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:
:::ss
<html>
<%-- This is my first template --%>
<head>
<% base_tag %>
<title>$Title</title>
$MetaTags
</head>
<body>
<divid="Container">
<divid="Header">
<h1>Bob's Chicken Shack</h1>
<% with $CurrentMember %>
<p>You are logged in as $FirstName $Surname.</p>
<% end_if %>
</div>
<divid="Navigation">
<% if $Menu(1) %>
<ul>
<% loop $Menu(1) %>
<li><ahref="$Link"title="Go to the $Title page"class="$LinkingMode">$MenuTitle</a></li>
<% end_loop %>
</ul>
<% end_if %>
</div>
<divclass="typography">
$Layout
</div>
<divid="Footer">
<p>Copyright $Now.Year</p>
</div>
</div>
</body>
</html>
# Template elements
### Base Tag
The `<% 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" /><!--[if lte IE 6]></base><![endif]-->`
### Layout Tag
In every SilverStripe theme there is a default `Page.ss` file in the `/templates` folder. `$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.
## Variables
Variables are things you can use in a template that grab data from the page and put in the HTML document. For example:
:::ss
$Title
This inserts the value of the Title field of the page being displayed in place of `$Title`. This type of variable is called a **property**. It is often something that can be edited in the CMS. Variables can be chained together, and include arguments.
:::ss
$Property
$Property(param)
$Property.SubProperty
These **variables** will call a method/field on the object and insert the returned value as a string into the template.
*`$Property` will call `$obj->Property()` (or the field `$obj->Property`)
*`$Property(param)` will call `$obj->Property("param")`
*`$Property.SubProperty` will call `$obj->Property()->SubProperty()` (or field equivalents)
If a variable returns a string, that string will be inserted into the template. If the variable returns an object, then
the system will attempt to render the object through its forTemplate() method. If the `forTemplate()` method has not been
defined, the system will return an error.
SilverStripe provides lots of properties and methods. For more details on built-in page controls and variables, see http://doc.silverstripe.org/sapphire/en/reference/built-in-page-controls
### Escaping
Sometimes you will have template tags which need to roll into one another. This can often result in SilverStripe looking
for a "FooBar" value rather than a "Foo" and then "Bar" value or when you have a string directly before or after the
variable you will need to escape the specific variable. In the following example `$Foo` is `3`.
:::ss
$Foopx // returns "" (as it looks for a Foopx value)
{$Foo}px // returns "3px" (CORRECT)
Or when having a `$` sign in front of the variable
:::ss
$$Foo // returns ""
${$Foo} // returns "$3"
## Includes
Within SilverStripe templates we have the ability to include other templates from the Includes directory using the SS
'include' tag. For example, the following code would include the `Includes/SideBar.ss` code:
:::ss
<% include SideBar %>
The "include" tag can be particularly helpful for nested functionality. In this example, the include only happens if
a variable is true
:::ss
<% if CurrentMember %>
<% include MembersOnlyInclude %>
<% end_if %>
You can also perform includes using the Requirements Class via the template controls. See the section on
[Includes in Templates](requirements#including_inside_template_files) for more details and examples.
:::ss
<% require themedCSS(LeftNavMenu) %>
### Including CSS and JavaScript files (a.k.a "Requirements")
See [CSS](/topics/css) and [Javascript](/topics/javascript) topics for individual including of files and
[requirements](reference/requirements) for good examples of including both Javascript and CSS files.
## Conditional Logic
You can conditionally include markup in the output. That is, test for something that is true or false, and based on that test, control what gets output.
The simplest if block is to check for the presence of a value.
<% if $CurrentMember %>
<p>You are logged in as $CurrentMember.FirstName $CurrentMember.Surname.</p>
<% end_if %>
The following compares a page property called `MyDinner` with the value in quotes, `kipper`, which is a **literal**. If true, the text inside the if-block is output.
<% if $MyDinner="kipper" %>
Yummy, kipper for tea.
<% end_if %>
Note that inside a tag like this, variables should have a '$' prefix, and literals should have quotes. SilverStripe 2.4 didn't include the quotes or $ prefix, and while this still works, we recommend the new syntax as it is less ambiguous.
This example shows the use of the `else` option. The markup after `else` is output if the tested condition is *not* true.
<% if $MyDinner="kipper" %>
Yummy, kipper for tea
<% else %>
I wish I could have kipper :-(
<% end_if %>
This example shows the user of `else\_if`. There can be any number of `else\_if` clauses. The conditions are tested from first to last, until one of them is true, and the markup for that condition is used. If none of the conditions are true, the markup in the `else` clause is used, if that clause is present.
<% if $MyDinner="quiche" %>
Real men don't eat quiche
<% else_if $MyDinner=$YourDinner %>
We both have good taste
<% else %>
Can I have some of your chips?
<% end_if %>
This example shows the use of `not` to negate the test.
<% if not $DinnerInOven %>
I'm going out for dinner tonight.
<% end_if %>
You can combine two or more conditions with `||` ("or"). The markup is used if *either* of the conditions is true.
<% if $MyDinner=="kipper" || $MyDinner=="salmon" %>
yummy, fish for tea
<% end_if %>
You can combine two or more conditions with `&&` ("and"). The markup is used if *both* of the conditions are true.
<% if $MyDinner=="quiche" && $YourDinner=="kipper" %>
Lets swap dinners
<% end_if %>
As you'd expect, these can be nested:
<% if $MyDinner=="chicken" %>
<% if $Wine=="red" %>
You're doing it wrong
<% else %>
Perfect
<% end_if %>
<% end_if %>
## Looping Over Datasets
The `<% loop %>...<% end_loop %>` tag is used to **iterate** or loop over a collection of items. For example:
<ul>
<% loop $Children %>
<li>$Title</li>
<% end_loop %>
</ul>
This loops over the children of a page, and generates an unordered list showing the Title property from each one. Note that $Title <i>inside</i> the loop refers to the Title property on each object that is looped over, not the current page. (To refer to the current page's Title property inside the loop, you can do `$Up.Title`. More about `Up` later.
The value that given in the `<% loop %>` tags should be a collection variable.
### Modulus and MultipleOf
New in 2.4 you can use 2 new controls $Modulus and $MultipleOf to help build column layouts.
:::ss
$Modulus(value, offset) // returns an int
$MultipleOf(factor, offset) // returns a boolean.
The following example demonstrates how you can use $Modulus(4) to generate custom column names based on your control statement. Note that this works for any control statement (not just children)
:::ss
<% control Children %>
<divclass="column-{$Modulus(4)}">
...
</div>
<% end_control %>
Will return you column-3, column-2, column-1, column-0, column-3 etc. You can use these as styling hooks to float, position as you need.
You can also use $MultipleOf(value, offset) to help build columned layouts. In this case we want to add a <br> after every 3th item
:::ss
<% control Children %>
<% if MultipleOf(3) %>
<br>
<% end_if %>
<% end_control %>
## Scope
In the `<% loop %>` section, we saw an example of two **scopes**. Outside the `<% loop %>...<% end_loop %>`, we were in the scope of the page. But inside the loop, we were in the scope of an item in the list. The scope determines where the value comes from when you refer to a variable. Typically the outer scope of a page type's layout template is the page that is currently being rendered. The outer scope of an included template is the scope that it was included into.
### With
The `<% with %>...<% end_with %>` tag lets you introduce a new scope. Consider the following example:
<% with $CurrentMember %>
Hello $FirstName, welcome back. Your current balance is $Balance.
<% end_with %>
Outside the `<% with %>...<% end_with %>`, we are in the page scope. Inside it, we are in the scope of `$CurrentMember`. We can refer directly to properties and methods of that member. So $FirstName is equivalent to $CurrentMember.FirstName. This keeps the markup clean, and if the scope is a complicated expression we don't have to repeat it on each reference of a property.
`<% with %>` also lets us use a collection as a scope, so we can access properties of the collection itself, instead of iterating over it. For example:
$Children.Length
returns the number of items in the $Children collection.
### Top
$Top.Title
### Up
When we are in a scope, we sometimes want to refer to the scope outside the <% loop %> or <% with %>. We can do that easily by using $Up.
$Up.Owner
## Formatting Template Values
The following example takes the Title field of our object, casts it to a `[api:Varchar]` object, and then calls
the `$XML` object on that Varchar object.
:::ss
<% with Title %>
$XML
<% end_with %>
Note that this code can be more concisely represented as follows:
:::ss
$Title.XML
See [data-types](/topics/data-types) for more information.
## Translations
Translations are easy to use with a template, and give access to SilverStripe's translation facilities. Here is an example:
<%t Member.WELCOME 'Welcome {name} to {site}' name=$Member.Name site="Foobar.com" %>
Pulling apart this example we see:
*`Member.WELCOME` is an identifier in the translation system, for which different translations may be available. This string may include named placeholders, in braces.
*`'Welcome {name} to {site}'` is the default string used, if there is no translation for Member.WELCOME in the current locale. This contains named placeholders.
*`name=$Member.Name` assigns a value to the named placeholder `name`. This value is substituted into the translation string wherever `{name}` appears in that string. In this case, it is assigning a value from a property `Member.Name`
*`site="Foobar.com"` assigns a literal value to another named placeholder, `site`.
## Comments
Using standard HTML comments is supported. These comments will be included in the published site.
:::ss
$EditForm <!-- Some Comment About the Edit Form -->
However you can also use special SilverStripe comments which will be stripped out of the published site. This is useful
for adding notes for other developers but for things you don't want published in the public html.
:::ss
$EditForm <%-- This is Located in MemberEditForm.php --%>
## Partial Caching
Partial caching lets you define blocks of your template that are cached for better performance. See [Partial Caching](/reference/partial-caching.md) for more information.
## Creating your own Template Variables and Controls
There are two ways you can extend the template variables you have available. You can create a new database field in your
`$db` or if you do not need the variable to be editable in the cms you can create a function which returns a value in your
