FreeMarker (Template Engine)

Table of Contents

1 FreeMarker简介

Apache FreeMarker is a template engine: a Java library to generate text output (HTML web pages, e-mails, configuration files, source code, etc.) based on templates and changing data.

FreeMarker工作过程如图 1 所示。

freemarker_overview.png

Figure 1: FreeMarker工作过程

参考:
Apache FreeMarker Manual
Online FreeMarker Template Tester

1.1 第一个FreeMarker程序

下面程序摘自:http://freemarker.org/docs/pgui_quickstart_all.html

首先,准备好模板文件(假设名为test.ftlh):

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome ${user}!</h1>
  <p>Our latest product:</p>
  <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>

测试程序(准备数据,展开模板)如下:

import freemarker.template.*;
import java.util.*;
import java.io.*;

public class Test {

    public static void main(String[] args) throws Exception {

        /* ------------------------------------------------------------------------ */
        /* You should do this ONLY ONCE in the whole application life-cycle:        */

        /* Create and adjust the configuration singleton */
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_25);
        cfg.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
        cfg.setDefaultEncoding("UTF-8");
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
        cfg.setLogTemplateExceptions(false);


        /* ------------------------------------------------------------------------ */
        /* You usually do these for MULTIPLE TIMES in the application life-cycle:   */

        /* Create a data-model */
        Map root = new HashMap();
        root.put("user", "Big Joe");

        Product latest = new Product();
        latest.setUrl("products/greenmouse.html");
        latest.setName("green mouse");
        root.put("latestProduct", latest);

        /* Get the template (uses cache internally) */
        Template temp = cfg.getTemplate("test.ftlh");

        /* Merge data-model with template */
        Writer out = new OutputStreamWriter(System.out);
        temp.process(root, out);
        // Note: Depending on what `out` is, you may need to call `out.close()`.
        // This is usually the case for file output, but not for servlet output.
    }
}

其中,程序中使用的Product类,其定义如下:

/**
 * Product bean; note that it must be a public class!
 */
public class Product {

    private String url;
    private String name;

    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

运行上面测试程序,会输出下面内容(模板中 ${...} 内容被替换了,其它内容原封不动):

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome Big Joe!</h1>
  <p>Our latest product:</p>
  <a href="products/greenmouse.html">green mouse</a>!
</body>
</html>

2 FreeMarker Template Language (FTL)

FreeMarker模板可以看作是一个程序语言,被称为FreeMarker Template Language (FTL)。

2.1 模板文件基本组成

FreeMarker模板文件主要由如下4个部分组成:

  1. 文本:直接输出的部分。
  2. 插值:格式为 ${...}#{...} ,它们将被替换为数据模型中的内容。
  3. 注释:模板中 <#----> 之间的内容被认为是注释,FreeMarker在产生输出文件时会删掉注释。
  4. FTL指令(或称FTL标记):由FreeMarker指定,和HTML标记有点类似。一般,FTL指令的名字以 # 开头(用户可以自定义指令,名字以 @ 开头),且不能嵌套在其它的不同指令中(同一个指令有的可以嵌套,如if指令)。这是 <#if> 指令的一个例子: <#if animals.python.price == 0>Pythons are free today!</#if> ,只有当条件 animals.python.price == 0 为真时,才会输出“Pythons are free today!”。

注意:

