Interpolations

Overview

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/time/date-time value, because (by default) only these types are converted to string by interpolation automatically. Values of other types (such as booleans, sequences) must be converted to string "manually" (see some advices later), or an error will stop the template processing.

Automatic escaping

If the interpolation is in a text section (not in a string literal expression), the text that it inserts goes through automatically escaping, if FreeMarker was properly configured. See more about escaping here....

Guide to 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 doesn't have to deal with it (but he can with the number_format setting; see in the documentation of setting directive). Also, 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:

${1.5}

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

1.5

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

1,5

since German people use comma as decimal separator.

<a href="/shop/productdetails?id=${product.id?c}">Details...</a>

Guide to inserting date/time/date-time values

If the expression evaluates to a date-like value then that will be transformed to a text according to a default format. Usually the programmer should set the default format; the template author doesn'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). Also, you can override the default formatting for a single interpolation with the string built-in.

Guide to inserting boolean values

By default 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. That's because there's no universally useful way of representing booleans (sometimes you want to print yes/no, sometimes enabled/disabled, on/off, etc.).

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")}.

FreeMarker can be configured with a default boolean format with the boolean_format setting, then ${married} and such will work. However, in most applications it's not recommended, as boolean should be rendered differently on different places, and leaving the formatting on the default is possibly just an oversight and thus should generate error.

When you want to generate JavaScript or other computer language parts, then ${someBoolean?c} ("c" stands for computer audience) should be used to print true/false. (Remember that ?c was also used to print numbers for computer audience.)

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: