SilverStripe 2.4: Creating our Own Theme

Time for action - files and folders for a new theme

We could start off from scratch, but let's not make it more complicated than necessary:

Simply copy the BlackCandy theme to a new folder in the same directory. We'll just call it bar as the page should be for a bar business.

Now reload the CMS backend and you should be able to switch to the new bar theme.

As we won't use any of the available images we can delete all image files, but leave the folder intact—we'll add our own pictures later on.

Basic layout

Next, we'll create our page's general layout. Time to put our template skills into action!

Here's the basic layout we want to create:

silverstripe-24-creating-our-own-theme-img-0

So far it's a pretty basic page. We'll take a good look at the templates and basic structure but won't spend much time on the HTML and CSS specifics. Do, however pay attention on how to set up the different CSS files to make the most out of them.

We won't list every line of code involved. If you'd prefer, you can simply copy the missing parts from the code provided here (Ch:2)

File themes/bar/templates/Page.ss

This page is pretty empty. We'll later add an intro page with a different structure, so the code these templates will share is rather limited.

Time for action - the base page

Add the following code to the file themes/bar/templates/Page.ss:

<!doctype html>
<html lang="$ContentLocale">
<head>
<meta charset="utf-8"/>
<% base_tag %>
<title>
<% if MetaTitle %>
$MetaTitle
<% else %>
$Title
<% end_if %>
</title>
$MetaTags(false)
<link rel="shortcut icon" href="favicon.ico"/>

</head>
<body>
$Layout
<noscript>
<br/> <br/> <br/> <br/> <br/> <br/> 
<div><p>
<b>Please activate JavaScript.</b><br/>
Otherwise you won't be able to use all available functions
properly...
</p></div>
</noscript>
</body>
</html>

What just happened?

The highlighted parts are SilverStripe specific:

First, we set the language of our content. Depending on what you've selected during the installation process this can vary. By default, it will be:
<html lang="en-US">

Setting the page's base; this can be useful when referencing images and external files. Depending on how you set up your system this will vary.

Setting the title just like in the BlackCandy theme.

Next, adding meta tags without the title element. These are only set if you actually enter them in the CMS on the Metadata tab on the desired page's Content tab. Empty fields are simply left out in the output. Only the SilverStripe note is set in any case.

Finally, including the page's specific layout.

The JavaScript we include for Internet Explorer versions before 9 fixes their inability to correctly render HTML5 tags. To learn more about the specific code, head over to https://code.google.com/p/html5shim/.

Why HTML5?
The motivation behind it isn't to stay buzz-word compliant. While HTML5 is not a finished standard yet, it already adds new features and makes the development a little easier. Take a look at the doctype declaration for example: that's much shorter than XHTML. Now there's a real chance of actually remembering it and not needing to copy it every time you start from scratch. New features include some very handy tags, but we'll come to those in the next code sample.

The output on the final HTML page for the second and third elements (we've already taken a look at the first) in the header looks like the following listing. Which part in the template is responsible for which line or lines?

Did you notice that there is no reference to a CSS file and the styling is still applied? Remember that CSS files are automagically included if you stick to the naming convention we've already discussed.

File themes/bar/templates/Layout/Page.ss

Now let's move beyond the basics and do something a bit more interesting.

Time for action - the layout page

Add the following code to the file themes/bar/templates/Layout/Page.ss:

<div>
<img src="$ThemeDir/images/background.jpg" alt="Background"
id="background"/>
</div>
<section id="content" class="transparent rounded shadow">
<aside id="top">
<% include BasicInfo %>
</aside>
<% include Menu %>
<section class="typography">
$Content
$Form
</section>
</section>
<% include Footer %>

We rely on just three includes which are very easy to reuse on different pages.

We then reference the page's content and possible forms (no comments will be required).

The only template part we've not yet covered is the $ThemeDir. This is replaced by the path to our theme, in our case themes/bar/. So you don't need to worry about hard-coded paths when copying template files between different themes. You only need to take care of paths in the CSS files as they are not processed by the template engine.

The includes: BasicInfo.ss, Menu.ss, and Footer.ss

In the previous code segment, we've referenced three includes. Let's not forget to create them.

Time for action - the includes

The includes we're yet to explore are Menu.ss, BasicInfo.ss, and Footer.ss.

The menu is very simple, we only include the first level, highlighting the currently active item, as we won't have more subpages:
<nav id="menu">
<ul>
<% control Menu(1) %>
<li class="$Linkingmode">
<a href="$Link">$MenuTitle</a>
</li>
<% end_control %>
</ul>
</nav>

BasicInfo.ss only contains the $ThemeDir placeholder besides good old HTML:
<a href="home">
<img src="$ThemeDir/images/logo.png" alt="Logo" id="logo"/>
</a>
<ul id="details-first">
<li>Phone: <b>01 23456789</b></li>
<li>Contact: <a href="contact">[email protected]</a></li>
<li>Address: <a href="location">Bar Street 123</a></li>
</ul>
<div id="details-second">
<div class="left">Opening hours:</div>
<div class="right"><p>
<b>Mon - Thu 2pm to 2am</b><br/>
<b>Fri - Sat 2pm to 4am</b>
</p></div>
</div>
<a href="http://www.facebook.com/pages/">
<img src="$ThemeDir/images/facebook.png" alt="Facebook"
id="facebook"/>
</a>
Be sure to replace bar.com with your own domain. However, using it here is quite fitting because we're making a page for a bar and http://www.bar.com is only a placeholder itself. It's derived from foobar or foo bar, a placeholder name often used in computer programming. But take a look at the site yourself for more information.

Finally, the footer makes use of the $Now placeholder and the date formatter .Year to retrieve the current year:
<footer>
<span><a href="imprint">Imprint</a></span>
<span>© Bar $Now.Year</span>
</footer>

Have a go hero - create the layout and pages

Now that we've gone over all of the content, it's time to build the page. Feel free to copy some code as we're not a typing class, but take careful note of every SilverStripe specific part, so you understand what you're doing.

We use three includes, so create these files and remove the rest still available from BlackCandy as well as the unused templates/Layout/Page_results.ss.

And don't forget to flush the cache by appending ?flush=all to the page's URL! When working with includes it will save you a lot of trouble.

We've hardcoded some links to different pages in the template files. Make sure you add all necessary pages including the imprint, but don't add it to the menu.