SilverStripe 2.4: Customizing the Layout

Templates and themes

All pages within SilverStripe are rendered using a template, which is basically an HTML/XHTML file with added control code. A template allows you to make conditional statements, create menus, access data stored in the database, and much more. Instead of using PHP for these enhancements, templates rely on a dedicated template engine. When the user accesses a page the engine replaces the control code with PHP. This transformation is then evaluated by the web server to regular markup code, which every browser can display.

A theme consists of a collection of template, CSS, and image files. Design-specific JavaScript is also stored here. Together they form the layout of a page.

Switching between themes

You can have multiple themes and switch between them whenever you like.

You’re definitely encouraged to give everything described here a try. It helps you in becoming an active developer instead of a passive user. So let’s get things started!

Time for action – change the default theme

Simply perform the following steps in the CMS and you’re all set:

1. Log into the CMS by appending /admin to your page’s base URL. Provide the credentials you defined during the installation and you should be logged-in.
2. Go to the general configuration page by clicking on the globe within the Page Tree section. The default text of this element is Your Site Name.
3. The Theme is set to (Use default theme) by default; change this to tutorial.

   
4. Click on the Save button.
5. Go to the base URL / and reload the page.

What just happened?

We’ve successfully changed the theme of our website. It’s as easy as that.

Note that you need to package your theme into a subfolder of themes/ to be able to switch between them.

While you can also put the contents of a theme directly into the mysite/ folder, keeping your system modularized is a good practice. Therefore we won’t integrate the layout into the site specific folder and will instead always create a dedicated, switchable theme.

Getting more themes

After unpacking a theme, copy it to the themes/ folder, change the theme in the CMS, and you’re good to go.

Using a prebuilt theme really is that simple. Next, we’ll take a look at the facilities for building our own themes—specifically, the template engine that powers all themes in SilverStripe.

By the end of this article and next, you’ll even be ready to upload and share your own themes with the rest of the community at the address above. New contributions are always welcome.

Template engine

As described earlier, the SilverStripe architecture consists of three layers, each serving a specific purpose. The one responsible for the layout is called View, which we’ll cover in detail in this article.

Another template engine?

One might wonder why it is necessary to learn another template language, while there are already so many others available and PHP can do all of it as well. The main reasons behind this are:

• The template engine and the rest of the system fit perfectly together. After getting the hang of it, it makes the creation of templates and communication with the other layers faster and easier.
• The available control code is very simple. Designers without a lot of programming knowledge can create feature-rich layouts.
• It enforces good coding practice. Without the ability to use raw PHP, one cannot by-pass the other layers and undermine the architecture. Only layout and rendering information should be used within templates.

Taking a look at BlackCandy

First of all, switch back to the BlackCandy theme as we want to take a better look at it.

Within your installation, navigate to the folder themes/blackcandy/ and you’ll see three folders: css/, images/, and templates/. The images/ folder contains any image used in your theme; if you like, you can create subfolders to keep things organized. The remaining folders are a bit more complicated, so let’s break them down.

CSS

At first this looks a bit messy—five files for the CSS; couldn’t we use just a single one? We could, but many developers consider it a good practise splitting the functionality into different parts, making it easier to navigate later on. Sticking to this convention adds functionality as well.

This is a common principle, called convention over configuration. If you do things the way they are expected by the system, you don’t need to configure them specifically. Once you know the “way” of the system, you’ll work much quicker than if you had to configure the same things over and over again.

editor.css

This file is automagically loaded by SilverStripe’s what you see is what you get (WYSIWYG) editor. So if you apply the correct styling via this file, the content in the CMS’ backend will look like the final output in the frontend. Additionally you’ll have all custom elements available under the Styles dropdown, so the content editors don’t need to mess around with pure HTML.

As this file is not automatically linked to the frontend, it’s common practice to put all frontend styling information into typography.css and reference that file in editor.css:

@import “typography.css”;

If you want to provide any styling information just for the CMS, you can put it below the @import.

layout.css, form.css, and typography.css

These files are automagically included in the frontend if they are available in your theme. While layout.css is used for setting the page’s basic sections and layout, form.css deals with the form related styling.

typography.css covers the layout of content entered into the CMS, generally being imported by editor.css as we’ve just discussed. Elements you will include here are headers (<h1>, <h2>, and so on), text (for example <p>), lists, tables, and others you want to use in the CMS (aligning elements, <hr>, and so on).

ie6.css

This file isn’t part of the SilverStripe convention, but is a useful idea you might want to adopt. You must include it manually but it will still be a good idea to stick to this naming schema: ie.css for styling elements in any version of Internet Explorer, ie6.css for Internet Explorer 6 specifics, and so on.

What about performance?
Cutting down on the number of files being loaded is an effective optimization technique for websites. We’ll take a look at how to do that.

Templates

Now that we’ve discussed the styling, let’s take a look at how to put the content together with the help of templates.

Learning the very basics

Before we continue, some basic facts and features of templates:

• Templates must use the file extension .ss instead of .html or .php.
• Templates can be organized alongside their PHP Controllers, so you can use the same powerful mechanism as in the other layers. We’ll take a better look at what this means a little later.
• Page controls consist of placeholders and control structures, which are both placed within the regular markup language.
• Placeholders start with a $ and are processed and replaced by the template engine.
• Control structures are written between opening <% and closing %>. They look a bit like HTML tags and they are used the same way. Some consist of a single element, like HTML’s <br>, whereas others consist of two or more.

Starting to use templates

Now that we’ve covered the basics, let’s put them into practice.

Time for action – using site title and slogan

We shall use placeholders, taking a look at the code level and how to use them in the CMS:

1. Open the file themes/blackcandy/templates/Page.ss in your preferred editor.
2. If the syntax highlighting is disabled due to the unknown file extension, set it to HTML.
3. Find the two placeholders $SiteConfig.Title and $SiteConfig.Tagline in the code.
4. Go to the general configuration page in the CMS, the one where we’ve changed the theme.
5. Edit the Site title and Site Tagline/Slogan to something more meaningful.
6. Save the page.
7. Go to the base URL and hit refresh.
8. If you view the page’s source, you can see that the two placeholders have been replaced by the text we have just entered in the CMS.

If you are wondering about the short doctype declaration: there is nothing missing, this is HTML5, which SilverStripe is already using in its default theme. If you prefer XHTML or an older HTML standard, you can freely change it. The CMS happily works with all of them.

What just happened?

The file we’ve just edited is the base template. It’s used for every page (unless specifically overwritten). You can define your general layout once and don’t have to repeat it again.

You should always try to avoid repeating code or content. This is generally called don’t repeat yourself (DRY) or duplication is evil (DIE). SilverStripe supports you very well in doing this.

The site title and slogan are globally available. You can use them on every page and they share the same content across the whole website. These placeholders are prefixed with SiteConfig. as well as a $ sign. In the CMS they are all available on the site’s root element, the one with the globe. By default, there are just two, but we’ll later see how to add more.

Other placeholders are available on specific pages or can be different on each page. We’ll come to those next.

Layout

Looking again at the Page.ss we’ve just opened, you’ll also see a $Layout placeholder. This is replaced by a file from the themes/blackcandy/templates/Layout folder. There are only two files available by default and for every standard page Page.ss is used.

When a page is loaded, the template engine first finds the base templates/Page.ss (excluding the theme specific part of the path as this can vary). It’s evaluated and the $Layout is replaced by templates/Layout/Page.ss, which is also evaluated for further SilverStripe controls.

Ignore Page_results.ss for the moment. It’s only used for search queries which we’ll cover later. We’ll also add more page types so the layout’s Page.ss can then be replaced by a more specific template, while the base templates/Page.ss is always used.

Includes

Both Page.ss files include statements like <% include BreadCrumbs %>. These controls are replaced by files from the themes/blackcandy/templates/Includes/ folder. For example, the above include grabs the themes/blackcandy/templates/Includes/BreadCrumbs.ss file.

Note that filenames are case sensitive. Otherwise you’re free to select a meaningful name. Try sticking to one naming convention to make your own life easier later on, and also note that you mustn’t include the <code>.ss</code> extension.

If you’re seeing a Filename cannot be empty error, make sure the included file really exists.

Have a go hero – using page name, navigation label, and metadata title

Now that we’ve explored all available files and how they are used, let’s take a better look at the system.

In the CMS backend, go to the Home page. Change the text currently entered into Page name, Navigation label (both in the Main tab), and Title (Metadata tab). Take a look at:

• Where on the page they are used
• In which file they are located (take a look at all three possible locations)
• What template placeholders represent them

You might notice $MetaTitle, $Title, and $MenuTitle in your template files (for the moment ignore the appended .XML). We will explore these later on.