Creating Your Own Theme

Exclusive offer: get 50% off this eBook here
concrete5 Beginner's Guide

concrete5 Beginner's Guide — Save 50%

Create and customize your own website with the Concrete5 Beginner's Guide

$26.99    $13.50
by Remo Laubacher | June 2013 | Beginner's Guides Open Source Web Development

In this article we're going to change the layout of the site we've created. To achieve this, we will convert an HTML file into a concrete5 theme. This means that we have to replace and insert a few lines of PHP code to make things a bit more dynamic. However, you'll see that the basic conversion process is rather easy and quick; creating a concrete5 theme does only require very little PHP skill and almost no time.

Some code snippets are just modifications to other snippets in this article. If you want to re-create the theme code on your own, you have to follow each step and follow the instructions precisely. If you're in a hurry, at the end of the article you'll find a link from where you can download the final code used in this article.

In this article by Remo Laubacher, author of concrete5 Beginner's Guide - Second Edition, you'll learn how to create concrete5 themes by going through the follow topics:

  • A simple example showing you how to convert an existing HTML to a concrete5 theme

  • An explanation and more examples about page types

  • A number of snippets that can help you to get more out of your theme

  • An example that shows you the use of attributes to add a page-specific background picture

  • How to use customizable styles to allow certain CSS properties to be changed in the dashboard

(For more resources related to this topic, see here.)

Starting with a new layout

Before we start creating a concrete5 theme we need a layout. In this article, we're going to use a simple layout without any pictures to keep the code as short as possible—it's about concrete5, not about HTML and CSS.

If you don't have the time for an exercise, you can use your own layout. With good knowledge about the basic technologies of concrete5, you should be able to amend the instructions in this article to match your own layout. If you don't feel very comfortable working with PHP you should probably use the printed HTML code in this article.

Here's a screenshot of what our site is going to look like once we've finished our theme:

While this layout isn't very pretty, it has an easy structure; navigation on top and a big content area where we can insert any kind of block we want. In case you're using your own layout, try to use one with a simple structure; navigation on top or on the left with one big place for the content, and try to avoid Flash.

The HTML code

Let's have a look at the HTML code:

<!DOCTYPE html>
<html lang="en">
<head>
<title>concrete5 Theme</title>
<meta http-equiv="Content-Type" content="text/
html;charset=utf-8" />
<style type="text/css" media="screen">@import "main.css";</
style>

</head>
<body>
<div id="wrapper">
<div id="page">
<div id="header_line_top"></div>
<div id="header">
<ul class="nav-dropdown">
<li><a href="#">Home</a></li>
<li><a href="#">Test</a></li>
<li><a href="#">About</a></li>
</ul>
</div>
<div id="header_line_bottom"></div>
<div id="content">
<p>Paragraph 1</p>
<p>Paragraph 2</p>
<p>Paragraph 3</p>
</div>
<div id="footer_line_top"></div>
<div id="footer"></div>
<div id="footer_line_bottom"></div>
</div>
</div>
</body>
</html>

There are three highlighted lines in the preceding code:

  • The CSS import: This is to keep the layout instructions separated from the HTML elements; we've got all the CSS rules in a different file named main.css. This is also how almost all concrete5 themes are built.

  • The header block contains the navigation. As we're going to apply some styles to it, make sure it has its own ID. Using an ID also improves the performance when using CSS and JavaScript to access an element, as an ID is unique.

  • The same applies to the content block. Make sure it has a unique ID.

Most web technologies we use nowadays are standardized in one way or another. Currently, the most important organization is W3C. They also offer tools to validate your code.

Checking your code is never a bad idea. Navigate to http://validator.w3.org/ and enter the address of the website you want to check or in this case, as your website isn't accessible by the public, click on Validate by Direct Input and paste the HTML code to see if there are any mistakes. While it should be fairly easy to produce valid HTML code, things are a bit tricky with CSS. Due to some old browser bugs, you're often forced to use invalid CSS rules. There's often a way to rebuild the layout to avoid some invalid rules but often this isn't the case—you won't be doomed if something isn't 100 percent valid but you're on the safer side if it is.

CSS rules

As mentioned earlier, all CSS rules are placed in a file named main.css. Let's have a look at all CSS rules you have to put in our CSS file:

/* global HTML tag rules */
html, body, div, pre, form, fieldset, input, h1, h2, h3, h4, h5, h6,
p, textarea, ul, ol, li, dl, dt, dd, blockquote, th, td {
margin: 0;
padding: 0;
}
p {
margin: 5px 0px 15px 0px;
}
html {
height: 100%;
}
body {
background-color: #989898;
height: 100%;
}
/* layout rules */
#wrapper {
margin: 0 auto;
width: 980px;
text-align: left;
padding-top: 35px;
}
#page {
background: #FFFFFF;
float: left;
width: 960px;
padding: 5px;
-moz-box-shadow: 0 0 15px black;
-webkit-box-shadow: 0 0 15px black;
box-shadow: 0 0 15pxblack;
border-radius: 10px;
}
/* header */
#header {
background: #262626;
border-radius: 10px 10px 0px 0px;
height: 75px;
}
#header_line_top {
background: #262626;
height: 0px;
}
#header_line_bottom {
background: #e64116;
height: 3px;
}
/* content */
#content {
min-height: 300px;
padding: 30px;
color: #1E1E1E;
font-family: verdana, helvetica, arial;
font-size: 13px;
line-height: 22px;
}
/* footer */
#footer {
background: #262626;
height: 75px;
border-radius: 0px 0px 10px 10px;
}
#footer_line_top {
background: #e64116;
height: 3px;
}
#footer_line_bottom {
background: #262626;
height: 0px;
}
/* header navigation */
#header ul{
margin: 0px;
padding: 20px;
}
#header ul li {
float: left;
list-style-type: none;
}
#header ul li a {
margin-right: 20px;
display: block;
padding: 6px 15px 6px 15px;
color: #ccc;
text-decoration: none;
font-family: verdana, helvetica, arial;
}
#header ul li a:hover {
color: white;
}

concrete5 Beginner's Guide Create and customize your own website with the Concrete5 Beginner's Guide
Published: March 2011
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

Converting HTML and CSS to a concrete5 theme

We've got our HTML and CSS files, and now we want them to be part of a new concrete5 theme with two editable areas, one for the content and one for the header. We will ignore the footer for now.

Time for action – creating the concrete5 theme header

Carry out the following steps:

  1. Directly in the root of your site, in the themes directory, and in case of bitnami in the htdocs directory, create a new directory named c5book, but any other name is fine as long as you're using letters and underscores, and avoid the special characters available on your keyboard.

  2. Create a thumbnail of your site measuring 120 x 90 pixels and save it as thumbnail.png within your theme directory.

  3. Create a file named description.txt in the new directory by using a text editor, such as Notepad.

  4. Open the file and enter the name of the theme in the first line and the description on the second line. Its content should look like the following:

    c5book Theme
    Concrete5 Theme by Remo Laubacher

  5. Save and close the file. You should have a structure like the one shown in the following screenshot:

  6. As we're going to create several page layouts sharing the same header and footer, let's create a directory named elements for these common files.

  7. We are going to split a part of the HTML code into a file called header.php. To do this, create a file named header.php in a new subdirectory called elements and insert the preceding HTML code, including the DIV element with the ID header_ line_bottom, but look closely as we had to change a few lines.

    <?php
    defined('C5_EXECUTE') or die('Access Denied.');
    ?>
    <!DOCTYPE html>
    <html lang="<?php echo LANGUAGE?>">
    <head>
    <meta http-equiv="Content-Type" content="text/
    html;charset=<?php echo APP_CHARSET ?>" />
    <link rel="stylesheet" media="screen" type="text/css"
    href="<?php echo $this->getStyleSheet('main.css') ?>" />
    <?php Loader::element('header_required'); ?>

    </head>
    <body>
    <div id="wrapper">
    <div id="page">
    <div id="header_line_top"></div>
    <div id="header">
    <?php
    $a = new GlobalArea('Header Nav');
    $a->display($c);

    ?>
    </div>
    <div id="header_line_bottom"></div>

What just happened?

There are a few highlighted lines in the preceding code, which we modified in order to use our HTML code in concrete5:

  • The first line makes sure you can't directly call our file to ensure that everything is running in the concrete5 context.

  • The next line specifies the content type and uses the constant APP_CHARSET to get the correct encoding, which by default is utf8.

  • The next highlighted line includes our CSS files the proper concrete5 way. You can avoid the PHP function if you want to but you'll get access to a nice concrete5 feature if you use $this->getStyleSheet(); thanks to which you can easily change the properties of your CSS file in a nice interface without touching a single line of code. More information on this is available in the Creating customizable themes recipe.

  • Loader::element makes sure the concrete5 in-site editing toolbar is included. This is necessary to display the in-site editing toolbar, once you're logged in to your site.

  • The last highlighted line defines the area where blocks can be placed. The string Header Nav is what the user will see while editing the page. Please note that we've used GlobalArea and not Area. Using GlobalArea adds an area of which the content is identical on all pages using this area. If you use Area, you'll get an editable area which has a different content on each page.

