Alternative (square bracket) syntax

Sometimes the generated content uses symbols that clashes with the default FreeMarker syntax (typically, ${...}-s that FreeMarker should print as is, without interpretation), or you use some tool that is confused by the default FreeMarker syntax (typically by < and >). While usually there are tricks to work those cases around (like you can use ${'$'}{x} to print ${x} as is) , they are often too inconvenient. Thus, the interpolation syntax can be configured to be like [=x] instead of ${x}. Also, independently of that, the FreeMarker tag syntax can be configured to use [], like in [#if x]...[/#if].

Note:

While both the "tag syntax" and "interpolation syntax" can be configured to use square brackets, they are totally independent configuration settings. Thus, the overall syntax can be like [#if x]${y}[/#if], or like <#if x>[=y]</#if> as well.

Square bracket tag syntax

Note:

This section is about the tag syntax, not the interpolation syntax. Don't confuse the two, they are independent.

Note:

This feature exists since FreeMarker 2.3.4.

FreeMarker supports an alternative tag syntax, where [ and ] is used instead of < and > in FreeMarker directives and comments, for example:

  • Calling predefined directive: [#list animals as animal]...[/#list]
  • Calling user-defined directive: [@myMacro /]
  • Comment: [#-- the comment --]

To use square tag syntax instead of the default one, the programmers should configure FreeMarker so (see Configuraton.setTagSyntax, or the tag_syntax setting). However, the tag syntax can also be enforced in the template, with the ftl directive (see later).

For example, this is how the last example of the Getting Started looks with the alternative syntax:

<p>We have these animals:
<table border=1>
  <tr><th>Name<th>Price
  [#list animals as animal]
  <tr>
    <td>
      [#if animal.size == "large"]<b>[/#if]
      ${animal.name}
      [#if animal.size == "large"]</b>[/#if]
    <td>${animal.price} Euros
  [/#list]
</table>

The square bracket and the default (angle bracket) syntax are mutually exclusive within a template; they can't be mixed. If the template uses square bracket tag syntax, then things like <#if ...> will be just static text, not FTL tags. Similarly, if the template uses the angle brackets tag syntax, things like [#if ...] are static text, not FTL tags.

If you start the file with [#ftl ...] (where the ... stands for the optional parameters; of course [#ftl] works too) the file will use square bracket tag syntax regardless of the configuration settings (but that does not change the interpolation syntax to [=...]). Similarly, if you start the file with <#ftl ...> the file will use the normal (angle bracket) tag syntax. If there is no ftl directive in the file, then the programmer decides what the tag syntax will be by configuring FreeMarker (programmers see Configuration.setTagSyntax(int) in the API javadocs). Most probably the programmers use the factory default.

Square bracket interpolation syntax

Note:

This section is about the interpolation syntax, not the tag syntax. Don't confuse the two, they are independent.

Note:

This feature exists since FreeMarker 2.3.28

In this case instead of ${expression} (and the deprecated #{expression}) you write [=expression]. This syntax is activated by the programmers from the configuration (see Configuration.setInterpolationSyntax in the Java API); unlike the tag syntax, it can't be specified inside the template. It can be used both together with, and without the square bracket tag syntax, as they are technically unrelated, but it's probably more aesthetic to use square bracket tag syntax when you use square bracket interpolation syntax:

[#--
  Note:
  This example uses both interpolation_syntax=squareBracket and tag_syntax=squareBracket,
  but you can also use interpolation_syntax=squareBracket and tag_syntax=angleBracket.
--]
<p>We have these animals:
<table border=1>
  <tr><th>Name<th>Price
  [#list animals as animal]
  <tr>
    <td>
      [#if animal.size == "large"]<b>[/#if]
      [=animal.name]
      [#if animal.size == "large"]</b>[/#if]
    <td>[=animal.price] Euros
  [/#list]
</table>

When square bracket interpolation syntax is used, ${expression} and #{expression} in the template will be just static text, which is printed as is. This is mostly useful if you generate output that should contain those (especially ${expression} is frequent), such as when generating JSP files.

There's also a third tag syntax, "dollar", where only the interpolation syntax is ${expression}, and the deprecated #{expression} is just static text. (The one where #{expression} is still an interpolation is called the "legacy" interpolation syntax, and is the default for backward compatibility.)