Interpolations

You use interpolation to insert values into the output. There are two types of interpolations:

Warning!

A frequent mistake of users is the usage of interpolations in places where it shouldn't/can't be used. Interpolations work only in text sections (e.g. <h1>Hello ${name}!</h1>) and in string literals (e.g. <#include "/footer/${company}.html">). A typical bad usage is <#if ${isBig}>Wow!</#if>, which is syntactically WRONG. You should simply write <#if isBig>Wow!</#if>. Also, <#if "${isBig}">Wow!</#if> is WRONG too, since the parameter value will be a string, and the if directive wants a boolean value, so it will cause a runtime error.

Universal interpolations

Inserting string value

If the expression evaluates to a string then it will be simply printed to the output.

Inserting numerical value

If the expression evaluates to a number then the numerical 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 number_format setting in the documentation of setting directive).

${1.5}  

will print this if the language of output is English:

1.5  

but it will print this if the language of output is Hungarian:

1,5  

since Hungarian people use the comma as the decimal separator.

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

Warning!

As you can see, interpolations print for human audience (by default at least), as opposed to ``computer audience''. In some cases this is not good, like when you print a database record ID-s as the part of an URL or as an invisible field value in a HTML form, or when you print CSS/JavaScript numerical literals, because these printed values will be read by computer programs and not by humans. Most computer programs are very particular about the format of the numbers, and understand only a kind of simple US number formatting. For that, use the c (stands for ``computer audience'') built-in, for example:

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

Inserting date value

If the expression evaluates to a date then the numerical 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 modify the formatting for a single interpolation with the string built-in.

Warning!

To display a date as text, FreeMarker must know which parts of the date are in use, that is, if only the date part (year, month, day), or only the time part (hour, minute, second, millisecond), or both. Unfortunately, because of the technical limitations of Java platform, for some variables it is not possible to detect this automatically; ask the programmer if the data model contains such problematic variables. If it is not possible to find out which parts of the date are in use, then you must help FreeMarker with the date, time and datetime built-ins, or it will stop with error.

Inserting boolean value

An attempt to print boolean values with universal 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.

Numerical interpolations

Note

You can do more fine-gradient formatting with the string built-in and with the number_format setting even now. Numerical interpolation will be deprecated and kept for backward compatibility only when we introduce a terser syntax for using string built-in.

With numerical interpolations the value must be numerical or an error aborts template processing. The advantages over universal interpolations are:

So what is number formatting? As you have seen the second syntax of numerical insertion is: #{expression; format}. I show the usage of format by example:

For example, assume that x is 2.582 and y is 4:

           <#-- If the language is US English the output is: -->
#{x; M2}   <#-- 2.58 -->
#{y; M2}   <#-- 4    -->
#{x; m1}   <#-- 2.6 -->
#{y; m1}   <#-- 4.0 -->
#{x; m1M2} <#-- 2.58 -->
#{y; m1M2} <#-- 4.0  -->  

Page generated: 2006-03-15 13:49:01 GMT FreeMarker Manual -- For FreeMarker 2.3.6