concrete5: Beginner's Guide - Second Edition

3.5 (2 reviews total)
By Remo Laubacher
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Installing concrete5

About this book

concrete5 is an open source content management system (CMS) for publishing content on the World Wide Web and intranets. concrete5 is designed for ease of use, and for users with limited technical skills. It enables users to edit site content directly from the page. It provides version management for every page and allows users to edit images through an embedded editor on the page.

concrete5 Beginner’s Guide shows you everything you need to get your own site up and running in no time. You will then learn how to change the look of it before you find out all you need to add custom functionality to concrete5.

concrete5 Beginner’s Guide starts with installation, then you customize the look and feel and continue to add your own functionality. After you’ve installed and configured your own concrete5 site, we’ll have a closer look at themes and integrate a simple layout into concrete5. Afterwards, we’re going to build a block from scratch which you can use to manage a news section. We’re also going to add a button to our site which can be used to create a PDF document on the fly. This book also covers some examples that show you how to integrate an existing jQuery plugin.

concrete5 Beginner’s Guide is a book for developers looking to get started with concrete5 in order to create great websites and applications.

Publication date:
April 2013
Publisher
Packt
Pages
324
ISBN
9781782169314

 

Chapter 1. Installing concrete5

In this chapter, you'll learn what you need to get your own concrete5 site up and running on your local computer. You don't need to have a lot of experience with Apache, PHP, and MySQL configuration as we're going to use Bitnami, which will install all necessary components in almost no time.

Before you can start working with concrete5, you have to set up an environment, where you can test and play around with concrete5 to get used to it. If you have a web hosting account, you can install concrete5 there, but since that isn't always the case, we'll install everything concrete5 needs to work smoothly on your local Windows computer. We're assuming that you're working with Windows but instructions are available for those running Mac OS or Linux; most instructions work the same for all operating systems.

Bitnami installs a local web server, which we'll use to build and test the add-ons we're going to create. In the last chapter of this book, we're going to move the site from your local computer to a live web server.

 

Preparing for installation


There are a few tools you need, before you can start with the installation process. You probably already work with similar tools, but let's still make sure you've got everything before continuing.

Web browser

concrete5 supports all major browsers as long as you're working with an up-to-date version. Please note: you can create a website which is viewable with an outdated browser, but the in-context editing system won't work correctly, unless you're using a modern browser.

Whether you use Firefox, Chrome, Safari, or Internet Explorer doesn't really matter. concrete5 works with any recent browser with JavaScript capability, but it's recommended to use the latest browser version since most concrete5 community members test new releases with the newest browsers.

Text editor

Since we're going to edit PHP files you'll need a text editor. The requirements are quite small; you can pick almost any text editor you want. Just make sure it does support PHP syntax highlighting. Here are some possible editors:

There are a lot more text editors, as mentioned previously; you can use almost any editor you want. If you're familiar with another product, just go with it. You won't find anything in this book where you need a special text editor feature.

Archive utility

The same with the file archive utility, there are plenty of tools out there and if you want, you can use the in-built extraction utility of Windows or Mac OS. If you're looking for something more advanced, you can go with 7-Zip at http://www.7-zip.org/ or IZArc at http://www.izarc.org/; both are free and do a good job.

FTP client

Once more, there are lots of choices. You'll have to change file permissions later, so make sure your FTP client includes this option. A powerful and well known client is FileZilla, http://filezilla-project.org/. It's free as well and has a lot more features than we need.

 

Installing Bitnami


If you think you've found all the tools you'd like to use to create your website, you're ready to install Bitnami. Bitnami is a WAMP stack which provides a lot of different tools needed to run your favorite open source web application on your computer. WAMP is the short form for: Windows, Apache, MySQL, and PHP. The more common term is LAMP and describes the same, but for Linux. It's basically a combination of different applications.

There's a stack for concrete5 that installs everything including concrete5 in no time, but since we want to have a look at the process of installing concrete5 as well, we're going to use the WAMP stack. If you're working with Mac OS or Linux, check Bitnami MAMP, or LAMP; the process is pretty much the same for all the operating systems.

 

