6.6 KiB
title: Formatting, 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 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 DBHtmlText instance to the template we can call the FirstParagraph
method. This will
output the result of the DBHtmlText::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"> -->
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
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.
class Page extends SiteTree
{
private static $casting = [
'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.
For every field used in templates, a casting helper will be applied. This will first check for any
casting
helper on your model specific to that field, and will fall back to the default_cast
config
in case none are specified.
By default, ViewableData.default_cast
is set to Text
, which will ensure all fields have special
characters HTML escaped by default.
The most common casting types are:
Text
Which is a plain text string, and will be safely encoded via HTML entities when placed into a template.Varchar
which is the same asText
but for single-line text that should not have line breaks.HTMLFragment
is a block of raw HTML, which should not be escaped. Take care to sanitise any HTML value saved into the database.HTMLText
is aHTMLFragment
, but has shortcodes enabled. This should only be used for content that is modified via a TinyMCE editor, which will insert shortcodes.Int
for integers.Decimal
for floating point values.Boolean
For boolean values.Datetime
for date and time.
See the Model data types and casting section for instructions on configuring your model to declare casting types for fields.
Escape methods in templates
Within the template, fields can have their encoding customised at a certain level with format methods. See DBField for the specific implementation, but they will generally follow the below rules:
$Field
with no format method supplied will correctly cast itself for the HTML template, as defined by the casting helper for that field. In most cases this is the best method to use for templates.$Field.XML
Will invokehtmlentities
on special characters in the value, even if it's already cast as HTML.$Field.ATT
will ensure the field is XML encoded for placement inside a HTML element property. This will invokehtmlentities
on the value (even if already cast as HTML) and will escape quotes.Field.JS
will cast this value as a javascript string. E.g.var fieldVal = '$Field.JS';
can be used in javascript defined in templates to encode values safely.$Field.CDATA
will cast this value safely for insertion as a literal string in an XML file. E.g.<element>$Field.CDATA</element>
will ensure that the<element>
body is safely escaped as a string.
Cast summary methods
Certain subclasses of DBField also have additional summary or manipulations methods, each of which can be chained in order to perform more complicated manipulations.
For instance, The following class methods can be used in templates for the below types:
Text / HTMLText methods:
$Plain
Will convert any HTML to plain text version. For example, could be used for plain-text version of emails.$LimitSentences(<num>)
Will limit to the first<num>
sentences in the content. If called on HTML content this will have all HTML stripped and converted to plain text.