We've split a part of our HTML code into a new file named header.php. While this isn't mandatory, most themes follow this procedure and you probably should too, as long as you don't have any good reason not to.

Even if you just have one page layout, you never know what will happen next and keeping your files clean and short makes them easier to read as well.

Let's create the next element, the footer!

Time for action – creating the concrete5 theme footer

Carry out the following steps:

  1. In the elements directory, create a new file named footer.php.

  2. From the original HTML file, copy everything starting at footer_line_top to the end of the file and insert it in the new file.

    <?php defined('C5_EXECUTE') or die('Access Denied.'); ?>
    <div id="footer_line_top"></div>
    <div id="footer"></div>
    <div id="footer_line_bottom"></div>
    </div>
    </div>
    <?php Loader::element('footer_required'); ?>
    </body>
    </html>

  3. There are only two lines we have to insert. The first one is again just a protection to disallow direct calls to our file. The second one is a placeholder for a snippet you can specify in the concrete5 dashboard. This is often used for a JavaScript statistics tracking code as well as code files you want to load after the content is rendered. It's also used to load the editing toolbar and therefore mandatory.

  4. Save and close the file; there's nothing else to do there.

What just happened?

We created another shared element which holds the code for our footer. There's not much code in it as we're trying to keep things simple and therefore we are not putting any content in the footer.

In case you create more theme templates, you can use this footer for all of them, which makes sure that if you want a login link at the bottom you can do it once and it will appear on all page types and therefore all pages as well.

Time for action – creating a page template

Carry out the following steps:

  1. Go back to the directory where you've created description.txt and create another file named default.php.

  2. Insert the content DIV along with some PHP code:

    <?php
    defined('C5_EXECUTE') or die('Access Denied.');
    $this->inc('elements/header.php');
    ?>
    <div id="content">
    <?php
    $b = new Area('Main');
    $b->display($c);
    ?>
    </div>
    <?php $this->inc('elements/footer.php'); ?>

What just happened?

Just like we did in the header, there's a line at the top to avoid direct calls and a few more lines of code to insert another editable area named Main. In all the themes you can find in the marketplace there's an area called Main. By following this rule, concrete5 makes it possible to switch between themes without losing the content.

As you can see, the creation of the last file was also quite easy. There isn't a lot left from the original HTML code. However, having a small default.php file is also quite helpful, as you sometimes copy this file in case you need more page templates.

Time for action – creating more page templates

Carry out the following steps:

  1. concrete5 themes usually ship with a few default templates, one of them usually being left_sidebar. Let's create it by copying default.php in a new file named left_sidebar.php.

  2. We're going to add two sub DIV elements to hold our left and main column:

    <?php
    defined('C5_EXECUTE') or die('Access Denied.');
    $this->inc('elements/header.php');
    ?>
    <div id="content">
    <div id="left-sidebar">
    <?php
    $as = new Area('Sidebar');
    $as->display($c);
    ?>
    </div>
    <div id="main">
    <?php
    $b = new Area('Main');
    $b->display($c);
    ?>
    </div>
    <div class="clear"></div>

    </div>
    <?php $this->inc('elements/footer.php'); ?>

  3. As we've added new HTML elements, we also have to insert a few more CSS rules in a new file called main.css right in the root of your theme where you've created description.txt before. These are the rules you need:

    #left-sidebar {
    float: left;
    width: 250px;
    margin-right: 30px;
    }
    #main {
    float: left;
    width: 600px;
    }
    .clear {
    clear: both;
    }

  4. Let's create another file named right_sidebar.php. Call the sidebar container right-sidebar and switch the two DIV elements. Some more CSS rules are necessary as well:

    #right-sidebar {
    float: left;
    width: 250px;
    margin-left: 30px;
    }

What just happened?

We've created two more page templates for our site. If you move your mouse cursor on the Edit button, you can click on Design in the popup menu and then select the left or right sidebar template to change the location of the sidebar.

While you probably remember the layouts you can use to split an area into columns, it might be beneficial to create page types as it is easier for the user to specify the layout when creating a new page. However, you're of course free to avoid additional templates by splitting an area into several columns. It's up to you; whatever you like!

