Formatting, casting, and escaping variable content#

Classes that subclass ModelData (such as DataObject, DBField or Controller) can define how their values should be cast or escaped when used in a template.

Most of the details on this page refer to casting values using the configuration on ModelData.

Casting#

The templating system casts variables and the result of method calls into objects (usually one of the various DBField classes) before outputting them in the final rendered markup. This casting functionality lives in the CastingService class.

DBField classes provide methods that developers can use to format data in the template (e.g. choosing how to format a date), as well as defining whether HTML markup in that data will be escaped, stripped, or included directly in the rendered result.

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 (using the same format as the $db array described in Data types and casting) in the $casting array for the object. When rendering that method to a template, Silverstripe CMS will ensure that the object is wrapped in the correct type. This provides you with all of the methods available in that class, and ensures and values are safely escaped.

Note that if an object is returned from the method, that object will be retained instead of using the $casting configuration.

namespace App\Data;

use SilverStripe\Model\ModelData;

class MyTemplatedObject extends ModelData
{
    private static $casting = [
        'Header' => 'HTMLText',
    ];

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

When calling $MyCustomMethod on the above object from a template, Silverstripe CMS now has the context that this method contains HTML, so it won't escape the value.

Common casting types#

Values can be cast as any DBField instance, but these tend to be the most common:

• Text Which is a plain text string, and will be safely encoded via htmlspecialchars() when placed into a template.
• Varchar which is the same as Text 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 a HTMLFragment, 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.

Formatting#

As has been mentioned in a few sections of documentation already, in a template you have access to all of the public properties and methods of any object in scope. For instance, if we provide a DBHtmlText instance to the template (either directly by returning it from a method, or by declaring it in the $db configuration for a DataObject model, or by declaring it in the $casting configuration), we can use $MyField.FirstParagraph in the template. This will output the result of the DBHtmlText::FirstParagraph() method to the template.

<%-- app/src/Page.ss --%>

<%-- prints the result of DBHtmlText::FirstParagragh() --%>
$Content.FirstParagraph

<%-- prints the result of DBDatetime::Format("d/m/Y") --%>
$LastEdited.Format("d/m/Y")

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

<%-- prints the first paragraph of content for the first item in the list --%>
$MyList.First.Content.FirstParagraph

<%-- prints "Copyright 2023" --%>
<p>Copyright {$Now.Year}</p>

<%-- prints <div class="about-us"> --%>
<div class="$URLSegment.LowerCase">

Commonly useful formatting methods#

All DBField instances share the following useful methods for formatting their values:

• RAW() - outputs the raw value into the template with no escaping.
• XML() (and its alias HTML()) - encodes the value (using htmlspecialchars()) before outputting it.

• CDATA - formats the 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.

• JS() - ensures that text is properly escaped for use in JavaScript.

  • e.g. var fieldVal = '$Field.JS'; can be used in JavaScript defined in templates to encode values safely.

• ATT() (and its alias HTMLATT()) - formats the value appropriate for an HTML attribute string

  • e.g. <div data-my-field="$MyField.HTMLATT"></div>
• RAWURLATT() - encodes strings for use in URLs via rawurlencode()
• URLATT() - encodes strings for use in URLs via urlencode()
• JSON() - encodes the value as a JSON string via json_encode()

Escaping HTML values in templates#

The concept of escaping values in templates is ultimately just a combination of formatting and casting.

Values are typically escaped (i.e. the special HTML characters are encoded) in templates by either not declaring a casting type, or by defaulting to the Text casting type.

See the casting section above for instructions on configuring your model to declare casting types for fields, and how some of the more common casting types affect escaping.

Escape methods in templates#

Within the template, fields can have their encoding customised at a certain level with format methods.

See the formatting section above for some of the more common formatting methods available and how they affect escaping.

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>) - limits output to the first <num> sentences in the content. This method internally calls Plain(), converting HTML content into plain text.