  1. FTL区分大小写,比如 ${name}${Name} ,以及 ${NAME} 是相互不同的。
  2. “插值”只能出现在文本中(如 <h1>Hello ${name}!</h1> ),或者字符串(如 <#include "/footer/${company}.html"> )中。这种用法: <#if ${big}>...</#if> (会导致语法错误)或者这种用法 <#if "${big}">...</#if> (if指令需要boolean值,但这里是string,会导致运行时错误)都是错误的用法。对于这个例子,正确的写法为 <#if big>...</#if>
  3. 注释可以内嵌在FTL指令或者插值中。如: ${user <#-- The name of user -->}!</h1> 是合法的写法。

2.2 FTL指令(标记)

一般地,FTL标记以“开始标记” <#directivename parameters> 开始,以“结束标记” </#directivename> 结尾;也有一些标记(如 <#include something> )只有“开始标记”,而没有“结束标记”(你也无需写为 <#include something /> ,因为FreeMarker知道include指令不需要结束标记)。

FreeMarker允许用户自定义标记,用户自定义标记以 <@mydirective parameters> 开始,以 </@mydirective> 结尾;如果用户自定义标记不需要嵌套内容,则应用写为 <@mydirective parameters /> ,这类似于xml标记 <img ... />

参考:
FTL Directive Reference

2.2.1 指令:assign

使用 assign 指令可以创建一个新变量,或者替换一个存在的变量。其基本形式为:

<#assign name1=value1 name2=value2 ... nameN=valueN>

2.2.2 指令:function, return

使用 function 指令可以创建函数。语法为:

<#function name param1 param2 ... paramN>
  ...
  <#return returnValue>
  ...
</#function>

如,有下面模板:

<#function avg x y>
  <#return (x + y) / 2>
</#function>
${avg(2, 3)}

模板展开后会输出:

2.5

2.2.3 指令:if

if 指令是一个常用的分支控制指令。语法如下:

<#if condition>
  ...
<#elseif condition2>
  ...
<#elseif condition3>
  ...
...
<#else>
  ...
</#if>

其中, elseif 部分和 else 部分都是可选的。

if 指令可以嵌套使用。如:

<#if x == 1>
  x is 1
  <#if y == 1>
    and y is 1 too
  <#else>
    but y is not
  </#if>
<#else>
  x is not 1
  <#if y < 0>
    and y is less than 0
  </#if>
</#if>

if 指令使用实例:

<#assign x=2>
<#if x == 1>
  x is 1
<#elseif x == 2>
  x is 2
<#elseif x == 3>
  x is 3
</#if>

上面模板展开后会输出:

  x is 2

2.2.4 指令:include

可以使用 include 指令把另外一个模板插入到当前模板中,其语法为:

<#include path options>

其中,path为另外一个模板的路径,option是可选的。

例如,文件/common/copyright.ftl的内容为:

Copyright 2001-2002 ${me}<br>
All rights reserved.

有下面模板:

<#assign me = "Juila Smith">
<h1>Some test</h1>
<p>Yeah.
<hr>
<#include "/common/copyright.ftl">

模板展开后会输出:

<h1>Some test</h1>
<p>Yeah.
<hr>
Copyright 2001-2002 Juila Smith
All rights reserved.

2.2.5 指令:list, else, items, sep, break

list 指令用于迭代输出数据模型中的集合。

下面是list指令的基本形式(这里称为形式一):

<#list sequence as item>
    Part repeated for each item
<#else>
    Part executed when there are 0 items
</#list>

其中, else 部分可以省略;item可取任意名字,代表被迭代输出的集合元素。

比如,有下面模板:

<#list ['Joe', 'Kate', 'Fred'] as user>
  <p>${user}
</#list>

模板展开后会输出:

  <p>Joe
  <p>Kate
  <p>Fred

list 指令可以嵌套使用。如,有下面模板:

<#list 1..2 as i>
  <#list 1..3 as j>
    i = ${i}, j = ${j}
  </#list>
</#list>

模板展开后会输出:

    i = 1, j = 1
    i = 1, j = 2
    i = 1, j = 3
    i = 2, j = 1
    i = 2, j = 2
    i = 2, j = 3
2.2.5.1 items指令

下面是list指令的另一种形式(这里称为形式二):

<#list sequence>
    Part executed once if we have more than 0 items
    <#items as item>
        Part repeated for each item
    </#items>
    Part executed once if we have more than 0 items
<#else>
    Part executed when there are 0 items
</#list>

比如,有下面模板:

<#list ['Joe', 'Kate', 'Fred']>
  <ul>
    <#items as user>
      <li>${user}</li>
    </#items>
  </ul>
<#else>
  <p>No users
</#list>

模板展开后会输出:

  <ul>
      <li>Joe</li>
      <li>Kate</li>
      <li>Fred</li>
  </ul>
2.2.5.2 sep指令

sep is used when you have to display something between each item (but not before the first item or after the last item).

比如,有下面模板:

<#list ['Joe', 'Kate', 'Fred'] as user>${user}<#sep>, </#sep></#list>

模板展开后会输出:

Joe, Kate, Fred
2.2.5.3 break指令

You can exit the iteration at any point with the break directive.

比如,有下面模板:

<#list 1..10 as x>
  ${x}
  <#if x == 3>
    <#break>
  </#if>
</#list>

模板展开后会输出:

  1
  2
  3

2.2.6 指令:noparse

noparse 指令之间的内容会被FreeMarker原封不动地输出,其语法为:

<#noparse>
  ...
</#noparse>

2.2.7 指令:switch, case, default, break

FreeMarker中 switch, case, default, break 指令,类似于Java的switch语句。语法如下:

<#switch value>
  <#case refValue1>
    ...
    <#break>
  <#case refValue2>
    ...
    <#break>
  ...
  <#case refValueN>
    ...
    <#break>
  <#default>
    ...
</#switch>

3 Expressions

When you supply values for interpolations or directive parameters you can use variables or more complex expressions. Let's see some concrete examples:

  • When you supply value for interpolations: The usage of interpolations is ${expression} where expression gives the value you want to insert into the output as text. For example ${(5 + 8)/2} prints "6.5" to the output.
  • When you supply a value for the directive parameter: For example, the syntax of if directive is: <#if expression>...</#if>. The expression here must evaluate to a boolean value. For example in <#if 2 < 3> the 2 < 3 (2 is less than 3) is an expression which evaluates to true.

参考:
FreeMarker expressions cheat sheet

3.1 表达式及其实例

Table 1: FreeMarker表达式及其实例
Expression Example
String "Foo" or 'Foo'
Number 123.45
Bollean true, false
Sequence ["foo", "bar"]
Hash {"name":"green mouse", "price":150}

3.2 Built-in(?)

The so-called built-ins are like subvariables that aren't coming from the data-model, but added by FreeMarker to the values. In order to make it clear where subvariables comes from, you have to use ? (question mark) instead of . (dot) to access them.

不同类型的表达式,对应有不同的built-in,可以通过问号 ? 来访问built-in。

下面是一些常用built-ins的实例。比如,有下面模板:

${"hello freemarker"?upper_case}
${"hello freemarker"?cap_first}
${"hello freemarker"?length}
${["foo", "bar"]?size}
${["foo", "bar"]?join(", ")}

模板展开后会输出:

HELLO FREEMARKER
Hello freemarker
16
2
foo, bar

参考:
FreeMarker Built-in Reference

3.3 处理null值

如果data model中某值为null,不能直接访问它,否则会把异常。假设user并没有在data model中定义,如果模板中有代码 ${user} ,则会报异常。

参考:
Handling missing values

3.3.1 测试表达式是否存在(??)

可以通过 unsafe_expr?? 或者 (unsafe_expr)?? 来测试表达式 unsafe_expr 是否为null。

比如,有下面模板:

<#if mouse??>
  Mouse found
<#else>
  No mouse found
</#if>
Creating mouse...
<#assign mouse = "Jerry">
<#if mouse??>
  Mouse found
<#else>
  No mouse found
</#if>

模板展开后会输出:

  No mouse found
Creating mouse...
  Mouse found

3.3.2 表达式默认值(!)

当表达式为null时,我们可以为它指定默认值。为表达式 unsafe_expr 指定默认值为 default_expr 的写法为: unsafe_expr!default_expr 或者 (unsafe_expr)!default_expr

比如,有下面模板:

${mouse!"No mouse."}
<#assign mouse="Jerry">
${mouse!"No mouse."}

模板展开后会输出:

No mouse.
Jerry

4 自定义指令

FreeMarker中可以自定义指令。 和内置指令以 # 开头不同,自定义指令以 @ 开头。

参考:
Defining your own directives: http://freemarker.org/docs/dgui_misc_userdefdir.html

4.1 用macro指令自定义指令

macro 指令可以自定义指令。

比如,有下面模板:

<#macro test>
  This is test text
</#macro>
<#-- call the macro: -->
<@test/>
<@test/>

模板展开后会输出:

  This is test text
  This is test text

再看一个带参数的例子。比如,有下面模板:

<#macro test foo bar baaz>
  Test text, and the params: ${foo}, ${bar}, ${baaz}
</#macro>
<#-- call the macro: -->
<@test foo="a" bar="b" baaz=5*5-2/>
<@test foo="x" bar="y" baaz=10/>

模板展开后会输出:

  Test text, and the params: a, b, 23
  Test text, and the params: x, y, 10

4.2 在Java中自定义指令

在Java中自定义指令需要实现freemarker.template.TemplateDirectiveModell接口。简单例子,可参考:http://freemarker.org/docs/pgui_datamodel_directive.html

5 Miscellaneous

5.1 Auto-escaping and output formats

当我们用FreeMarker生成HTML文件时,假设模板中有 ${name}$ ,而程序中name的值为 Someone & Co. ,在HTML中,它的正确输出其实应该是 Someone &amp; Co. 。通过配置,可以让FreeMarker帮我们进行自动转义。

方法一:
The recommended practice is using "ftlh" file extension to activate HTML auto-escaping, and "ftlx" file extension to activate XML auto-escaping.

方法二:
在模板文件的第一行用 ftl 指令设置输出格式,如:

<#ftl output_format="HTML">

下面是一些内置的output format:

Table 2: The predefined output formats
Name Description MIME Type Default implementation
HTML Escapes <, >, &, ", ' as &lt;, &gt;, &amp;, &quot;, &#39; text/html HTMLOutputFormat.INSTANCE
XHTML Escapes <, >, &, ", ' as &lt;, &gt;, &amp;, &quot;, &#39; application/xhtml+xml XHTMLOutputFormat.INSTANCE
XML Escapes <, >, &, ", ' as &lt;, &gt;, &amp;, &quot;, &apos; application/xml XMLOutputFormat.INSTANCE
RTF Escapes {, }, \ as \{, \}, \\ application/rtf RTFOutputFormat.INSTANCE
undefined Doesn't escape. The default output format. None (null) UndefinedOutputFormat.INSTANCE

参考:
Auto-escaping and output formats

5.1.1 指令:outputformat

使用指令 outputformat 可以强制改变“输出格式”。其语法为:

<#outputformat formatName>
  ...
</#outputFormat>

比如,有下面模板:

<#assign mo1 = "Foo's bar {}">
HTML:  <#outputformat 'HTML'>${mo1}</#outputformat>
XML:  <#outputformat 'XML'>${mo1}</#outputformat>
RTF:  <#outputformat 'RTF'>${mo1}</#outputformat>

模板展开后会输出:

HTML:  Foo&#39;s bar {}
XML:  Foo&apos;s bar {}
RTF:  Foo's bar \{\}

5.1.2 指令:noautoesc

使用指令 noautosec 可以临时禁止对输出的转义。

比如,有下面模板:

<#ftl output_format="HTML">
${"&"}
${"<"}
<#noautoesc>
  ${"&"}
  ${"<"}
</#noautoesc>
${"&"}
${"<"}

模板展开后会输出:

&amp;
&lt;
  &
  <
&amp;
&lt;

Author: cig01

Created: <2017-03-31 Fri 00:00>

Last updated: <2017-12-13 Wed 13:41>

Creator: Emacs 25.3.1 (Org mode 9.1.4)