2019-11-18 05:58:33 +01:00
---
2014-10-13 09:49:30 +02:00
title: Common Variables
2014-10-30 05:16:38 +01:00
summary: Some of the common variables and methods your templates can use, including Menu, SiteConfig, and more.
2019-11-18 05:58:33 +01:00
---
2014-10-13 09:49:30 +02:00
# Common Variables
2019-10-08 00:08:21 +02:00
The page below describes a few of common variables and methods you'll see in a SilverStripe template. This is not an
exhaustive list. From your template you can call any method, database field, or relation on the object which is
2021-05-16 22:22:53 +02:00
currently in scope as well as its subclasses or extensions.
2014-10-13 09:49:30 +02:00
2019-10-08 00:08:21 +02:00
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 ](syntax#scope ) 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
2017-07-03 03:22:12 +02:00
[TemplateGlobalProvider ](api:SilverStripe\View\TemplateGlobalProvider ) interface.
2014-10-13 09:49:30 +02:00
2019-11-18 05:58:33 +01:00
[notice]
2019-10-08 00:08:21 +02:00
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 subclasses **or**
2014-10-13 09:49:30 +02:00
extensions.
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-13 09:49:30 +02:00
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 [Formating, Modifying and Casting Variables ](casting ) documentation.
2019-11-18 05:58:33 +01:00
[alert]
2014-10-13 09:49:30 +02:00
Some of the following only apply when you have the `CMS` module installed. If you're using the `Framework` alone, this
functionality may not be included.
2019-11-18 05:58:33 +01:00
[/alert]
2014-10-13 09:49:30 +02:00
## Base Tag
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< head >
< % base_tag %>
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
..
< / head >
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-11-18 05:58:33 +01:00
The `<% base_tag %>` placeholder is replaced with the HTML base element. Relative links within a document (such as `< img
2021-02-11 00:18:36 +01:00
src="someimage.jpg" alt="">`) will become relative to the URI specified in the base tag. This ensures the browser knows where
2014-10-13 09:49:30 +02:00
to locate your site’ s images and css files.
It renders in the template as `<base href="http://www.yoursite.com" /><!--[if lte IE 6]></base><![endif]-->`
2019-11-18 05:58:33 +01:00
[alert]
A `<% base_tag %>;` is nearly always required or assumed by SilverStripe to exist.
[/alert]
2014-10-13 09:49:30 +02:00
## CurrentMember
2017-10-27 04:38:27 +02:00
Returns the currently logged in [Member ](api:SilverStripe\Security\Member ) instance, if there is one logged in.
2014-10-13 09:49:30 +02:00
2017-10-27 04:38:27 +02:00
```ss
< % if $CurrentMember %>
2020-03-23 03:54:30 +01:00
Welcome back, $CurrentMember.FirstName
2017-10-27 04:38:27 +02:00
< % end_if %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
## Title and Menu Title
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$Title
$MenuTitle
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
Most objects within SilverStripe will respond to `$Title` (i.e they should have a `Title` database field or at least a
`getTitle()` method).
2019-10-08 00:08:21 +02:00
The CMS module in particular provides two fields to label a page: `Title` and `MenuTitle` . `Title` is the title
2014-10-13 09:49:30 +02:00
displayed on the web page, while `MenuTitle` can be a shorter version suitable for size-constrained menus.
2019-11-18 05:58:33 +01:00
[notice]
2014-10-13 09:49:30 +02:00
If `MenuTitle` is left blank by the CMS author, it'll just default to the value in `Title` .
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-13 09:49:30 +02:00
## Page Content
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$Content
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
It returns the database content of the `Content` property. With the CMS Module, 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.
2019-11-18 05:58:33 +01:00
[info]
2019-10-08 00:08:21 +02:00
Please note that this database content can be "versioned", meaning that draft content edited in the CMS can be different
2014-10-13 09:49:30 +02:00
from published content shown to your website visitors. In templates, you don't need to worry about this distinction.
2019-10-08 00:08:21 +02:00
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 ](/../model/versioning ) for
2014-10-13 09:49:30 +02:00
more details).
2019-11-18 05:58:33 +01:00
[/info]
2014-10-13 09:49:30 +02:00
### SiteConfig: Global settings
2019-11-18 05:58:33 +01:00
[notice]
2019-10-08 00:08:21 +02:00
`SiteConfig` is a module that is bundled with the CMS. If you wish to include `SiteConfig` in your framework only
2021-05-16 22:22:53 +02:00
web pages, you'll need to install it via composer.
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-13 09:49:30 +02:00
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$SiteConfig.Title
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-10-08 00:08:21 +02:00
The [SiteConfig ](../configuration/siteconfig ) object allows content authors to modify global data in the CMS, rather
2014-10-13 09:49:30 +02:00
than PHP code. By default, this includes a Website title and a Tagline.
2019-10-08 00:08:21 +02:00
`SiteConfig` can be extended to hold other data, for example a logo image which can be uploaded through the CMS or
2014-10-13 09:49:30 +02:00
global content such as your footer content.
## 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
2019-10-08 00:08:21 +02:00
on a per-page basis.
2014-10-13 09:49:30 +02:00
2019-11-18 05:58:33 +01:00
[notice]
2014-10-13 09:49:30 +02:00
If you don’ t want to include the title tag use `$MetaTags(false)` .
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-13 09:49:30 +02:00
By default `$MetaTags` renders:
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< title > Title of the Page< / title >
< meta name = "generator" http-equiv = "generator" content = "SilverStripe 3.0" / >
< meta http-equiv = "Content-type" content = "text/html; charset=utf-8" / >
2017-08-03 02:51:32 +02:00
```
2017-10-27 04:38:27 +02:00
`$MetaTags(false)` will render
2014-10-13 09:49:30 +02:00
2017-10-27 04:38:27 +02:00
```ss
< meta name = "generator" http-equiv = "generator" content = "SilverStripe 3.0" / >
< meta http-equiv = "Content-type" content = "text/html; charset=utf-8" / >
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
If using `$MetaTags(false)` we can provide a more custom `title` .
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$MetaTags(false)
< title > $Title - Bob's Fantasy Football< / title >
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-02-01 18:33:20 +01:00
### 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):
```php
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;
}
```
2014-10-13 09:49:30 +02:00
## Links
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< a href = "$Link" > ..< / a >
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-10-08 00:08:21 +02:00
All objects that could be accessible in SilverStripe 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
2014-10-13 09:49:30 +02:00
link.
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$Link
<!-- returns /about - us/offices/ -->
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
$AbsoluteLink
<!-- returns http://yoursite.com/about - us/offices/ -->
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
### Linking Modes
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$isSection
$isCurrent
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2015-11-23 21:10:47 +01:00
When looping over a list of `SiteTree` instances through a `<% loop $Menu %>` or `<% loop $Children %>` , `$isSection` and `$isCurrent`
2019-10-08 00:08:21 +02:00
will return true or false based on page being looped over relative to the currently viewed page.
2014-10-13 09:49:30 +02:00
For instance, to only show the menu item linked if it's the current one:
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % if $isCurrent %>
$Title
< % else %>
< a href = "$Link" > $Title< / a >
< % end_if %>
2017-08-03 02:51:32 +02:00
```
2015-11-23 21:10:47 +01:00
2017-08-03 02:51:32 +02:00
An example for checking for `current` or `section` is as follows:
2015-11-23 21:10:47 +01:00
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< a class = "<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>" href = "$Link" > $MenuTitle< / a >
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2015-11-23 21:10:47 +01:00
**Additional Utility Method**
2014-10-13 09:49:30 +02:00
2014-10-30 05:16:38 +01:00
* `$InSection(page-url)` : This if block will pass if we're currently on the page-url page or one of its children.
2014-10-13 09:49:30 +02:00
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % if $InSection(about-us) %>
< p > You are viewing the about us section< / p >
< % end_if %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
### URLSegment
2019-10-08 00:08:21 +02:00
This returns the part of the URL of the page you're currently on. For example on the `/about-us/offices/` web page the
2014-10-13 09:49:30 +02:00
`URLSegment` will be `offices` . `URLSegment` cannot 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.
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< div id = "section-$URLSegment" >
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
< / div >
2014-10-13 09:49:30 +02:00
2017-10-27 04:38:27 +02:00
<!-- returns <div id="section - offices"> -->
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
## ClassName
2019-10-08 00:08:21 +02:00
Returns the class of the current object in [scope ](syntax#scope ) such as `Page` or `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
2014-10-13 09:49:30 +02:00
behavior based on the page type used:
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< body class = "$ClassName" >
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
<!-- returns <body class="HomePage">, <body class="BlogPage"> -->
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
## Children Loops
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % loop $Children %>
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
< % end_loop %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
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.
2019-11-18 05:58:33 +01:00
[alert]
2019-10-08 00:08:21 +02:00
For doing your website navigation most likely you'll want to use `$Menu` since its independent of the page
2014-10-13 09:49:30 +02:00
context.
2019-11-18 05:58:33 +01:00
[/alert]
2014-10-13 09:49:30 +02:00
### ChildrenOf
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % loop $ChildrenOf(< my-page-url > ) %>
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
< % end_loop %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-10-08 00:08:21 +02:00
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
2014-10-13 09:49:30 +02:00
pages underneath a "staff" holder on any page, regardless if its on the top level or elsewhere.
### AllChildren
2019-10-08 00:08:21 +02:00
Content authors have the ability to hide pages from menus by un-selecting the `ShowInMenus` checkbox within the CMS.
2014-10-30 05:16:38 +01:00
This option will be honored by `<% loop $Children %>` and `<% loop $Menu %>` however if you want to ignore the user
2014-10-13 09:49:30 +02:00
preference, `AllChildren` does not filter by `ShowInMenus` .
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % loop $AllChildren %>
...
< % end_loop %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
### Menu Loops
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % loop $Menu(1) %>
...
< % end_loop %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
`$Menu(1)` returns the top-level menu of the website. You can also create a sub-menu using `$Menu(2)` , and so forth.
2019-11-18 05:58:33 +01:00
[notice]
2014-10-13 09:49:30 +02:00
Pages with the `ShowInMenus` property set to `false` will be filtered out.
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-13 09:49:30 +02:00
## Access to a specific Page
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % with $Page(my-page) %>
$Title
< % end_with %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-10-08 00:08:21 +02:00
Page will return a single page from site, looking it up by URL.
2014-10-13 09:49:30 +02:00
## Access to Parent and Level Pages
### Level
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % with $Level(1) %>
$Title
< % end_with %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-10-08 00:08:21 +02:00
Will return a page in the current path, at the level specified by the numbers. It is based on the current page context,
2014-10-13 09:49:30 +02:00
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
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
<!-- given we're on 'Bob Marley' in "about us > staff > bob marley" -->
2017-08-03 02:51:32 +02:00
2017-10-27 04:38:27 +02:00
$Parent.Title
<!-- returns 'staff' -->
2014-10-13 09:49:30 +02:00
2017-10-27 04:38:27 +02:00
$Parent.Parent.Title
<!-- returns 'about us' -->
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
## Navigating Scope
2016-11-01 05:56:32 +01:00
See [scope ](syntax#scope ).
2014-10-13 09:49:30 +02:00
## Breadcrumbs
2019-10-08 00:08:21 +02:00
Breadcrumbs are the path of pages which need to be taken to reach the current page, and can be a great navigation aid
2014-10-13 09:49:30 +02:00
for website users.
2019-10-08 00:08:21 +02:00
While you can achieve breadcrumbs through the `$Level(<level>)` control manually, there's a nicer shortcut: The
2014-10-13 09:49:30 +02:00
`$Breadcrumbs` variable.
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$Breadcrumbs
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2017-10-06 17:00:32 +02:00
By default, it uses the template defined in `templates/BreadcrumbsTemplate.ss`
of the `silverstripe/cms` module.
2014-10-13 09:49:30 +02:00
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % if $Pages %>
< % loop $Pages %>
< % if $Last %>$Title.XML< % else %>< a href = "$Link" > $MenuTitle.XML< / a > » < % end_if %>
< % end_loop %>
< % end_if %>
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2019-11-18 05:58:33 +01:00
[info]
2019-10-08 00:08:21 +02:00
To customise the markup that `$Breadcrumbs` generates, copy `templates/BreadcrumbsTemplate.ss`
from the `silverstripe/cms` module to your theme (e.g.: `themes/you-theme/templates/BreadcrumbsTemplate.ss` ).
Modify the newly copied template and flush your Silverstripe CMS cache.
2019-11-18 05:58:33 +01:00
[/info]
2014-10-13 09:49:30 +02:00
## Forms
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
$Form
2017-08-03 02:51:32 +02:00
```
2014-10-13 09:49:30 +02:00
2021-05-16 22:22:53 +02:00
A page will normally contain some content and potentially a form of some kind. For example, the log-in page has a
2019-10-08 00:08:21 +02:00
SilverStripe log-in form. If you are on such a page, the `$Form` variable will contain the HTML content of the form.
2014-10-13 09:49:30 +02:00
Placing it just below `$Content` is a good default.
2017-11-27 04:39:17 +01:00
## Related Lessons
* [Adding dynamic content ](https://www.silverstripe.org/learn/lessons/v4/adding-dynamic-content-1 )
## Related Documentation
2014-10-13 09:49:30 +02:00
* [Casting and Formating Variables ](casting )
* [Template Inheritance ](template_inheritance )
## API Documentation
2017-07-03 03:22:12 +02:00
* [ContentController ](api:SilverStripe\CMS\Controllers\ContentController ): The main controller responsible for handling pages.
* [Controller ](api:SilverStripe\Control\Controller ): Generic controller (not specific to pages.)
* [DataObject ](api:SilverStripe\ORM\DataObject ): Underlying model class for page objects.
* [ViewableData ](api:SilverStripe\View\ViewableData ): Underlying object class for pretty much anything displayable.