Home
 

26

Mar

24

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)

  • We offer replica watches of Rolex Watches on online for sale. Our Replica Rolex Watches are the best quality and most cheap watches replica are the same as the genuine replica watch.at www.awatchesreplica.com.

    Posted by replica watches, 28/08/2010 10:45pm (6 days ago)

  • <P style="MARGIN: 0cm 0cm 0pt" class=MsoNormal><SPAN style="FONT-SIZE: 15pt" lang=EN-US><FONT face="Times New Roman">The superiority of <SPAN style="mso-spacerun: yes">&nbsp;</SPAN><B style="mso-bidi-font-weight: normal"><A href="http://www.awatchesreplica.com/Replica_Rolex_Watches-1.html"><FONT color=#800080>Replica Rolex Watches</FONT></A></B> are not only for the </FONT></SPAN><SPAN style="FONT-SIZE: 15pt" lang=EN-US><FONT face="Times New Roman">best price,but also for the high quality of<B style="mso-bidi-font-weight: normal"> <A href="http://www.awatchesreplica.com/"><FONT color=#800080>replica watches</FONT></A></B>.We </FONT></SPAN><SPAN style="FONT-SIZE: 15pt" lang=EN-US><FONT face="Times New Roman">offer cheap <B style="mso-bidi-font-weight: normal"><A href="http://www.awatchesreplica.com/Replica_Rolex_Watches-1.html"><FONT color=#800080>replica rolex watches</FONT></A></B>,<B style="mso-bidi-font-weight: normal"><A href="http://www.awatchesreplica.com/"><FONT color=#800080>replica watch</FONT></A></B>,<B style="mso-bidi-font-weight: normal"><A href="http://www.awatchesreplica.com/"><FONT color=#800080>fake watches</FONT></A></B> online for sale.

    Posted by replica watches, 28/08/2010 10:42pm (6 days ago)


  • I just came across your blog and reading your beautiful words. I thought I would leave my first comment but I don't know what to say except that I have enjoyed reading. Nice blog. I will keep visiting this blog very often.

    Posted by HI Magic Saturday , 23/08/2010 2:05am (12 days ago)

  • Aram, first off, great tutorial. Second, you should check out this thread, of someone wanting to make templates for SilverStripe.

    Maybe you could make a custom tutorial, showing how to use an Artisteer HTML template and convert it to a SilverStripe template? That would be great!

    ...I see you have a lot of comment SPAM on this thread. Hope you get on your site and take the time to clean it up. ...It's probably manual SPAM, but maybe their are bypassing your form somehow.

    Posted by usajim, 20/08/2010 3:57am (15 days ago)

  • I just came across your blog and reading your beautiful words. I thought I would leave my first comment but I don't know
    what to say except that I have enjoyed reading. Nice blog. I will keep visiting this blog very often.

    Posted by tiffany, 13/08/2010 10:39pm (21 days ago)

  • I was just doing some web browsing on my Garmin Phone during my break at my work place, and I came across something I thought was interesting . It linked over to your website so I clicked over. I can’t really find the relevance between your site and the one I came from, but your site good none the less.thanks for sharing thoes informations , It is interesting, i like it!

    Posted by kevin, 10/08/2010 12:42am (25 days ago)

  • 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 (2 months 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 (2 months 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 (3 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 (3 months ago)

1 2 3 next »

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

Post your comment