Installing your theme

Once you've created all the files, you probably want to see how it looks on your site.

Time for action – installing theme

Carry out the following steps:

  1. Type Themes into the intelligent search box and select the first entry in the search result.

  2. Your new theme should appear at the end of the installed themes in the section Themes Available to Install. Click on Install, as shown in the following screenshot:

  3. After you've installed the theme, you'll see a screen with all page types available in your theme. Click on Return to Themes to get back to the previous screen.

  4. Your new theme is installed now, but it's not activated yet. Click on Preview if you want to look at it before activating it or just click on Activate to use it right away. You'll have to confirm this action.

What just happened?

We've installed our new theme which has been converted from a static HTML page. A theme is nothing but a bunch of files in a single directory, but it won't be available in concrete5 unless you follow the preceding steps.

PHP constants and functions

The following subarticle isn't one you have to go through step by step, it's rather a collection of small snippets that you can use to improve your concrete5 theme or block. The code snippets won't have any purpose in the upcoming articles—you can implement them if you like, but you don't have to.

By default, concrete5 sets a bunch of constants that you can use when you create a theme but also a block or any other type of add-on. A lot of these constants are used internally and don't have any use for you when building themes or add-ons, but some are helpful and the rest give you at least an impression about a few internal workings of concrete5. There are also lots of functions to check the state of the current page, get information about the user, and much more.

While the basic template we've created works well for most situations, there are several things you can do within a template and not only in the user interface. The code lines aren't real life examples; they just give you a hint about things you can do once you run into a problem.

Again, instead of publishing a complete list of constants you might need, we're going to look at a simple way to get a list which will always show you all constants, no matter what version of concrete5 you're using.

Time for action – getting a list of available constants

Carry out the following steps to get a list of the available constants:

  1. Open default.php from your theme in a text editor.

  2. Look for the following PHP block:

    <?php
    $b = new Area('Main');
    $b->display($c);
    ?>

  3. Before the closing PHP tags ?>, insert a few more lines so it looks like the following:

    <?php
    $b = new Area('Main');
    $b->display($c);
    echo '<pre>';
    print_r(get_defined_constants(true));
    echo '</pre>';

    ?>

  4. Open a page of a type without a page template. Remember, we've created a template for the left and right sidebar. Pick the full width for example, otherwise the inserted code won't be executed.

  5. The output will contain a huge list of constants categorized by modules. At the end there's a category named user; these are the constants which are not coming from PHP itself but rather from concrete5. Look at them and you'll find a lot of constants related to directories, URLs, locales, and more. You don't need all of them but they could be useful some day and give you some insights about the internals of concrete5.

What just happened?

Even if you've built software for a long time you'll still find methods, properties, and a lot more you haven't used before. You can try to remember all of them, but you'll probably have a hard time doing so. The preceding code can help you to get some information about the constants used in a PHP project.

Time for action – listing all available functions

As with most classes, you often have to call a method to get a value and not directly access a property as the method might do some additional checks you'd lose if you'd access the property directly. Let's start with what we have got to do to get a list of all available functions:

  1. To get a list of all available methods without looking into the code, just add the following code where you'd like to get more information. Let's put it in default. php again like we did with the constants:

    <?php
    $b = new Area('Main');
    $b->display($c);
    echo '<xmp>';
    $reflection = new ReflectionClass($this);
    print_r($reflection->getMethods());
    echo '</xmp>';

    ?>

  2. This will print a long list where you can find all available methods next to the property named name:

    Array
    (
    [0] =>ReflectionMethod Object
    (
    [name] =>getInstance
    [class] => View
    )
    [1] =>ReflectionMethod Object
    (
    [name] =>getThemeFromPath
    [class] => View
    )

What just happened?

The Time for action – listing all available functions section illustrated all the available methods in the current context, helping you to get a first impression about the available methods. The following two Time for action sections can be used in other PHP-based projects.

You won't get a nice explanation about the constants or methods, but you'll still know if something is available, helping you to be sure that you're on the right track. However, once you have found the correct class, you can open the following page to get more information about the methods and properties of it:http://www.concrete5.org/api/.

Time for action – checking for edit mode

There are situations where you have to know if the user is currently editing the page. For example, the in-site editing toolbar sometimes causes problems because it shifts down a few elements. If your layout has been built using absolutely positioned layers, you probably have to move down the layers a bit in case the toolbar is visible.

The current page object can be accessed by using the global variable $c, which contains a method that returns true if the page is currently in edit mode.

  1. Open default.php of your theme or any other page type template.

  2. Look for the code new Area and right before it, insert the highlighted lines as shown here:

    <?php
    if ($c->isEditMode()) {
    echo 'You are editing this page at the moment!';
    }

    $b = new Area('Main');
    $b->display($c);
    ?>

What just happened?

By calling the isEditMode() method on the current page, which you can access by $c, you can check if the user is currently editing the page. This offers you some flexibility in case a layout or block causes problems in edit mode. This simple check makes it easy to change, hide, or disable certain functions on your site in case it's necessary.

Time for action – hiding content from anonymous visitors

Carry out the following steps:

  1. We've already seen how we can hide a page or even a block from a user by using the concrete5 user interface in combination with the advanced permission mode.

  2. Let's hide content by using some code. Put the following lines in default.php:

    <?php
    $u = new User();
    if ($u->isLoggedIn()) {
    echo '<a href="/secret/">Secret key to world domination</a>';
    }

    $b = new Area('Main');
    $b->display($c);
    ?>

What just happened?

The preceding two Time for action sections can both be used to change the content by adding some logic to the template.

While we've put both of them in a theme template, they are not only restricted to this location. You can use the command new User() almost anywhere in concrete5. The method $c->isEditMode() also works in several places: theme templates, page list templates, or autonav templates.

Time for action – restricting numbers of blocks per area

By default, you can place as many blocks in an area as you want. However, there are situations where a restriction to a single block might have some advantages.

In an absolute positioned layout, it can happen that the Add To Main link overlaps with another area or you simply want to make sure that there's just a single image block in the header area. Have a look at the following two steps to add this restriction:

  1. Open the theme template where you'd like to add a restriction to the number of blocks. default.php does the job again.

  2. Look for the PHP part where you specify the area and insert the highlighted line shown here:

    <?php
    $b = new Area('Main');
    $b->setBlockLimit(1);
    $b->display($c);
    ?>

What just happened?

By simply adding one more line to our area, we made sure that only one block can be inserted. This nifty little method makes sure that the interface stays clean and consistent. In case you've made a wrong decision, no worries—the line can be removed without any problems at any time.

Time for action – inserting a block wrapper in an area

While you can do a lot with the CSS layout feature in concrete5, it might happen that you have to surround your block with some HTML code to style your site the way you want it to look. There's a simple way to add some wrapping code around each block in an area, as follows:

  1. Once more, open a theme template like default.php and look for the place where you create the area.

  2. Replace the PHP block using the following snippet:

    <?php
    $b = new Area('Main');
    $b->setBlockWrapperStart('<div class="mainBlock">');
    $b->setBlockWrapperEnd('</div>');

    $b->display($c);
    ?>

What just happened?

The two lines of PHP code we've inserted in the preceding snippet simply surround each block in the Main area with a DIV element.

When you now create your CSS files, you can access them using .mainBlock. A few lines in your CSS file like the following will add a line at the bottom of each block:

.mainBlock {
border-bottom: 1px solid black;
}

Working with page attributes

concrete5 ships with a few default attributes for pages, users, and files. You can easily add new attributes to these objects to attach different kinds of metadata to them. You can use attributes to create dynamic elements in your theme without creating your own block.

A few things you can do with the default attributes:

  • Exclude a page from the navigation

  • Specify metadata for search engines

  • Exclude a page from the search index

These are just a few of the things you can do by default, without adding a new attribute. However, what can we do if we create our own attributes?

Imagine we'd like to have a different background picture on each page. We could create a block for this, but we can also use an attribute and a little modification to our theme.

Time for action – using attributes to set background picture

Carry out the following steps:

  1. Go to the dashboard and click on Attributes in the Pages and Themes section.

  2. At the bottom, click on the Add Attribute drop-down box and select Image/File, then click on the Add button.

  3. In the next screen, enter background for Handle and Background Picture in Name. The handle is what you'll need to access your attribute from the code. You can see this on the following screenshot:

  4. Click on Add. The Background Picture attribute has been added to the available attributes.

  5. Go back to the Dashboard and click on Page Types.

  6. Click on Settings next to the first page type.

  7. In the list of attributes, check the checkbox next to Background Picture. This ensures the attribute is displayed by default for each page of this type.

  8. Click on Save.

  9. Do the same for all page types where you'd like to use this attribute.

  10. Go to the home page by clicking on the Return to Website button on top.

  11. Move your mouse cursor over the Edit button and click on Properties and select the second tab, Custom Attributes. This is where you can find all the attributes on a page. Our attribute is already in the list of selected attributes because we've added it to our page type before.

  12. Use the file selector next to our new attribute to select a new background picture for the current page.

  13. Click on Save and the selected picture will be assigned to our page.

What just happened?

We've created a new image attribute, which we've used to assign a background picture to a page of our choice.

This procedure works with every attribute, text, number, dates, and so on. You can use them in the same way if you want to manage page-specific metadata.

It's now possible to assign pictures to a page, but nothing happens with this data at the moment. We've got to add a few lines of code to display the new background picture.

Time for action – accessing attribute data from a template

Carry out the following steps:

  1. Open header.php of your theme in your editor. You can find it in /themes/ c5book/elements.

  2. Remove the <body> tag; we're going to replace it with some code, which includes the background picture.

  3. Insert the following code right where you've removed the <body> tag:

    <?php
    $backgroundAttribute = $c->getAttribute('background');
    if ($backgroundAttribute) {
    $backgroundFile = $backgroundAttribute->getRelativePath();
    echo "<body style=\"background:url('{$backgroundFile}')\">";
    } else {
    echo "<body>";
    }
    ?>

  4. Reload your page and you'll see the new background picture instead of the color gray.

What just happened?

We removed the static body tag and inserted some PHP code to fetch the attribute value. This works by using $c->getAttribute(). $c is a global variable referring to the current page. You can use $c = Page::getCurrentPage(); if you prefer to use a method to get the current page object.

The parameter of getAttribute() is the handle of the attribute you created. You can use it to access any page attribute you want.

Inserting blocks in templates

Putting blocks in areas is a rather simple task, but if your users aren't experienced computer users, it might be even too easy. What if they accidentally delete or modify the autonav, the navigation block? It would break the site very quickly.

You can enable the advanced permission mode, which allows you to specify permissions on blocks and areas. However, enabling this mode can give you too much power and makes managing the site more complicated. While this shouldn't be a problem once you're more familiar with concrete5, there's another way you might want to check out—put blocks in your templates!

Time for action – replacing the header area with a template block

Carry out the following steps:

  1. Open elements/header.php from your theme in your text editor.

  2. Look for the following highlighted lines and remove all of them:

    <div id="wrapper">
    <div id="page">
    <div id="header_line_top"></div>
    <div id="header">
    <?php
    $a = new GlobalArea('Header Nav');
    $a->display($c);
    ?>

    </div>

  3. Next, insert the following PHP code instead:

    <?php
    $autonav = BlockType::getByHandle('autonav');
    $autonav->controller->orderBy = 'display_asc';
    $autonav->controller->displayPages = 'top';
    $autonav->render('templates/header_menu');
    ?>

  4. Save the file and reload your page, the header navigation is still there, but if you switch into edit mode, there's nothing you can edit in the header navigation.

What just happened?

By replacing the area with the preceding small code, we've put the autonav block directly into the template, disallowing any modification in the user interface.

We've set a few properties to specify the intended autonav behavior and called render with the argument templates/header_menu. This makes sure we're using the header menu template which you can find in concrete/blocks/autonav/templates. Please note, there's no .php extension when calling the render method.

If you wanted to use the default template of a block, just specify view:

$autonav->render('view');

Putting blocks in a template using this procedure works for almost any block, but how do you know what kind of properties they have?

Time for action – finding autonav block properties

There are several tools doing a similar job, the developer console of Chrome or Safari, Firebug for Firefox, or the built-in inspector of Firefox. Open Chrome or Safari and follow these steps to find the block properties:

  1. After the installation procedure has succeeded, log in to your concrete5 test site http://localhost/login/.

  2. Navigate to the home page and switch to the edit mode. Click on Add to Main and Add Block.

  3. Pick the block you want to find the properties for. Autonav is a good choice as it has a few properties you might not find very intuitive.

  4. When the block edit dialog is visible, right click on the first drop-down list, as shown in the following screenshot:

  5. After you've clicked on Inspect element, the console will show up and automatically select the element named orderBy.

  6. Click on the arrow on the left of the selected element and you'll see the following:

What just happened?

Using the Chrome developer console, we discovered where we can quickly find block properties. In our case, the sort order in an autonav block is defined using a property called orderBy and values such as display_asc and chrono_desc.

concrete5 block edit dialogs work like a common HTML form and therefore use tags such as input and select to update the block properties.

While this might be an uncommon kind of documentation, it will work with blocks which have been released a minute ago, even if the developer didn't take the time to write the documentation.

In the case of autonav, a complete example with all available properties would look like the following:

$autonav = BlockType::getByHandle('autonav');
$autonav->controller->orderBy = 'display_asc';
$autonav->controller->displayUnavailablePages = 1;
$autonav->controller->displayPages = 'top';
$autonav->controller->displaySubPages = 'relevant';
$autonav->controller->displaySubPageLevels = 'enough_plus1';
$autonav->render('view');

Time for action – specifying block templates in an area

Sometimes you might want to set a default block template for an area. This might happen if the default template doesn't work at all and the customer would have to select a custom template for each block he/she adds. Let's save his/her time and specify a block template in our template.

  1. Open a theme template like default.php.

  2. Look for the PHP block which defines an area and insert the highlighted line from the following snippet:

    <?php
    $b = new Area('Main');
    $b->setCustomTemplate('autonav', 'templates/header_menu');
    $b->display($c);
    ?>

What just happened?

The single line of code that we've added to our theme templates makes sure that for every autonav block where no template has manually been specified in the user interface, the header_menu template is used.

While setting header_menu for all autonav blocks is probably a bit useless, you'll learn how to build your own block templates in the next article. Once you've created your own templates, it's just a matter of time till you'll realize that overriding the default block template can be quite handy.

Applying a theme to a single page

There are a few pages in concrete5 that you don't have to create on your own. They exist whether you like it or not but luckily the chances are you'll like them.

Assume you're using the existing login page you can find at http://localhost/login/ to grant some visitors access to the VIP section on your page. This works out of the box but it doesn't look like it should, as it still has the classic concrete5 look and doesn't look like our site at all.

To apply the look of our site, we have to do two things. Create a special file in our theme to handle these pages and activate the theme for these pages. The next two Time for action sections are going to do these steps.

What's a single page?

A single page is a page which is likely to exist just once in your site. This is usually due to a certain functionality or layout such as the dashboard pages. A second screen to create users is quite useless which is why the dashboard has been built using single pages.

For those familiar with other MVC frameworks, single pages are usually called views or layouts.

Time for action – creating a single page layout

Carry out the following steps:

  1. Create a file named view.php in your theme.

  2. Put the following code in it:

    <?php
    defined('C5_EXECUTE') or die('Access Denied.');
    $this->inc('elements/header.php');
    ?>
    <div id="content">
    <?php
    echo $innerContent;
    ?>

    </div>
    <?php $this->inc('elements/footer.php'); ?>

What just happened?

We've created another file in our theme which looks a lot like default.php. However, there's one major difference; view.php must always output the variable $innerContent. The content of single pages is generated by program code and saved in $innerContent.

Some controllers use more variables which you'll have to process as well in order to replace the concrete5 core layout. The login page, for example, has another variable in order to make sure errors are printed too.

Time for action – adding variables to handle login errors

Carry out the following steps:

  1. Before you put any code in view.php, open concrete\themes\core\ concrete.php and have a look at the content of the file. Right before $innerContent is printed, there are a few lines about printing any existing errors. This is what we're going to need in our view.php file too. Copy and insert it in the new file, and it should look like the following:

    <?php
    defined('C5_EXECUTE') or die('Access Denied.');
    $this->inc('elements/header.php');
    ?>
    <div id="content">
    <?php
    Loader::element('system_errors', array('error' => $error));
    ?>

    <?php
    echo $innerContent;
    ?>
    </div>
    <?php $this->inc('elements/footer.php'); ?>

  2. Now that we handle errors as well, we can use our view.php file to style the login page. Open config/site_theme_paths.php in your editor.

  3. There are already a few examples we can use as a template, or alternatively simply remove everything and insert the following lines instead:

    <?php
    defined('C5_EXECUTE') or die('Access Denied. ');
    $v = View::getInstance();
    $v->setThemeByPath('/login', 'c5book');

  4. Save the file and log out of concrete5 and go to http://localhost/login/.

What just happened?

We've added view.php to our theme which can be used to apply a theme layout to single pages. The login page has now been embedded into our page with a small modification to config/site_theme_paths.php.

We're going to create our own single pages later in this article as well, but if you just want to style existing single pages, this is everything you'll need.

Creating customizable themes

Creating a concrete5 theme does require some programming skill; it's a tool for programmers and not just designers and end-users after all. However, there's a nice way to allow end users to change some colors in a theme without any programming skill.

This feature allows you to change colors, fonts and insert custom CSS rules using the concrete5 interface without touching any files at all.

Time for action – creating a customizable theme

Carry out the following steps:

  1. Open main.css from your theme.

  2. Look for body and replace it using the following code:

    body {
    /* customize_background */ background-color: #989898; /*
    customize_background */
    height: 100%;
    }

  3. Search for #header_line_bottom and replace it with these lines:

    #header_line_bottom {
    /* customize_header_line */ background-color: #e64116; /*
    customize_header_line */
    height: 3px;
    }

  4. Search for #footer_line_top and replace it with the following lines:

    #footer_line_top {
    /* customize_footer_line */ background-color: #e64116; /*
    customize_footer_line */
    height: 3px;
    }

  5. At the end of the file, insert the following line:

    /* customize_miscellaneous */ /* customize_miscellaneous */

What just happened?

We've added some comments to our CSS file. They don't generate any errors if you validate the file but concrete5 parses them and generates an interface on top of it where you can change the values surrounded by these comments.

After you've saved the modified CSS file, you can go back to the Dashboard and select Themes. Next, click on Customize next to the active theme. All the comments are transferred into a simple interface where you can change the values by clicking on the icon on the left of each property. Change them and you'll immediately see a preview of how the page is going to look with the new values. If you're satisfied with your choice, click on Save and your site will go green in no time, as shown in the following screenshot:

It often happens that a new theme ignores the custom values. This is usually due to a problem in the way the CSS file is included. If it has been directly linked using a relative path, concrete5 won't be able to replace the values. Make sure you use the following code to include your CSS file in case you want to use customizable style sheets:

<link rel="stylesheet" media="screen" type="text/css" href="<?php echo
$this->getStyleSheet('main.css')?>" />

Have a go hero – adding more customizable styles

You've seen how you can add your own customizable styles, why not try to add more to make it possible to customize more aspects of your theme without the need to touch a file?

Summary

In this article, we looked at the process to transform a static HTML site into a concrete5 theme by adding a few PHP calls in our files. We split our theme into three parts; a header, the actual content file, and a footer, to make it easier to create different page templates to allow a quick change of the page structure.

