This document contains information for an outdated version (2.4) and may not be maintained any more. If some of your projects still use this version, consider upgrading as soon as possible.
SilverStripe templates consist of HTML code augmented with special control codes, described below. Because of this, you can have as much control of your site's HTML code as you like.
Because the SilverStripe templating language is a string processing language it can therefore be used to make other text-based data formats, such as XML or RTF.
Here is a very simple template:
<html> <head> <% base_tag %> <title>$Title</title> $MetaTags </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 class="typography"> $Layout </div> <div id="Footer"> <p>Copyright $Now.Year</p> </div> </div> </body> </html> <%-- comment --%>
Default Template Syntax
These tags appear on the default template and should be included in every theme:
<% base_tag %> placeholder is replaced with the HTML base element. Relative links within a document (such as `<img
src="someimage.jpg" />`) will become relative to the URI specified in the base tag. This ensures the browser knows where
to locate your site’s images and css files. So it is a must for templates!
It renders in the template as
<base href="http://www.mydomain.com" />
$MetaTags placeholder in a template returns a segment of HTML appropriate for putting into the
<head> tag. It
will set up title, keywords and description meta-tags, based on the CMS content and is editable in the 'Meta-data' tab
on a per-page basis. If you don’t want to include the title-tag
<title> (for custom templating), use
<title>Title of the Page</title> <meta name="generator" http-equiv="generator" content="SilverStripe 2.0" > <meta http-equiv="Content-type" content="text/html; charset=utf-8" >
TODO Explain SiteTree properties and SiteTree->MetaTags() overloading
In every SilverStripe theme there is a default
Page.ss file in the
$Layout appears in this file
and is a core variable which includes a Layout template inside the
/templates/Layout folder once the page is rendered.
By default the
/templates/Layout/Page.ss file is included in the html template.
By default, SilverStripe includes the
theme/css/typography.css file into the Content area. So you should always include the
typography style around the main body of the site so both styles appear in the CMS and on the template. Where the main body of
the site is can vary, but usually it is included in the /Layout files. These files are included into the main Page.ss template
by using the
$Layout variable so it makes sense to add the .typography style around $Layout.
<div class="typography"> $Layout </div>
Designing reusable templates
Although SilverStripe is ultimately flexible in how you create your templates, there's a couple of best practices. These will help you to design templates for modules, and make it easier for other site developers to integrate them into their own base templates.
- Most of your templates should be Layout templates
- Build your templates as a Theme so you can easily re-use and exchange them
- Your layout template should include a standard markup structure (
- Layout templates only include content that could be completely replaced by another module (e.g. a forum thread). It
might be infeasible to do this 100%, but remember that every piece of navigation that needs to appear inside
$Layoutwill mean that you have to customise templates when integrating the module.
- Any CSS applied to layout templates should be flexible width. This means the surrounding root template can set its width independently.
- Don't include any navigation elements in your Layout templates, they should be contained in the root template.
- Break down your templates into groups of includes. Site integrators would then have the power to override individual includes, rather than entire templates.
For more information about templates go to the Advanced Templates page.
- Advanced Templates
- Tutorial 1: Building a basic site
- Tutorial 2: Extending a basic site