Overall structure

Templates are in fact programs you write in a language called FTL (for FreeMarker Template Language). This is a quite simple programming language designed for writing templates and nothing else.

A template (= FTL program) is a mix of the following sections:

  • Text: Text that will be printed to the output as is.

  • Interpolation: These sections will be replaced with a calculated value in the output. Interpolations are delimited by ${ and } (or with #{ and }, but that shouldn't be used anymore; see more here).

  • FTL tags: FTL tags are a bit similar to HTML tags, but they are instructions to FreeMarker and will not be printed to the output.

  • Comments: Comments are similar to HTML comments, but they are delimited by <#-- and -->. Comments will be ignored by FreeMarker, and will not be written to the output.

Let's see a concrete template. I have marked the template's components with colors: text, interpolation, FTL tag, comment. With the [BR]-s I intend to visualize the line breaks.

Template
<html>[BR]
<head>[BR]
  <title>Welcome!</title>[BR]
</head>[BR]
<body>[BR]
  <#-- Greet the user with his/her name -->[BR]
  <h1>Welcome ${user}!</h1>[BR]
  <p>We have these animals:[BR]
  <ul>[BR]
  <#list animals as animal>[BR]
    <li>${animal.name} for ${animal.price} Euros[BR]
  </#list>[BR]
  </ul>[BR]
</body>[BR]
</html>

FTL distinguishes upper case and lower case letters. So list is good directive name, while List is not. Similarly ${name} is not the same as ${Name} or ${NAME}

It is important to realize that interpolations can be used in text (and in string literal expressions; see later) only.

An FTL tag can't be inside another FTL tag nor inside an interpolation. For example this is WRONG: <#if <#include 'foo'>='bar'>...</#if>

Comments can be placed inside FTL tags and interpolations. For example:

Template
<h1>Welcome ${user <#-- The name of user -->}!</h1>[BR]
<p>We have these animals:[BR]
<ul>[BR]
<#list <#-- some comment... --> animals as <#-- again... --> animal>[BR]
...
Note:

For those of you who have tried the above examples: You may notice that some of spaces, tabs and line breaks are missing from the template output, even though we said that text is printed as is. Don't bother with it now. This is because the feature called ''white-space stripping'' is turned on, and that automatically removes some superfluous spaces, tabs and line breaks. This will be explained later.