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.
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!
Simply perform the following steps in the CMS and you’re all set:
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.
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.
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.
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:
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.
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.
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.
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).
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.
Now that we’ve discussed the styling, let’s take a look at how to put the content together with the help of templates.
Before we continue, some basic facts and features of templates:
Now that we’ve covered the basics, let’s put them into practice.
We shall use placeholders, taking a look at the code level and how to use them 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.
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.
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.
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.
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:
You might notice $MetaTitle, $Title, and $MenuTitle in your template files (for the moment ignore the appended .XML). We will explore these later on.
I remember deciding to pursue my first IT certification, the CompTIA A+. I had signed…
Key takeaways The transformer architecture has proved to be revolutionary in outperforming the classical RNN…
Once we learn how to deploy an Ubuntu server, how to manage users, and how…
Key-takeaways: Clean code isn’t just a nice thing to have or a luxury in software projects; it's a necessity. If we…
While developing a web application, or setting dynamic pages and meta tags we need to deal with…
Software architecture is one of the most discussed topics in the software industry today, and…