After we finished our theme, we installed it and had a look at different functions you might be able to use in case you want to get a little bit more out of concrete5. Afterwards, we created a new page attribute where we can assign a page specific background picture. The attribute example was rather simple, but once you've got into it, you should be able to come up with a lot of different applications for attributes.

Next, we added a navigation block right into our template to avoid the need to use page defaults or manually add the navigation on each page. This also made it impossible for the end user to accidentally remove or modify the navigation, a part of the site which is quite likely not to change every day.

We also looked at a way to assign our page theme to existing single pages such as the login page. This allows us to use built-in concrete5 functionality for a community without having to write lots of code.

If you followed each step of this article, you should have created a bunch of files for your concrete5 site. For those who were in a rush or accidentally skipped a step, you can download the complete theme in the 9314_05_c5book_theme.zip folder on the Packt Publishing website.

Extract the file to /themes and you can install it in your Dashboard when you go to Themes in the dashboard of your site.

In the next article we're going to look at how you can customize the block output by creating custom block templates. Block templates help you to turn the slideshow block into a gallery, add a thumbnail to a page list, and a lot more, so head over to the next article to get more knowledge about this exciting topic!

Resources for Article :


Further resources on this subject:


concrete5 Beginner's Guide Create and customize your own website with the Concrete5 Beginner's Guide
Published: March 2011
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

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.

Books From Packt


Creating Concrete5 Themes
Creating Concrete5 Themes

concrete5 Beginner's Guide
concrete5 Beginner's Guide

Drupal 7 Development by Example Beginner’s Guide
Drupal 7 Development by Example Beginner’s Guide

Joomla! 2.5 Beginner’s Guide
Joomla! 2.5 Beginner’s Guide

ASP.NET 3.5 CMS Development
ASP.NET 3.5 CMS Development

CMS Design Using PHP and jQuery
CMS Design Using PHP and jQuery

CMS Made Simple 1.6: Beginner's Guide
CMS Made Simple 1.6: Beginner's Guide

Kentico CMS 5 Website Development: Beginner's Guide
Kentico CMS 5 Website Development: Beginner's Guide


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
L
T
8
X
g
H
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software