--- title: Template Syntax summary: A look at the operations, variables and language controls you can use within templates. icon: code --- # Template Syntax A template can contain any markup language (e.g HTML, CSV, JSON..) and before being rendered to the user, they're processed through [SSViewer](api:SilverStripe\View\SSViewer). This process replaces placeholders such as `$Var` with real content from your [model](../model) and allows you to define logic controls like `<% if $Var %>`. An example of a SilverStripe template is below: **app/templates/Page.ss** ```ss
<% base_tag %>Welcome $FirstName $Surname.
<% end_with %> <% if $Dishes %>You are coming from $UsersIpAddress.
``` [note] Method names that begin with `get` will automatically be resolved when their prefix is excluded. For example, the above method call `$UsersIpAddress` would also invoke a method named `getUsersIpAddress()`. [/note] The variables that can be used in a template vary based on the object currently in [scope](#scope). Scope defines what object the methods get called on. For the standard `Page.ss` template the scope is the current [PageController](api:SilverStripe\CMS\Controllers\ContentController\PageController) class. This object gives you access to all the database fields on [PageController](api:SilverStripe\CMS\Model\SiteTree\PageController), its corresponding [Page](api:SilverStripe\CMS\Model\SiteTree\Page) record and any subclasses of those two. **app/code/Layout/Page.ss** ```ss $Title // returns the page `Title` property $Content // returns the page `Content` property ``` ## Conditional Logic The simplest conditional block is to check for the presence of a value (does not equal 0, null, false). ```ss <% if $CurrentMember %>You are logged in as $CurrentMember.FirstName $CurrentMember.Surname.
<% end_if %> ``` A conditional can also check for a value other than falsy. ```ss <% if $MyDinner == "kipper" %> Yummy, kipper for tea. <% end_if %> ``` [notice] When inside template tags variables should have a '$' prefix, and literals should have quotes. [/notice] Conditionals can also provide the `else` case. ```ss <% if $MyDinner == "kipper" %> Yummy, kipper for tea <% else %> I wish I could have kipper :-( <% end_if %> ``` `else_if` commands can be used to handle multiple `if` statements. ```ss <% if $MyDinner == "quiche" %> I don't like quiche <% else_if $MyDinner == $YourDinner %> We both have good taste <% else %> Can I have some of your chips? <% end_if %> ``` ### Negation You can check if a variable is false with `<% if not %>`. ```ss <% if not $DinnerInOven %> I'm going out for dinner tonight. <% end_if %> ``` Note that you cannot combine this with other operators such as `==`. For more nuanced check you can use the `!` operator. ```ss <% if $MyDinner != "quiche" %> Lets go out <% end_if %> ``` ### Boolean Logic Multiple checks can be done using `||`, `or`, `&&` or `and`. If *either* of the conditions is true. ```ss <% if $MyDinner == "kipper" || $MyDinner == "salmon" %> yummy, fish for tea <% end_if %> ``` If *both* of the conditions are true. ```ss <% if $MyDinner == "quiche" && $YourDinner == "kipper" %> Lets swap dinners <% end_if %> ``` ### Inequalities You can use inequalities like `<`, `<=`, `>`, `>=` to compare numbers. ```ss <% if $Number >= "5" && $Number <= "10" %> Number between 5 and 10 <% end_if %> ``` ## Includes Within SilverStripe templates we have the ability to include other templates using the `<% include %>` tag. The includes will be searched for using the same filename look-up rules as a regular template. However in the case of the include tag an additional `Includes` directory will be inserted into the resolved path just prior to the filename. ```ss <% include SideBar %> <% include MyNamespace/SideBar %> ``` When using subfolders in your template structure (e.g. to fit with namespaces in your PHP class structure), the `Includes/` folder needs to be innermost. ```ss <% include MyNamespace/SideBar %> ``` The `include` tag can be particularly helpful for nested functionality and breaking large templates up. In this example, the include only happens if the user is logged in. ```ss <% if $CurrentMember %> <% include MembersOnlyInclude %> <% end_if %> ``` Includes can't directly access the parent scope when the include is included. However you can pass arguments to the include. ```ss <% with $CurrentMember %> <% include MemberDetails Top=$Top, Name=$Name %> <% end_with %> ``` ## Looping Over Lists The `<% loop %>` tag is used to iterate or loop over a collection of items such as [DataList](api:SilverStripe\ORM\DataList) or a [ArrayList](api:SilverStripe\ORM\ArrayList) collection. ```ssPage '$Title' is a child of '$Up.Title'
<% loop $Children %>Page '$Title' is a grandchild of '$Up.Up.Title'
<% end_loop %> <% end_loop %> ``` Given the following structure, it will output the text. ``` My Page | +-+ Child 1 | | | +- Grandchild 1 | +-+ Child 2 Children of 'My Page' Page 'Child 1' is a child of 'My Page' Page 'Grandchild 1' is a grandchild of 'My Page' Page 'Child 2' is a child of 'MyPage' ``` [notice] Additional selectors implicitely change the scope so you need to put additional `$Up` to get what you expect. [/notice] ```ssPage '$Title' is a child of '$Up.Up.Up.Title'
<% end_loop %> ``` #### Top While `$Up` provides us a way to go up one level of scope, `$Top` is a shortcut to jump to the top most scope of the page. The previous example could be rewritten to use the following syntax. ```ssPage '$Title' is a child of '$Top.Title'
<% loop $Children %>Page '$Title' is a grandchild of '$Top.Title'
<% end_loop %> <% end_loop %> ``` ### With The `<% with %>` tag lets you change into a new scope. Consider the following example: ```ss <% with $CurrentMember %> Hello, $FirstName, welcome back. Your current balance is $Balance. <% end_with %> ``` This is functionalty the same as the following: ```ss Hello, $CurrentMember.FirstName, welcome back. Your current balance is $CurrentMember.Balance ``` Notice that the first example is much tidier, as it removes the repeated use of the `$CurrentMember` accessor. Outside the `<% with %>.`, we are in the page scope. Inside it, we are in the scope of `$CurrentMember` object. We can refer directly to properties and methods of the [Member](api:SilverStripe\Security\Member) object. `$FirstName` inside the scope is equivalent to `$CurrentMember.FirstName`. ### Me `$Me` outputs the current object in scope. This will call the `forTemplate` of the object. ```ss $Me ``` ## Comments Using standard HTML comments is supported. These comments will be included in the published site. ```ss $EditForm ``` 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 <%-- Some hidden comment about the form --%> ``` ## Related Lessons * [Creating your first theme](https://www.silverstripe.org/learn/lessons/v4/creating-your-first-theme-1) ## Related Documentation [CHILDREN Exclude="How_Tos"] ## How to's [CHILDREN Folder="How_Tos"] ## API Documentation * [SSViewer](api:SilverStripe\View\SSViewer) * [ThemeManifest](api:SilverStripe\View\ThemeManifest)