silverstripe-framework/docs/en/reference/templates-upgrading-guide.md

Moving from SilverStripe 2 to SilverStripe 3

These are the main changes to the SiverStripe 3 template language.

Control

The <% control var %>...<% end_control %> in SilverStripe prior to version 3 has two different meanings. Firstly, if the control variable is a collection (e.g. DataObjectSet), then <% control %> iterates over that set. If it's a non-iteratable object, however, <% control %> introduces a new scope, which is used to render the inner template code. This dual-use is confusing to some people, and doesn't allow a collection of objects to be used as a scope.

In SilverStripe 3, the first usage (iteration) is replaced by <% loop var %>. The second usage (scoping) is replaced by <% with var %>

Literals in Expressions

Prior to SilverStripe 3, literal values can appear in certain parts of an expression. For example, in the expression <% if mydinner=kipper %>, mydinner is treated as a property or method on the page or controller, and kipper is treated as a literal. This is fairly limited in use.

Literals can now be quoted, so that both literals and non-literals can be used in contexts where only literals were allowed before. This makes it possible to write the following:

• <% if $mydinner=="kipper" %>... which compares to the literal "kipper"
• <% if $mydinner==$yourdinner %>... which compares to another property or method on the page called yourdinner

Certain forms that are currently used in SilverStripe 2.x are still supported in SilverStripe 3 for backwards compatibility:

• <% if mydinner==yourdinner %>... is still interpreted as mydinner being a property or method, and yourdinner being a literal. It is strongly recommended to change to the new syntax in new implementations. The 2.x syntax is likely to be deprecated in the future.

Similarly, in SilverStripe 2.x, method parameters are treated as literals: MyMethod(foo) is now equivalent to $MyMethod("foo"). $MyMethod($foo) passes a variable to the method, which is only supported in SilverStripe 3.

Method Parameters

Methods can now take an arbitrary number of parameters:

$MyMethod($foo,"active", $CurrentMember.FirstName)

Parameter values can be arbitrary expressions, including a mix of literals, variables, and even other method calls.

Less sensitivity around spaces

Within a tag, a single space is equivalent to multiple consequetive spaces. e.g.

<% if $Foo %>

is equivalent to

<%   if   $Foo  %>