Theming in Concrete5

Oct 25, 2010
Eric Aguayo

Concrete5 is an Open Source PHP based CMS which is gaining more acceptance among developers, site builders and content administrators. This is largely due to Concrete5’s In-context editing capabilities as well as other features which make the process of building a website a fun task. Building and managing custom themes in Concrete5 is pretty straightforward. In Concrete 5 you can have themes and page types. At the beginning it can be confusing but Page Types are just different templates and layouts for the same theme. On the Concrete5 website there is a simple guide that provides very detailed steps on how to start building a basic theme from a standard HTML template. I am just going to give a little summary here on how this can be done.

You can start building a theme by coping one of the already built-in themes in Concrete5 but for most cases you may already have a prototype theme with static HTML content and want to use it as start point for start building your theme. Follow these steps:

  • First you have to change the extensions of every html page to php. These will automatically become your page types. Make sure that at least one template is renamed default.php which will be used by most of the pages of your site.
    • Note: If you have single pages, which means they have their own layout and content, it is better not to create a page type, instead generate a generic template called view.php and print a variable named $innerContent anywhere you want the single pages content be displayed. This template will be applied for other pages such as “Page not found” or “Forbidden”
    • Next, you have to load all your stylesheets through the following function  which will allow you to customize the stylesheets throughout the CMS

<?=$this->getStyleSheet('your_stylesheet_name.css')?>

  • Add the following function code to add the correct path to all the referenced files and images in the HTML code
  • Replace all the static content that you want to use to place dynamic content with the following PHP code that defines a region.
<?=$this->getThemePath()?>

<?php

    $a = new Area('Region Name');

    $a->display($c);

?>

         You can place as many of these, as you want, just replace the “Region Name” with the proper region names. Default region names are: Header Nav, Header, Main, Sidebar.

  • Replace the title tag with the following code so the administration menu can be loaded on the top of the screen
  • Add a description.txt file with the theme title on the first line and the description on the second line. This will be used to identify your theme on the Dashboard. Also, if you have a little more time you can add a thumbnail image of size 120x90 and named thumbnail.png to allow content editors and site builders to easily identify your theme.
  • Put all the files within a folder with the name of the theme and copy the whole folder into the themes folder, located on the CMS root folder (e.g. /themes/my_theme).
  • Now, go into the CMS and install and activate the theme on the themes section of the dashboard. After installing go to the “Inspect Element” section to select the templates to be added as page types. Finally click on “Activate” to apply the theme on all the pages of the site.
<?php 
    Loader::element('header_required'); 
?>


After you have the theme enabled and applied you can follow some additional steps that will help you to customize your theme a bit further

  • Add CSS comments before and after each of the CSS declarations that you want to be customized on all your CSS files. All comments entries needs to be prefixed by “customize_” in order to make them customizable by the Concrete5. Currently there are only two selectors on the CMS, one for color and other for Font but we can expect to have more widgets on the future. Some examples of these CSS comments are:
    • /* customize_body */
    • /* customize_link*/
    • /* customize_link_hover */
    • Add single pages to the “single_pages” directory located on the root of the project. These pages will just need to have the inner content to be displayed on the view.php template file.
    • You can apply specific themes individually to single pages or specific paths by setting this on the config/site_theme_paths.php file. In this file you will find some examples on how to do this.

A further recommendation is to go through one of the built-in themes in Concrete5 that can be found in the concrete5/themes folder and go through the set of files in there so you get familiar with some of the best practices and how themes can be structured to simplify things in the long term. Also take a look at the concrete/libraries/view.php file which contains several functions that can be used within the template files. In addition, to keep your stylesheets interfering with Concrete5 stylesheets use an “id” property within the <body> tag or a <div> tag that encloses all the page components. Finally, if you want to share your theme to the world you can submit it to the Concrete5 marketplace. Here is a screenshot of a theme I made from a template I took from freewebsitetemplates.com which took me just minutes to integrate with Concrete5 CMS.




Related Blog Posts: