Versions:

Formatting and Casting

All objects that are being rendered in a template should be a ViewableData instance such as DataObject, DBField or Controller. From these objects, the template can include any method from the object in scope.

For instance, if we provide a HtmlText instance to the template we can call the FirstParagraph method. This will output the result of the HtmlText::FirstParagraph() method to the template.

mysite/code/Page.ss

$Content.FirstParagraph
<!-- returns the result of HtmlText::FirstParagragh() -->

$LastEdited.Format("d/m/Y")
<!-- returns the result of SS_Datetime::Format("d/m/Y") -->

Any public method from the object in scope can be called within the template. If that method returns another ViewableData instance, you can chain the method calls.

$Content.FirstParagraph.NoHTML
<!-- "First Paragraph" -->

<p>Copyright {$Now.Year}</p>
<!-- "Copyright 2014" -->

<div class="$URLSegment.LowerCase">
<!-- <div class="about-us"> -->
See the API documentation for HtmlText, StringField, Text for all the methods you can use to format your text instances. For other objects such as SS_Datetime objects see their respective API documentation pages.

forTemplate

When rendering an object to the template such as $Me the forTemplate method is called. This method can be used to provide default template for an object.

mysite/code/Page.php

<?php

class Page extends SiteTree {

    public function forTemplate() {
        return "Page: ". $this->Title;
    }
}

mysite/templates/Page.ss

$Me
<!-- returns Page: Home -->

Casting

Methods which return data to the template should either return an explicit object instance describing the type of content that method sends back, or, provide a type in the $casting array for the object. When rendering that method to a template, SilverStripe will ensure that the object is wrapped in the correct type and values are safely escaped.

<?php

class Page extends SiteTree {

    private static $casting = array(
        'MyCustomMethod' => 'HTMLText' 
    );

    public function MyCustomMethod() {
        return "<h1>This is my header</h1>";
    }
}

When calling $MyCustomMethod SilverStripe now has the context that this method will contain HTML and escape the data accordingly.

By default, all content without a type explicitly defined in a $casting array will be assumed to be Text content and HTML characters encoded.

Escaping

Properties are usually auto-escaped in templates to ensure consistent representation, and avoid format clashes like displaying un-escaped ampersands in HTML. By default, values are escaped as XML, which is equivalent to HTML for this purpose.

There's some exceptions to this rule, see the "security" guide.

In case you want to explicitly allow un-escaped HTML input, the property can be cast as HTMLText. The following example takes the Content field in a SiteTree class, which is of this type. It forces the content into an explicitly escaped format.

$Content.XML 
// transforms e.g. "<em>alert</em>" to "&lt;em&gt;alert&lt;/em&gt;"

Was this article helpful?