Home
 

26

Mar

18

Building a Theme from a Static Template

What it Does

In this tutorial we are going to create a SilverStripe theme from a static template. The template is exclusive to SSbits and is free to use as you please.

Attached Files


Completed_files.zip(30 KB)

Starting_files.zip(29 KB)

Preperation

The example template provided with this article was created using the CSS framework in this article and so is structured correctly for turning into a silverstripe theme. If this is the first time you are creating a SilverStripe theme we would recommend using this template as it will make following the tutorial a lot easier. However if you are using another template that is not structured in this way see the appendix for some things to look out for before starting.

To use the included template, download and extract the zip file attached above. Copy the brushedsilver folder into the themes/ directory of your SilverStripe install. We then need to tell SilverStripe to use this theme, which is done in the mysite/_config.php file. You will see a line setting the theme to blackcandy which we need to replace with the name of our theme. In this example our theme folder is called brushedsilver so we change this line in _config.php to:

Part 1: Getting Started

The first thing we need to do is create a single theme template which we can then break down into smaller pieces. Create the file themes/brushedsilver/templates/Page.ss and copy the contents of themes/brushedsilver/index.html into it. We now have a static HTML template under a .ss file. It would still work in silverstripe but it would not create any dynamic content. This gives us some indication as to how flexible silverstripes templating system is, we can use as little or as much regular HTML as we like all the way to having a pure HTML page! Obviously we don't want that so lets start making our template dynamic.

The first thing to do is edit the <head> section. We need silverstripe to dynamically generate the meta-tags, the page title and also include any files we specify in our page controllers. Here is the same <head> section converted into a silverstripe template:

So lets run through this. The first thing we do is include the <% base_tag %> and set the title to hold the variable $Title which will be replaced by the title of whichever page we are on. This is followed by $Metatags(false) which adds the meta-tags set. We add false to this so that SilverStripe does not include the page title twice. If we wanted our page title to be independently set for each under the meta-data tab in the CMS, we could set this to true and delete the <title> tag. SilverStripe would then include the entire title line for us, but we would not be able to set a persistent part of it like the name of our site.

We then just add <% require themedCSS() %> tags for each of our CSS files and adjust the IE6 conditional path to be relative to the root of the site. And thats it, our <head> section is now ready for SilverStripe's dynamic magic.

Part II: Top Level Navigation

The navigation in the satic HTML is in the form of an unordered list. We are going to emulate this structure using a SilverStripe control loop which will loop over the top level pages allowing us to create a new list item and link for each one. It looks like this:

The control loop <% control Menu(1) %> tells SilverSripe to loop through the pages in the top level menu, creating whatever HTML is between this starting control and the <% end_control %> for each one. So in this case we create a <li> followed by a <a> and then a closing </li>.  Within the <a> we use a few SilverStripe variables, namely $LinkingMode, $Link, $Title and $MenuTitle. The key to understanding how this works and how control loops work in general is understanding that within this control loop you are in the context of whatever item is being looped through, in this case pages in the top level of the site tree. So when we loop through and use the $Link variable in the href, SilverStripe inserts the link to the page whose context we are currently in. Likewise for $LinkingMode, $Title and $MenuTitle, while outside the control we would be getting the values from the actual page we are on, inside it the values returned are of the items in the loop.

$LinkingMode inserts a class based on whether the link we are creating is for the current page or whether the current page is a child of this link. This way we can style a.current and a.section to be highlighted to show the user they are on that page or in that section.

For more information on the built in variables and functions you can use in a template see this page: http://doc.silverstripe.com/doku.php?id=built-in-page-controls.

At this point, have a look at your page. You will notice the header image not showing as we havn't adjusted the path yet, but also notice that the top level navigation is now generated from your silverstripe site. Remember that you will need to add ?flush=1 to the end of your URL each time you want to see changes made to a template. This makes sure SilverStripe clears its template cache before rendering the page. It's also worth disabling or clearing your browsers cache to avoid any confusion. If your using firefox you can download the Developer Toolbar that has a "disable cache" button among numerous other useful tools.

Part III: Layout Section (Content and Sidebar)

Now lets get onto the main section of our page, otherwise know as the 'Layout'. The Layout is the section of the page that changes between different types of page, so later on we will be stripping this out of our page and placing it in it's own file so that we can vary the look of our pages without having to have completely new templates. Before we do that though we want a completely working page.