Time for action – installing Bitnami WAMP stack


concrete5 is a PHP application which uses PHP as its programming language in combination with a MySQL database. There are lots of possibilities to meet the requirements of concrete5. The preferred web server is Apache but IIS like any web server supporting PHP works as well, but only Apache is supported by the core team.

If you already have a server or a local Apache, PHP, and MySQL set up, you can skip this step and continue with the Downloading concrete5 section a few pages ahead. Otherwise, we are going to need to install Bitnami WAMP stack on your local computer by following these simple steps:

  1. Go to http://bitnami.org/stacks/ and select the MAMP stack for Mac OS, WAMP for Windows, and LAMP for Linux. On the next page, click on Installer and double-click the EXE as soon as it has been downloaded. You should see the following window or a dialog you have to confirm if files downloaded from the Internet aren't executed directly on your computer:

  2. Click on Next to get to the next installation screen. Here you'll see a screen with a number of preselected components. We don't need them, as we're going to install concrete5 as our Content Management System (CMS) and framework. phpMyAdmin can't be unselected, but that's okay.

  3. Click on Next once more and you'll be asked to specify the installation folder. You can keep the suggested value but feel free to change it if you prefer a different location. For this book, we used Version 5.4.10. Your version might be higher. Cause the WAMP folder will have the version number in the name, all follow-up.

  4. Click on Next again and you'll be asked to enter the MySQL password for the user root. It's important to keep it saved as this is the main user to access your database. You'll need this password later when we install concrete5.

  5. There are a few more screens; click on Next and you'll have to enter the port number for Apache as well as MySQL in the following screen. You can keep the port number 80 for Apache and 3306 for MySQL. However, it might be possible that another application is already using one or both of these ports, in which case you have to disable the existing application or use a different port number. It's not a problem if you change these numbers; just make sure that you remember the port numbers as you'll need them later when we install concrete5.

After you've clicked your way through all the screens and confirmed the launch process at the end, you should have a running MySQL server as well as a working Apache web server with all necessary components to run a concrete5 site on your local computer. Before we install concrete5, let's make a small change to the MySQL configuration. MySQL table names are not case sensitive on Windows. This will cause some problems if you want to move your site to a Linux server where MySQL is by default set up with case sensitive table names. If you don't feel comfortable with this change, it's not necessary, but recommended if you move your site to another server at some point.

To change this, if you work with concrete5, do the following:

  1. Go to the directory where you've installed Bitnami and open the folder mysql; it should look as follows:

  2. The my.ini file contains several settings related to MySQL. Open the file and insert the following line immediately after the mysqld section:

    lower_case_table_names = 0

    The mysql section should look like as follows:

  3. Now that MySQL is properly configured, locate the manager tool in your start menu. You should be able to find it in All Programs | Bitnami WAMP Stack | Manager tool and open it. You should see the following dialog:

  4. Select MySQL Database and click on the Restart button in the right pane. The buttons go gray. When the buttons return to their regular state the restart of MySQL is complete.

  5. If everything worked you should be able to open your browser and enter http://localhost/.

    Note

    If you had to change the port of your Apache service, make sure you append it to the hostname. Port number 80 is the default port to access websites and can be omitted. However, if you had to change to a different number like 8000, you have to use an address like this: http://localhost:8000/.

There's also one small change we have to make to the Apache configuration in order to make sure we can use a file called .htaccess, which allows concrete5 to change certain Apache configurations. Follow these steps:

  1. Go to the directory where you've installed Bitnami and open the folder apache2 and then conf.

  2. Within that directory, open the file called httpd.conf.

  3. Look for a section which starts with <Directory "C:/BitNami/wampstack-5.4.10-0/apache2/htdocs"> and then look after a property called AllowOverride. You'll have to change its value from None to All.

  4. The relevant part should look like as follows afterwards:

    DocumentRoot "C:/BitNami/wampstack-5.4.10-0/apache2/htdocs"
    <Directory "C:/BitNami/wampstack-5.4.10-0/apache2/htdocs">
        #
        # Possible values for the Options directive are "None", "All",
        # or any combination of:
        #   Indexes Includes FollowSymLinks SymLinksifOwnerMatchExecCGI MultiViews
        #
        # Note that "MultiViews" must be named *explicitly* --- "Options All"
        # doesn't give it to you.
        #
        # The Options directive is both complicated and important.Please see
        # http://httpd.apache.org/docs/2.4/mod/core.html#options
        # for more information.
        #
        Options Indexes FollowSymLinks
    
        #
        # AllowOverride controls what directives may be placed in.htaccess files.
        # It can be "All", "None", or any combination of the keywords:
        #   Options FileInfo AuthConfig Limit
        #
        AllowOverride All
    
        #
        # Controls who can get stuff from this server.
        #
        Require all granted
    </Directory>
  5. After you've saved the change, go to the Bitnami Manager tool, select the Apache Web Server process, and restart it.

What just happened?

The Bitnami WAMP Stack setup package installed a working web server, including PHP with the most commonly used modules and a MySQL database. This is what a lot of web applications need, and you can use this environment for other CMSs as well.

You've also had a quick look at one MySQL configuration file to avoid problems when moving your data to a Linux server. If you want to know more about this setting, the MySQL documentation is going to answer almost any question about table names: http://dev.mysql.com/doc/refman/5.5/en/identifier-case-sensitivity.html.

We also enabled support for .htaccess files in Apache. We'll need it later in this chapter when we enable pretty URLs.

Pop quiz – requirements for concrete5

Like any other software, concrete5 needs certain things to run. Try to answer the following questions.

Q1. Which of the following server-side programming language(s) has been used to build concrete5?

  1. PHP

  2. Microsoft ASP

  3. Java

  4. All of the above

Q2. Which of the following database(s) can you use with concrete5?

  1. PostgreSQL

  2. MySQL

  3. Oracle

  4. All of the above

Q3. Which of the following operating system(s) can you use to run concrete5?

  1. Microsoft Windows

  2. Mac OS X

  3. Linux

  4. All of the above

Q4. Name the web server(s) you can use to run concrete5:

  1. Microsoft IIS

  2. Nginx

  3. Apache

  4. lighttpd

 

Downloading concrete5


Your local web server is running, there's nothing else to prepare, and you are now ready to install concrete5. There are just a few more steps till you can log in to concrete5.

 

Time for action – downloading the latest version


Before we can install anything we have to get the latest concrete5 version from this URL: http://www.concrete5.org/developers/downloads/. After downloading the zip archive for concrete5, follow these steps:

  1. Remove all the files and directories from Bitnami in the directory at C:\BitNami\wampstack-5.4.10-0\apache2\htdocs.

  2. Open the ZIP archive, open the first directory in it, and extract all the files to C:\BitNami\wampstack-5.4.10-0\apache2\htdocs.

  3. After you've extracted the ZIP file you should see a structure like that shown in the following screenshot:

    Note

    At the time of writing, concrete5 5.6.1 was the latest version. You can download a newer version if available; changes in the installation process should be minor if there are any at all.

What just happened?

You've downloaded and extracted the concrete5 CMS files. Depending on your archive utility it might have happened that empty folders like updates, files, and others haven't been created. Make sure your structure looks like the one shown in the preceding screenshot.

Before we continue, a few words about the file structure you've just created. It's important that you understand the structure of concrete5 before you start working with it. It's helpful to have a clear understanding about the structure so you can find your files easily. You'll later see that all add-ons in the marketplace follow this structure. Using the suggested structure helps to keep the structure clean, no matter who builds the concrete5 site or add-on.

It might look a bit bulky to have so many folders in the root of your website, but you'll realize that it makes perfect sense to have this structure the more you work with concrete5. We'll have a closer look at some of the directories later in this chapter.

 

Creating an empty MySQL database


You must create an empty SQL database before you can install concrete5.

 

Time for action – creating a MySQL database


Use phpMyAdmin, which is included in the Bitnami stack, to create the database:

  1. Open http://localhost/phpmyadmin/ in your web server and you should see the following page:

  2. Log in with the user root and the password you've entered during the installation process of Bitnami.

  3. Click on the Users tab and then on Add user and enter the following values:

  4. Make sure you remember the password as you'll need it later when we install concrete5. Also make sure you select the radio button Create database with same name and grant all privileges. Click on Add user to confirm all values and continue creating the users and database.

  5. We just created a new user called concrete5 as well as a database with the same name. There's one more change we have to make before we can use the new database for concrete5. In the left-hand column, select the new database and then click on Operations:

  6. Change the value for Collation to utf8_general_ci and confirm the change by clicking on Go. With this step, we made sure that our database and therefore concrete5 can work with non-Latin characters such as umlauts and even Japanese or Chinese characters.

What just happened?

All the components are ready; Apache, including PHP, should be running and there's an empty MySQL database to host your concrete5 site.

Note

Please note: concrete5 can't be installed in a database which isn't empty!

 

Installing concrete5


We're finally ready to get to the installation of concrete5. Let's install it!

 

Time for action – installing concrete5


To install concrete5 follow these steps:

  1. Open your favorite browser and enter http://localhost/. You should see the following installation screen:

  2. There are a number of checks that make sure your environment supports all the necessary functions needed for concrete5 before installing it. Our Bitnami stack contains everything and therefore only shows you green icons. A few words about the required items:

    • PHP: Whenever possible, try to use the latest PHP version but make sure you run at least 5.2.4.

    • JavaScript enabled: The concrete5 interface uses a lot of JavaScript to make things easy and smooth to use. It won't be possible to edit any content if you disable JavaScript in your browser.

    • MySQL available: concrete5 needs a MySQL database; no other databases are supported.

    • Supports concrete5 request URLs: By default you'll see index.php in each concrete5 URL you open. To get rid of this, you need to have the Apache module mod_rewrite, which we're going to deal with later in this chapter.

    • Image manipulation available: There are a number of functions such as the creating of thumbnails, which need image libraries in PHP.

    • XML support: In concrete5 you'll have some XML files to describe data structures, which is why XML support is mandatory.

    • Writable files and configuration directories: Usually not a problem if you work with a WAMP stack on Windows. The web server must be able to write some files in your website's installation directory. We'll discuss this issue later, when we move the site to the production server.

    • Cookies enabled: Cookies are used in the log in process and must be enabled in your browser.

  3. Once you've managed to get every icon to be green, click on Continue to Installation to get to this screen:

  4. To install concrete5 you have to enter the following information:

    • Name Your Site: You can enter any name you want, which can be changed in the dashboard later.

    • Email Address: This is the admin mail address. Make sure it exists; this is where you'll receive a link to change the eventually forgotten admin password.

    • Password: This is the password for the user admin; make sure it's not too easy since admin is the main user with access to everything in concrete5.

  5. You will also have to enter the following database information:

    • Server: Since the database is running on the same machine as the web server, just enter 127.0.0.1. If you changed the default MySQL port from 3306 to something else like 3307, use 127.0.0.1:3307.

    • MySQL Username, MySQL Password, and Database Name: concrete5 or whatever you used when you created the user in phpMyAdmin.

  6. Next is the Sample Content section. If you select Sample Content with Blog, concrete5 will create a few pages to play around with. Enable this; if you're new to concrete5, it will create some nice pages where you can see the different blocks you can use to build your website. You can remove those pages later.

  7. If you've entered all the necessary information, click on Install concrete5!

What just happened?

A few seconds after you've clicked on Install concrete5 you should see a screen with a confirmation that your site is up and running. Navigate to the actual site available at http://localhost/ and you should see the following screen:

