3.5 KiB
title: Formating, Modifying and Casting Variables summary: Information on casting, security, modifying data before it's displayed to the user and how to format data within the template.
Formatting and Casting
All objects that are being rendered in a template should be a [api: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 [api:HtmlText] instance to the template we can call the FirstParagraph
method. This will
output the result of the [api:HtmlText::FirstParagraph] method to the template.
mysite/code/Page.ss
:::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.
:::ss
$Content.FirstParagraph.NoHTML
<!-- "First Paragraph" -->
<p>Copyright {$Now.Year}</p>
<!-- "Copyright 2014" -->
<div class="$URLSegment.LowerCase">
<!-- <div class="about-us"> -->
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
<?php
class Page extends SiteTree {
public function forTemplate() {
return "Page: ". $this->Title;
}
}
mysite/templates/Page.ss
:::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
<?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.
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.
In case you want to explicitly allow un-escaped HTML input, the property can be cast as [api: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.
:::ss
$Content.XML
// transforms e.g. "<em>alert</em>" to "<em>alert</em>"