First part is the banner image and the sidebar. For the banner image we just need to make the path to the image relative to the root. For the sidebar we use a control loop identical to the one we used for the top navigation, only this time we call Menu(2) instead of Menu(1).
 

The only extra thing to notice here is that we use the variable $Level(1).Title for our sidebar's header. This is a shorter way of writing <% control Level(1) %>$Title<% end_control %> which is just as good because we don't need to loop through multiple items, just jump to the top level page of this section and grab its Title.

Next up is the actual content area. This is really quite simple as all we need to do is insert our $Content variable along with the $Form (for the login form etc.) and $PageComments (for pages where comments are enabled in the CMS) and then make sure our typography, layout and container divs are closed. We also want to get our breadcrumbs in there which is as simple as using $Breadcrumbs. Gotta love SilverStripe :)

Part IV: The Footer

There's not a whole lot to our footer, and even less that needs to be dynamic. We will however add a nifty variable to make the copyright year dynamic. $Now.Year will return the current year, so we can just stick that strait into our template. Alternatively if we want something like 2009 - {year} we can use the dynamic year function in this post. For this example well just use the $Now.Year variable:

Well that wraps up our generic template, but at the moment it's just in a single file which means if we wanted a page without a sidebar for example we would have to make a whole new template. But as usual SilverStripe provides an elegant solution to this situation.

Part V:Creating the Layout Template

We need to strip out our layout section and place it in its own file so that we can create 'Layouts' for each page type we need. So first cut everything within the <div id="layout"> </div> tags pasting it into a new file themes/brushedsilver/templates/Layout/Page.ss and replacing it in the main template with $Layout like so:

Now when SilverStripe draws a page it first grabs the main template from themes/brushedsilver/templates/Page.ss and when it encounters the $Layout variable it looks in the templates/Layout/ folder for a layout which matches the name of the current page type. If it can't find one or the current page type is Page then it just uses themes/brushedsilver/templates/Layout/Page.ss. It then resumes drawing from the main template for the footer etc.

Part VI: Creating the Includes

We can also take this a step further and remove some things from our Layout template so that we can then re-use them in other templates. Let's remove the sidebar and the breadcrumbs. Create two files in the themes/brushedsilver/templates/Includes/ folder, Sidebar.ss and Breadcrumbs.ss. Cut everything inside and including the <div id="sidebar"> </div> and paste it into Sidebar.ss. Now we can simply replace it with an <% include %> tag, as well as introducing a condition to decide whether we add it to our template or not:
 

What we are doing here is testing to see whether there is a second level menu to display and if there is we add our sidebar and our <div id="content> which limits the size of our content area. Otherwise we just leave the sidebar out all together and let the content fill the whole page.

Note. we are moving the <div id="content> to be inside this conditional statement, so if you copied and pasted the code above make sure you don't have another content div below it.

We can do a similar thing with our breadcrumbs so that they are only displayed if we are on the second level. Cut the contents of and including the <div id="breadcrumbs"> </div> and paste it into the Breadcrumbs.ss file. In its place put this code into themes/brushedsilver/templates/Layout/Page.ss

This code has a subtle difference to the one we used for the sidebar. In our If statement we use Level(2) instead of Menu(2). The difference here is that with the breadcrumbs we only want to display them when the user is actually on the second level or greater, while with the sidebar we want to show it on the first level only if a second level exists.

This proccess of separating page elements into Includes is good practice that we recommend repeating for the Footer and Header sections as well as any custom blocks you use repeatedly in your templates.

So that pretty much wraps up the tutorial. You should now have a fully fledged SilverStripe theme that can be extended as you create new page types with different data. The key thing to realise is that SilverStripe's templating system is not only very simple for non-programmers to understand but it is also unobtrusive and allows you to build your templates in a fashion very similar to those of a static HTML page.

Appendix

Sometimes you may want to use a template that was created by somone else who did not have SilverStripe in mind. Here are a few pointers to preparing it for conversion into a SilverStripe theme.

  • Use the blackcandy theme bundled with SilverStripe as a guide to the file structure of a theme. All your files should be in one folder with the name of your theme, containing three folders: css, images and templates. The templates folder should then contain two folders: Layout and Includes. Place all your images in the images folder and all your style sheets into the css folder.
  • Although not essential it's good practice to separate layout, typography and form CSS into their own files. This makes editing easier as well as encouraging re-use in later projects.
  • If you are using active states for navigation buttons so that they are highlighted if you are on that page check to make sure they are using the correct CSS selectors. Silverstripe uses .current and .section classes, returned when using the $LinkingMode variable.

About the Author

Name: Aram Balakjian

Website: http://www.aabweb.co.uk

Aram is a web designer/developer running London based agency aab web. He has a strong passion for developing attractive, usable sites around the SilverStripe CMS.

Comments (10)

  • A young boy and his dad went out fishing one fine morning. After a few quiet hours out in the boat, the boy became curious about the world around him. He looked up at his dad and asked \"How do fish breath under water?\"His dad thought about it for a moment, then replied, \"I really don\'t know, son.\"The boy sat quietly from another moment, then turned back to his dad and asked, \"How does our boat float on the water?\"Nnce again his dad replied, \"Don’t know, son.\"Pondering his thoughts again, a short while later, the boy asks \"Why is the sky blue?\"Again, his dad replied. \"Don’t know, son.\"The inquisitive boy, worried he was annoying his father, asks this time \"Dad, do you mind that I\'m asking you all of these questions?\"\"Of course not son.\" replied his dad, \"How else are you ever going to learn anything?\"

    Posted by replica watches, 06/07/2010 4:39am (23 days ago)

  • Hello, thanks for the nice tutorial. I have copied your theme to the \'themes\' directory and selected it from the control panel but it didn\'t showed up. Please could you help me out on this. Thanks in advance.

    Posted by Rahman, 05/07/2010 10:01am (24 days ago)

  • Ah.. I see it now.
    I needed to flush out the template cache to see it.

    Posted by Patrick, 03/06/2010 7:29pm (2 months ago)

  • Hi
    Now confused.. I changed the _config.php file line to brushedsilver as required to start- I even uploaded the Tutorial Complete files instead to see the difference but I just get a plain blue background page with no navigation etc
    "Generated with the default ContentController.ss template"

    If I can't get it to work with the already completed file I don't know what I am doing wrong?

    Posted by Patrick, 03/06/2010 7:15pm (2 months ago)

  • Best tutorial about SilverStripe templates I have ever seen. Also , exist clean explanations ,such as second level navigation tricks. Please could you explain , sub templates like template_blog . Thanks .

    Posted by Bizim Oyun Sitesi, 31/05/2010 3:35am (2 months ago)

  • Nice tutorial for novice, great wel done

    Posted by Lahiru, 30/04/2010 5:32am (3 months ago)

  • Hi
    I'm fairly new to SilverStripe and found you're tutorial really helpfull.

    One strange thing I found was that when you navigated from page to page, there was a delay before it picked up any stylesheet.

    I changed:

    <% require themedCSS(layout) %>

    to:

    <link rel="stylesheet" href="themes/brushedsilver/css/layout.css" type="text/css" media="screen, projection">

    and everything workes perfectly.

    Any ideas?

    Thanks in advance

    Mike

    Posted by Mike, 24/02/2010 8:28am (5 months ago)

  • I am a novice in silverstripe and this tutorial is a great help.

    Posted by Soumen, 19/01/2010 6:05am (6 months ago)

  • This is a great tutorial. I have tried your template. I realize it is just a starter, to get us going on SilverStripe templating. Have you developed any tutorials on theming for gallery, ecommerce (products), blog, diary and forums mods too? I am in great need of some tutorials on this, ASAP. Or if you have an example set of files, that I can look at, I would love that.

    Posted by Yakiv, 30/11/2009 4:33am (8 months ago)

  • Aram,
    Thank you for making this tutorial available! Now I am trying to apply the tutorial on my training site.

    in Part 1:Getting started I could not find the file suggested in \"the contents of themes/brushedsilver/index.html\"
    What I did find was the file: test_page.html
    Maybe that is the one you meant?

    Thanks for your good work!

    Posted by CharlieS, 20/08/2009 4:04am (11 months ago)

RSS feed for comments on this page RSS feed for all comments

Post your comment