You might wonder why we've used 127.0.0.1 and not localhost when connecting to the MySQL database. Both values would work, but it can happen that localhost is much slower because it resolves to an IPv6 address on Windows, in which case you'd run into a timeout first because MySQL doesn't support IPv6.

The configuration file

After you've successfully installed concrete5 you'll find a file called site.php in the config directory. This is where the installation process has saved the information you've entered during the process. Here's how it looks:

<?php 
define('DB_SERVER', '127.0.0.1');
define('DB_USERNAME', 'concrete5');
define('DB_PASSWORD', 'concrete5');
define('DB_DATABASE', 'concrete5');
define('PASSWORD_SALT', 'C8MKVa6UZveKlYxFGvmFFqspBAOR5hLjMf9Xsz');
  • DB_SERVER, DB_USERNAME, DB_PASSWORD, and DB_DATABASE are obviously just database related. If the credentials to access your MySQL database have changed, this is where you have to modify them to make sure concrete5 can access your database.

  • PASSWORD_SALT: This is a random string used in combination with the password to generate the password hashes found in the user table. Salts are used to complicate dictionary attacks and even if they are useless without a password, you should still not publish a real password salt to keep your site safe.

Pop quiz – the configuration file

Q1. You'll often have to check or modify a few lines in the configuration file, so where can you find it?

  1. <concrete5 installation directory>\config.php

  2. <concrete5 installation directory>\config\config.php

  3. <concrete5 installation directory>\config\site.php

Disabling caching

There are a few different caching functions in concrete5 which can improve the performance of your site but also make things difficult if you keep changing the files. If you change a file without telling concrete5 anything about it, it will keep using the old values in the cache and not reflect the changes you've made. It's therefore recommended to disable all caches while working on a new site.

 

Time for action – disabling caching


Follow these steps to disable all caches in concrete5:

  1. Log in to concrete5 and type cache settings in the intelligent search box and select the first entry in the result.

  2. In the screen you can see now, select all the radio buttons labeled as Off and confirm the change by clicking on Save.

What just happened?

We just disabled the cache in concrete5 to avoid some potential problems with outdated results. In the last chapter when we upload the site, we'll enable the cache again!

Enabling pretty URLs

When you browse to a subpage in your concrete5 site you'll notice an odd thing in every URL; there's index.php in it like in http://localhost/index.php/about/. Every request to a page in concrete5 is processed by index.php, this has several advantages. It's easier to check the permissions because there's a single point where the page rendering happens.

But even with these advantages you probably don't like to see index.php in every URL. Luckily it's rather easy to change it if your web server supports rewrite rules. Our Bitnami stack does, but only because we previously changed AllowOverride to All in the relevant section before. Now that we have everything needed for pretty URLs, here's what we have to do to get rid of index.php.

 

Time for action – enabling pretty URLs


Follow these steps to get rid of the index.php from your URLs:

  1. Log in to concrete5.

  2. Click on the Intelligent Search box in the top-right corner.

  3. Type pretty, and while you type, concrete5 searches for the correct entry. Once found, click on Pretty URLs.

  4. Check Enable Pretty URLs and hit on Save; you should see the following screen:

  5. concrete5 should have created a file called .htaccess in the root of your website (C:\BitNami\wampstack-5.4.10-0\apache2\htdocs\.htaccess). This is the file where the rewrite rules are stored that remove index.php from the URLs.

What just happened?

Congratulations, you're done! concrete5 is running and you've also activated some options to improve the behavior of concrete5.

You've enabled pretty URLs, which uses the Apache mod_rewrite module to rewrite URLs. You can now open a subpage by entering http://localhost/about/ without having index.php in the address. In case you'd like to know more about this Apache feature, this is the official documentation:

http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html

.htaccess is a configuration file most commonly used by Apache to configure Apache modules on a directory level. It's a simple text file you can open with any text editor of your choice. If you haven't worked with Apache before, the content might be a bit confusing but concrete5 took care of it. You shouldn't have to modify anything on your own in this file.

Note

Pretty URLs can also be used with Microsoft IIS but you need to install a rewrite filter first.

If you want to try it on your own, you can find a solid and free rewrite filter at this address: http://iirf.codeplex.com/.

File and directory structure of concrete5

As mentioned previously, there are a lot of folders in concrete5. Most of these top level folders are empty—resist the temptation to delete these as they are required for customizations. To give you a head start, here's a short list of the most important folders:

Folder

Explanation

blocks

You can find custom blocks and block templates in this folder. You'll learn more about blocks in the next few chapters.

concrete

Probably the most important part, this is where all core files, the actual CMS is located. Never update anything in this folder.

config

The folder where concrete5 puts the configuration files.

files

The file manager stores your files in this directory.

packages

This is where you have to put add-ons if you install them manually.

updates

The concrete5 auto update feature puts the new core in this directory. Never update anything in this folder.

There are a few more folders but you probably won't need them unless you dive deep into concrete5. There's one important thing to remember when working with concrete5: The directory concrete looks a lot like the root directory, but never change anything in the concrete directory. You'll find several directories in both places. That's because you can override a single file by placing it in the same structure in the top level.

Here's one example without going into too much detail. Later in this book, we're going to work with a block called content block, a few times. This block basically adds a formatted text to your page. The actual output is printed from this file: /concrete/blocks/content/view.php. How can we change that file without causing any problems with updates? Simply copy the file and place it here: /blocks/content/view.php. The structure is the same; there's just no concrete in the path. You'll have to create some directories first, but at the end, you just copy and paste a file and can then change its content.

Dispatcher process

As we've mentioned previously, every request to a page in concrete5 is forwarded to index.php. You might be able to see this by looking at the URL which starts with index.php, but if you enabled pretty URLs, this is hidden by some Apache mod_rewrite instructions. No matter which option you're using, index.php is always involved.

The actual logic is located in a file included by index.php, which you can find in concrete/dispatcher.php. Every time you request a page, the code of the dispatcher is executed. If you want to dig deeper into concrete5, you'll want to have a closer look at this file at some point. For now, let's just have a look at this quick summary of what happens in the dispatcher:

  • Initializing the error handling

  • Fetching all constants and configurations necessary for the site

  • Loading the database classes and establishing a connection

  • Creation of a session necessary to remember things such as login information

  • Loading all settings related to localization

  • Checking events that have to be run at some point

  • Parsing of the URL and fetching the correct object from the database related to the current URL

  • Rendering of the page object as well as all its blocks

You can find more information about the dispatcher flow on this page: http://www.concrete5.org/documentation/introduction/dispatcher-and-application-flow/.

 

Summary


You've reached the end of the first chapter!

  • You should now have a working concrete5 installation from where you'll learn how to work with concrete5

  • In case you have to check or modify your concrete5 configuration, you should know where to find the files

  • We've looked at the requirements to run concrete5

  • All the tools you'll need to go through this book should be installed on your computer

  • We're going to use this test site to build our own demo site including some block customization

About the Author

  • Remo Laubacher

    Remo Laubacher grew up in Central Switzerland in a small village surrounded by mountains and natural beauty. He started working with computers a long time ago and then, after various computer-related projects, focused on ERP and Oracle development. After completing his BSc in Business Administration, Remo became a partner at Ortic, his ERP and Oracle business, as well as a partner at Mesch web consulting and design GmbH. At Mesch—where he's responsible for all development-related topics—he discovered concrete5 as the perfect tool for their web-related projects and has since become a key member of the concrete5 community. You can find his latest publications on http://www.codeblog.ch/.

    He has also authored concrete5 Beginner's Guide and Creating concrete5 Themes.

    Browse publications by this author

Latest Reviews

(2 reviews total)
The book is for an older version of Concrete5. there's nothing available for the latest version of C5
Welcome on board fasten your seat belt. Ready to fly.
Book Title
Access this book and the full library for FREE
Access now