Common variables
The page below describes a few of common variables and methods you'll see in a Silverstripe CMS template. This is not an exhaustive list. From your template you can call any method, database field, or relation on the object which is currently in scope as well as its subclasses or extensions.
Knowing what methods you can call can be tricky, but the first step is to understand the scope you're in. Scope is explained in more detail on the syntax page. Many of the methods listed below can be called from any scope, and you can specify additional static methods to be available globally in templates by implementing the TemplateGlobalProvider interface.
Want a quick way of knowing what scope you're in? Try putting $ClassName
in your template. You should see a string
such as Page
of the object that's in scope. The methods you can call on that object then are any functions, database
properties or relations on the Page
class, PageController
class as well as anything from their parent classes and
any extensions applied to them.
Outputting these variables is only the start, if you want to format or manipulate them before adding them to the template have a read of the Formatting, Modifying and Casting Variables documentation.
Some of the following only apply when you have the silverstripe/cms
module installed. If you're using silverstripe/framework
alone, this
functionality may not be included.
Base tag
<head>
<% base_tag %>
...
</head>
The <% base_tag %>
placeholder is replaced with the HTML base element. Relative links within a document (such as
<img src="someimage.jpg" alt="">
) 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.
It renders in the template as <base href="https://www.example.com" /><!--[if lte IE 6]></base><![endif]-->
A <% base_tag %>
is nearly always required or assumed by Silverstripe CMS to exist.
CurrentMember
Returns the currently logged in Member instance, if there is one logged in.
<% if $CurrentMember %>
Welcome back, $CurrentMember.FirstName
<% end_if %>
Title and menu title
$Title
$MenuTitle
Most objects within Silverstripe CMS will respond to $Title
(i.e. they should have a Title
database field or at least a
getTitle()
method).
The CMS module in particular provides two fields to label a page: Title
and MenuTitle
. Title
is the title
displayed on the web page, while MenuTitle
can be a shorter version suitable for size-constrained menus.
If MenuTitle
is left blank by the CMS author, it'll just default to the value in Title
.
Page content
$Content
It returns the database content of the Content
field. For subclasses of SiteTree
, this is the value of the WYSIWYG editor
but it is also the standard for any object that has a body of content to output.
Please note that this database content can be "versioned", meaning that draft content edited in the CMS can be different from published content shown to your website visitors. In templates, you don't need to worry about this distinction.
The $Content
variable contains the published content by default, and only preview draft content if explicitly
requested (e.g. by the "preview" feature in the CMS) (see the versioning documentation for
more details).
SiteConfig
: global settings
SiteConfig
comes from an optional module that is bundled with the CMS. If you wish to include SiteConfig
in your framework only
web pages, you'll need to install silverstripe/siteconfig
via composer.
$SiteConfig.Title
The SiteConfig
object allows content authors to modify global data in the CMS, rather
than PHP code. By default, this includes a Website title and a Tagline.
SiteConfig
can be extended to hold other data, for example a logo image which can be uploaded through the CMS or
global content such as your footer content.
See the SiteConfig
documentation for more information.
Meta tags
The $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 use $MetaTags(false)
.
By default $MetaTags
renders (assuming 5.1.0 is the current version of silverstripe/framework
):
<title>Title of the Page</title>
<meta name="generator" content="Silverstripe CMS 5.1">
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
$MetaTags(false)
will render
<meta name="generator" content="Silverstripe CMS 5.1">
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
If using $MetaTags(false)
we can provide a more custom title
.
$MetaTags(false)
<title>$Title - Bob's Fantasy Football</title>
Disabling the meta generator tag
The meta generator tag includes the current version of silverstripe/framework
. This version number
provides aggregate installation numbers to the product team who maintain Silverstripe CMS which is
used to make informed product decisions.
If you dislike this behaviour, the entire meta generator tag can be disabled via:
SilverStripe\CMS\Model\SiteTree:
meta_generator: ''
The version portion of the metagenerator tag can be disabled via:
SilverStripe\CMS\Model\SiteTree:
show_meta_generator_version: false
Modifying meta tags
You can override the MetaComponents()
method on your SiteTree
sub-classes or make use of the MetaComponents
extension point to manipulate the underlying data that is rendered by $MetaTags
. Example (for Page
class):
namespace App\PageType;
use Page;
class MyPage extends Page
{
// ...
public function MetaComponents()
{
$tags = parent::MetaComponents();
// Override the content of the Title tag (needs to be html)
if ($this->MetaTitle) {
$tags['title']['content'] = $this->obj('MetaTitle')->forTemplate();
}
// Provide a default Meta Description
if (!$tags['description']['attributes']['content']) {
// provide raw text as attributes will be escaped later
$tags['description']['attributes']['content']
= $this->dbObject('Content')->LimitCharactersToClosestWord(300);
}
return $tags;
}
}
Links
<a href="$Link">..</a>
All objects that could be accessible via a public HTTP request in Silverstripe CMS should define a Link()
method and an AbsoluteLink()
method. Link()
returns the relative URL for the object and AbsoluteLink()
outputs your full website address along with the relative
link.
<%-- prints /about-us/offices/ --%>
$Link
<%-- prints https://www.example.com/about-us/offices/ --%>
$AbsoluteLink
Linking modes
$isSection
$isCurrent
When looping over a list of SiteTree
instances through a <% loop $Menu %>
or <% loop $Children %>
, $isSection
and $isCurrent
will return true or false based on page being looped over relative to the currently viewed page.
For instance, to only show the menu item linked if it's the current one:
<% if $isCurrent %>
$Title
<% else %>
<a href="$Link">$Title</a>
<% end_if %>
An example for checking for current
or section
is as follows:
<a class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>" href="$Link">$MenuTitle</a>
Additional utility method
$InSection('<page-url-segment>')
: This if block will pass if we're currently on that page or one of its children.
<% if $InSection('about-us') %>
<p>You are viewing the about us section</p>
<% end_if %>
URLSegment
This returns the part of the URL segment of the page you're currently on. For example on the /about-us/offices/
web page the
URLSegment
will be offices
. URLSegment
cannot easily be used to generate a link since it does not output the full path.
It can be used within templates to generate anchors or other CSS classes.
<%-- prints <div id="section-offices"> --%>
<div id="section-$URLSegment">
...
</div>
ClassName
Returns the class of the current object in scope (see "scope" in the syntax section) such as Page
or App\PageType\HomePage
.
Note that this is backed by DBClassName
, which means you can use the methods in that class from your template
(e.g. $ClassName.ShortName
prints HomePage
instead of App\PageType\HomePage
).
The $ClassName
can be handy for a number of uses. A common use case is to add to your <body>
tag to influence CSS styles and JavaScript
behavior based on the page type used:
<%-- prints <body class="HomePage">, or <body class="BlogPage"> --%>
<body class="$ClassName.ShortName">
Children
loops
<% loop $Children %>
<% end_loop %>
Will loop over all Children records of the current object context. Children are pages that sit under the current page in
the CMS
or a custom list of data. This originates in the Versioned
extension's getChildren
method.
See Looping Over Lists for more information about looping in general.
For doing your website navigation most likely you'll want to use $Menu
since its independent of the page
context.
ChildrenOf
<% loop $ChildrenOf('<my-page-url-segment>') %>
<% end_loop %>
Will create a list of the children of the given page, as identified by its URLSegment
value. This can come in handy
because it's not dependent on the context of the current page. For example, it would allow you to list all staff member
pages underneath a "staff" holder on any page, regardless if its on the top level or elsewhere.
Because variables can't be passed into method calls from templates (see Syntax > Variables), this requires you to hardcode some value into your template - which means you must ensure you have a page added in the CMS with that URL segment
A more robust way to implement this would be to add a helper method in your page controller which dynamically gets the appropriate page (if one exists).
AllChildren
Content authors have the ability to hide pages from menus by un-selecting the ShowInMenus
checkbox within the CMS.
This option will be honored by <% loop $Children %>
and <% loop $Menu %>
however if you want to ignore the user
preference, AllChildren
does not filter by ShowInMenus
.
<% loop $AllChildren %>
...
<% end_loop %>
Menu
loops
<% loop $Menu(1) %>
...
<% end_loop %>
$Menu(1)
returns the top-level menu of the website. You can also create a sub-menu using $Menu(2)
, and so forth.
Pages with the ShowInMenus
property set to false
will be filtered out.
Access to a specific page
<% with $Page('my-page') %>
$Title
<% end_with %>
Page will return a single page from site, looking it up by its URLSegment
field.
Access to parent and level pages
Level
<% with $Level(1) %>
$Title
<% end_with %>
Will return a page in the current path, at the level specified by the numbers. It is based on the current page context,
looking back through its parent pages. $Level(1)
being the top most level.
For example, imagine you're on the "bob marley" page, which is three levels in: "about us > staff > bob marley".
$Level(1).Title
would return "about us"$Level(2).Title
would return "staff"$Level(3).Title
would return "bob marley"
Parent
<%-- given we're on 'Bob Marley' in "about us > staff > bob marley" --%>
<%-- prints 'staff' --%>
$Parent.Title
<%-- prints 'about us' --%>
$Parent.Parent.Title
Navigating scope
See scope in the syntax documentation.
Breadcrumbs
Breadcrumbs are the path of pages which need to be taken to reach the current page, and can be a great navigation aid for website users.
While you can achieve breadcrumbs through the $Level(<level>)
control manually, there's a nicer shortcut: The
$Breadcrumbs
variable.
$Breadcrumbs
There are a number of arguments that can be passed in - see SiteTree::Breadcrumbs() for usage.
By default, it uses the template defined in templates/BreadcrumbsTemplate.ss
of the silverstripe/cms
module.
To customise the markup that $Breadcrumbs
generates, copy templates/BreadcrumbsTemplate.ss
from the silverstripe/cms
module to your theme (e.g.: themes/your-theme/templates/BreadcrumbsTemplate.ss
).
Modify the newly copied template and flush your Silverstripe CMS cache.
SilverStripeNavigator
The SilverStripeNavigator can be used on the front end for any page using a ContentController. It provides useful functionality for content authors such as showing whether the page being viewed is in published or draft mode, giving links to swap viewing modes, and a link to the CMS edit form for that page.
It's recommended to only display this for logged on users who have access to the CMS.
<% if $HasPerm('CMS_ACCESS') %>$SilverStripeNavigator<% end_if %>
Forms
$Form
A page will normally contain some content and potentially a form of some kind. For example, the log-in page has a
Silverstripe CMS log-in form. If you are on such a page (and the form is implements in a method called Form()
or getForm()
),
the $Form
variable will contain the HTML content of the form.
Placing it just below $Content
is a good default.
Related lessons
Related documentation
API documentation
- ContentController: The main controller responsible for handling pages.
- Controller: Generic controller (not specific to pages.)
- DataObject: Underlying model class for page objects.
- ViewableData: Underlying object class for pretty much anything displayable.