INDIVIRTUAL - TECHNISCH PARTNER IN DIGITALE DIENSTVERLENING

Freemarker best practises

June 20, 2019

Freemarker best practises

For those new to Freemarker, it is a Java-based template engine. You can use it for servlet based programs and also stand alone. The templates are text files that contain placeholders like ${name}. Java files contain the values for these placeholders and so the output is generated.

In this blog you can read some best practises when using Freemarker templates. This is a 8 minute read and involves auto escaping, handling missing values, cutting off html and incompatible improvements.

Use auto escaping


Input fields may contain problematic character used by evil minded users. An example of this are the characters ‘&’ and ‘<’. Thus it is wise to escape such characters. But it can be a lot of work to find every input field in a file and escape each and every variable one by one. So it can be a good idea to turn auto escaping on. So developers do not have to think about escaping field and only add ?no_esc when it should not be escaped.

An example to achieve this is to put <#ftl output_format="XML" auto_esc=true> as first line in the freemarker file.

Handle missing values


There are different ways in Freemarker to handle missing values like ?? , ?has_content and !. This section explains the difference so you as a programmer can decide when to use which.

  • ??

This expression tells you if a variable is missing or not. The result is a boolean value. This is usually combined with if statements. An example this combination is:

<#if mouse??>
  Mouse found
<#else>
  No mouse found
  • ?has_content

?has_content is handy to use when working with strings because it also returns false if the string is empty instead of only returning false if the string is null. Same for an empty List or map. An example to use this is
<#if node.attachments?has_content>.

  • !

With the exclamation mark you can set a default value for a variable if it would result in a null value. An example of this can be: color!”Red”. So if color has a null value it gets the default value Red. This does not only work with strings. You can also do a method call when facing a null value. But you should be careful using Product.color!”red” since this can still result in an error if Product gives a null value. This problem is easily solved by placing parentheses like (Product.color)!”red”.

Do not cut off Html


It is considered bad practice to break off html. As example for something you should not do :
<#If condition><a href ”..”></#if>
<div>...</div>
<#if condition></a></#if>

This is a dangerous move since the html will break if the first or second condition fails. It is a better practice to put the link inside a Macro and use that in one condition. An example of this:

<#macro link>
    <a href “...”>< #nested></a>
<#/macro>

<@link.<div> … </div></@link>

Use the incompatible improvements setting


This is a template setting which should not be left on the default. Here you can add a version number from where you want backward compatibility. Backwards compatible makes the code not clash with earlier versions. You can specify the Freemarker version number in multiple ways but here are two examples:
  • Note that you should do this on configuration level.
  • Note that you should not use a getter to set this setting because this might break when upgrading Freemarker.

If you are configuring with properties, add in your .properties file:

incompatible_improvements=2.3.28

Or

Add this init param to your web.xml file when using FreemarkerServlet:

<init-param>
  <param-name>incompatible_improvements</param-name>
  <param-value>2.3.28</param-value>
</init-param>

Sources

Mijnisha

Mijnisha