Interpolations

The format of interpolations is ${expression}, where expression can be any kind of expression (e.g. ${100 + x}).

The interpolation is used to insert the value of the expression converted to a string. Interpolations can be used only in two places: in text sections (e.g., <h1>Hello ${name}!</h1>) and in string literal expressions (e.g., <#include "/footer/${company}.html">).

WARNING: A common mistake is using <#if ${isBig}>Wow!</#if>, which is syntactically incorrect. Instead, write <#if isBig>Wow!</#if>.
<#if "${isBig}">Wow!</#if> is incorrect as well, since the parameter value will be a string, and the if directive requires a boolean value.

The result of the expression must be a string, number or date value. This is because interpolations automatically convert only numbers and dates to strings. Other types of values (such as booleans and sequences) must be converted to strings manually, or an error will terminate template processing.

Inserting strings

If the interpolation is in a text section (i.e., not in a string literal expression), the string that it will insert will be automatically escaped if an escape directive is in effect.

We strongly recommend that you utilize this to prevent cross-site-scripting attacks and badly formed HTML pages. Here's an example:

<#escape x as x?html>

...

  <p>Title: ${book.title}</p>

  <p>Description: <#noescape>${book.description}</#noescape></p>

  < >Comments:</ >

  <#list comments as comment>

    <div class="comment">

      ${comment}

    </div>

  </#list>

...

</#escape>

This example shows that when generating HTML, you should put the entire template inside the escape directive. Thus, if the book.title contains an &, it will be replaced with & in the output so the page remains well-formed HTML. If a comment contains tags such as <iframe> (or any other element), they will become to <iframe> and the like for other tags, rendering them harmless. If the data model does contain HTML, you have to neutralize the enclosing escape with a noescape. For example, if book.description in the above example is stored as HTML in the database. Without the enclosing escape, the template would look like the following:

...

  <p>Title: ${book.title?html}</p>

  <p>Description: ${book.description}</p>

  < >Comments:</ >

  <#list comments as comment>

    <div class="comment">

      ${comment?html}

    </div>

  </#list>

...

This does the same as the earlier example, but here you may forget some ?html, which is a security risk. In the earlier example, you may forget some noescape-s, which gives bad output too, but does not pose a security risk.

Inserting numerical values

If the expression evaluates to a number, the numerical value will be converted to a string according the default number format. This might include the maximum number of decimals, grouping, and others. Usually, the system sets the default number format, but you can set it using number_format setting. For more information, see the setting directive in Directive Reference. You can also override the default number format for a single interpolation using the string built-in.

The decimal separator and other symbols, such as the group separator, depend on the current locale (language, country) that is also set by the system. For example, this template:

${1.5}

produces output similar to this, if the current locale is English:

1.5

but if the current locale is Hungarian, the example produces output similar to this because Hungary uses comma as the decimal separator:

1,5

You can modify the formatting for a single interpolation with the string built-in.

Inserting date/time values

If the expression evaluates to a date, the numerical value will be transformed to text according to the default format. Usually, the system sets the default format, but you can change them using the date_format, time_format and datetime_format settings in the setting directive. For more information, see the setting directive in Directive Reference.

You can override the default formatting for a single interpolation using the string built-in.

WARNING: To display a date as text, RPL must be able to determine which parts of the date are in use: only the date part (year, month, day), only the time part (hour, minute, second, millisecond), or both. Due to technical limitations, it is not possible to detect this automatically for some variables. If you cannot find out whether the data model contains such variables, you must use the date, time and datetime built-ins; otherwise, an error will terminate template processing.

Inserting boolean values

An attempt to print boolean values with interpolation causes an error and terminates template processing. For example, this will cause an error: ${a == 2}.

However, you can convert booleans to strings with the ?string built-in. For example, to print the value of the "married" variable (assuming it's a boolean), write ${married?string("yes", "no")}.

Conversion rules

The exact rules for converting an expression value to a string (which is then subject to escaping) are shown below, in order:

If the value is a number, it is converted to a string in the format specified with the number_format setting.
If the value is any type of date (time or date-time), it is converted to a string in the format specified with the time_format, date_format, or datetime_format setting, depending on whether the date information is time-only, date-only, or a date-time. If the date type (date, time, or date-time) cannot be detected, an error will occur.
If the value is a string, there is no conversion.
In all other cases, an error will terminate template processing.

Learn more

Templates