Developing Themes

Tutorial 1 shows you how to create page templates. This guide will help you create your own SilverStripe website theme.

Developing your own theme in SilverStripe is a piece of cake thanks to a very straight forward and clean templating language.

What is a Theme?

A theme is a set of HTML/CSS/Javascript and images that can be used to provide a skin for a site. A theme does not include any PHP: instead it should be separate from the code which allows the portability of a design. After all, this is an MVC framework!

Getting started - Folder Structure

To start your theme you first need to create the basic folder structure for the theme. Check out the image below for the layout of your folders. First you need to create a folder in the themes directory called the name of your theme (we're using “blackcandy”). Please note that underscores in the theme name are reserved to denote “sub-themes” (e.g. “blackcandy_blog”).

Inside your theme, you need the css, images and templates folders. Each of these folders contain parts of your theme and keeping a good folder structure is super important. Now we have this structure we can put our CSS in the css folder, Images in the images folder and all our HTML in the templates folder. This keeps our workspace clean and easy to use.

After you have created the templates folder you need to create 2 more folders within - Includes and Layout (Note the uppercase initial letters). These are 2 different types of templates you will use in your theme - Includes contain snippets of HTML that you want to break out and share between templates (for example the Header can be an include, Footer, Navigation etc) whereas Layout templates are the base page templates. So you can have several includes in a Layout template.

Getting started - Core Files

HTML Templates

Once you have created your folders you need to start to fill it out with a couple 'Core' files. First and most importantly is we need a HTML template for our design. Read the Tutorial 1 and the HTML pages for more in-depth discussion about the HTML templates and how they work. At the very least we need a Page.ss file (note the .ss extenstion - Don't worry its just HTML and any text editor will still read it). So go ahead and create 2 Page.ss files. One in templates, the other in Layout.

Whats with the 2 Page.ss files? Well we have 2 so when the user visits a page they get redirected to the top level Page.ss then, depending on what page they are on, we can have a custom template for that page in the Layout folder. If you dont get it now, you will hopefully pick it up over the rest of this.

So you have 2 blank Page.ss files. What are we going to do with them? How bout we put some HTML in them so we can see our theme in action. The code for mine is below (copied from HTML)

yourtheme/templates/Page.ss

<!DOCTYPE html>
<html lang="en">
<head>
  <% base_tag %>
  $MetaTags(false)
  <title>Bob's Chicken Shack | $Title</title>
</head>
 
<body>
<div id="Container">
  <div id="Header">
    <h1>Bob's Chicken Shack</h1>
  </div>
 
  <div id="Navigation">
    <% if Menu(1) %>
    <ul>
      <% control Menu(1) %>	  
        <li><a href="$Link" title="Go to the $Title page" class="$LinkingMode">$MenuTitle</a></li>
      <% end_control %>
    </ul>
   <% end_if %>
  </div>
 
  <div id="Layout">
    $Layout
  </div>
 
  <div id="Footer">
    <p>Copyright $Now.Year - Bob's Chicken Shack.</p>
  </div>
</div>
</body>
</html>

yourtheme/templates/Layout/Page.ss

<h1>$Title</h1>
$Content
$Form
$PageComments

All you have to do now is tell your site to use your new theme - This is defined in the mysite/_config.php file

SSViewer::set_theme('mythemename');

Go to yoursite.com/?flush=1 and check it out. You should be using your new theme! Not really that awesome or amazing is it? Next we need to add some CSS Magics!

CSS Files

By standard SilverStripe uses 3 CSS Files for your site -

layout.css contains the layout and design of the site
typography.css contains the styling for the text/fonts/links (used in both front and back ends)
form.css styling for forms.

You can add more stylesheets using the template tag <% require themedCSS(filename) %>, which will load filename.css from your css directory.

Note: If you're using a default install of Silverstripe and notice that you're getting layout.css, typography.css and forms.css included without asking for them, they may be being called on lines 21-23 in mysite/code/Page.php. Remove these three Requirements::themedCSS lines, and you will be free to add your own styles.

Resources

A bunch of resources feel free to use to make your template awesome

http://kuler.adobe.com - Kuler is a great color scheming tool
http://blog.html.it/layoutgala/ - 40 super cool CSS layouts for you to use
http://designmeltdown.com - Great gallery of websites. Browse through and get inspired.
http://validator.w3.org/ - Your template must pass 'or get near' validation.
http://famfamfam.com/lab/icons/ - free, beautiful icons.
http://cssremix.com - Another CSS site gallery for inspiration.
http://www.maxdesign.com.au/presentation/process/ - a good process for creating a design

Reference

Overriding

The templating system will search for the appropriate files in the following order:

mysite (or other name given to site folder)
themes
module (eg blog)

So if, for example, you had a typography.css file for a module in the module folder (eg blog/css/), in the theme module directory (eg themes/blackcandy_blog/css/), and in your site folder (eg mysite/css/), the system would use the file mysite/css/typography.css

What gets overridden?

CSS
Templates

PHP files do not get overridden!

<img src="$ThemeDir/images/log.gif" />

If your image is in a subtheme, you can refer to that with an argument to ThemeDir. For example, if your image was in mytheme_forum, you could use the following code:

<img src="$ThemeDir(forum)/images/log.gif" />

Conventions, standards and guidelines

Following some set standards and conventions makes life easy for you and I.

Some conventions for SilverStripe websites, which we suggest following. Take a look at each:

We also suggest following various industry standards and conventions.