Interpolations

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

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

The result of the expression must be a string, number or date value. This is because only numbers and dates will be converted to string by the interpolation automatically, other types of values (such as booleans, sequences) must be converted to string "manually" somehow (see some advices later), or an error will stop the template processing.

Guide for inserting strings; don't forget escaping!

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. If you are generating HTML it's strongly recommended to utilize this to prevent cross-site-scripting attacks and not-well-formed HTML pages. Here's a quick example:

This example shows that when generating HTML you better put the whole template inside the escape directive. Thus, if the book.title contains &, it will be replaced with &amp; in the output so the page remains well-formed HTML. If a user comment contains tags like <iframe> (or any other element), they will become to &lt;iframe&gt; and like, rendering them harmless. But sometimes you really have HTML in the data-model, like let's assume book.description above is stored as HTML in the database, in which case you have to neutralize the enclosing escape with a noescape. Without the enclosing escape, the template would look like:

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

Guide for inserting numerical values

If the expression evaluates to a number then the numerical value will be converted to string according the default number format. This may includes the maximum number of decimals, grouping, and like. Usually the programmer should set the default number format; the template author don't have to deal with it (but he can with the number_format setting; see in the documentation of setting directive). You can override the default number format for a single interpolation with the string built-in.

The decimal separator used (and other such symbols, like the group separator) depends on the current locale (language, country), that also should be set by the programmer. For example, this template:

will print something like this if the current locale is English:

but if the current locale is Hungarian then it will print something like:

since Hungarian people use comma as decimal separator.

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

Guide for inserting date/time values

If the expression evaluates to a date then the date value will be transformed to a text according to a default format. Usually the programmer should set the default format; you don't have to deal with it (but if you care, see the date_format, time_format and datetime_format settings in the documentation of the setting directive).

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

Guide for inserting boolean values

An attempt to print boolean values with interpolation causes an error and aborts template processing. For example this will cause an error: ${a == 2} and will not print ''true'' or something like that.

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), you could write ${married?string("yes", "no")}.

The exact conversion rules

For those who are interested, the exact rules of conversion from the expression value to string (which is then still subject to escaping) are these, in this order: