1. Template + data-model = output

data-model是一个树状模型，通常是一个java对象。

2.data-model 入门

hashes（散列）：目录变量（the root, misc）

scalars（标量）：存储单个值的变量（size, price, name and foo）

sequences（序列）：They store subvariables like hashes, but here subvariables doesn't have a name, they are just items in a list. （数组？）（animals）

(root)
  |
  +- animals
  |   |
  |   +- (1st)
  |   |   |
  |   |   +- name = "mouse"
  |   |   |
  |   |   +- size = "small"
  |   |   |
  |   |   +- price = 50
  |   |
  |   +- (2nd)
  |   |   |
  |   |   +- name = "elephant"
  |   |   |
  |   |   +- size = "large"
  |   |   |
  |   |   +- price = 5000
  |   |
  |   +- (3rd)
  |       |
  |       +- name = "python"
  |       |
  |       +- size = "medium"
  |       |
  |       +- price = 4999
  |
  +- misc
     |
      +- foo = "Something"

scalars的数据类型：

String
Number
Date-like: Either a date-time (stores a date with time of the day), or a date (no time of day), or a time (time of day, no date).
Boolean

Summary

data-model呈现树状结构；
Scalars store a single value. The value can be a string or a number or a date-time/date/time or a boolean.
Hashes are containers that store other variables and associate them with a unique lookup name.
Sequences are containers that store other variables in an ordered sequence. The stored variables can be retrieved via their numerical index, starting from 0.

3. template 入门

3.1 基本语法

插值${...}：FreeMarker将在输出中将其替换为大括号内的表达式的实际值。
FTL标签（FTL=FreeMarker Template Language，FreeMarker模板语言）：类似于HTML标签（but they are instructions to FreeMarker and will not be printed to the output）。标签名以#开头（用户定义的FTL标签使用@替代#）。
注释：包含在<#--和-->之间。不会输出到最终的HTML文件中，因为FreeMarker在编译的时候会跳过这些注释。

除了以上3中语法中的内容都会被视为静态文本，即FreeMarker编译时不会处理这些文本，而是直接输出到HTML文件中。

3.2 常用指令

使用FTL标签可以引用所谓的指令。

3.2.1 if指令

例子：

Welcome ${user}<#if user == "Big Joe">, our beloved leader</#if>!

如果条件为false，<#if condition>和<#if>之间的内容将会被跳过。

配合<#else>指令可以指定条件不成立时执行的内容。

使用<#elseif>进一步细化条件。

3.2.2 list指令

语法：

<#list sequence as loopVariable>repeatThis</#list>

使用示例一：

<ul>
<#list misc.fruits as fruit>
  <li>${fruit}
</#list>
</ul>

使用示例二：

<#list misc.fruits>
  <ul>
    <#items as fruit>
      <li>${fruit}
    </#items>
  </ul>
</#list>

示例一的缺点：如果misc.fruits的length刚好为0，一对空的ul标签仍会输出到最终的HTML文件中。

示例二避免了这个问题。如果 misc.fruits的length为0，list中的所有内容都将被跳过，因此ul标签不会出现在最终的HTML文件中。

如果只是想使用某个符号将sequence 中的各项数据分隔开显示，可以使用<#sep>指令。

示例三：

<#--Template-->
<p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, </#list>

<p>Fruits: orange, banana

可是！如果这里的 misc.fruits 的 length 又为0呢？？

一个<#list>指令就像一个<#if>指令，可以有一个<#else>指令，当 sequence 的length为0时执行。

示例四：

<p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, <#else>None</#list>

事实上，示例四有个更简单的写法：

<p>Fruits: ${fruits?join(", ", "None")}

3.2.3 include指令

使用include指令，您可以将另一个文件的内容插入到模板中。

示例：

<#include "/copyright_footer.html">

3.3 指令的混合使用

各种指令可以混合使用

3.4 使用内置函数（bulit-ins）

所谓的内置函数就像子变量（或者说，类似Java中的方法）不是来自data-model，而是由FreeMarker添加到value。

为了区分一个子变量是来自FreeMarker而不是来自data-model，我们访问这个子变量时需要使用问号（?）来替代点（.）。

以下是一些使用例子：

user?upper_case：返回全部大写的user值
animal.name?cap_first：返回首字母大写的animal.name值
user?length：返回user值（一个字符串）中字符个数
animals?size：返回animals序列的长度
如果你在<#list animals as animal>和相应的<#list>之间：
- animal?index：返回当前animal的index值（从0开始）
- animal?counter：类似于index值，但是下标从1开始
- animal?item_parity：给出字符串“odd”或“even”，这取决于当前的计数器奇偶校验。这通常用于用交替颜色着色行，如：<td class="${animal?item_parity}Row">
  
  一些内置函数需要更多的参数来指定行为，如：
animal.protected?string("Y", "N") return the string "Y" or "N" depending on the boolean value of animal.protected.
animal?item_cycle('lightRow', 'darkRow') is the more generic variant of item_parity from earlier.
fruits?join(", "): converts the list to a string by concatenating items, and inserting the parameter separator between each items (like "orange, banana")
user?starts_with("J") gives boolean true of false depending on if user starts with the letter "J" or not.

如果需要反复调用更多内置函数，可以使用链接语法。如：<p>${fruits?join(", ")?cap_first}</p>（fruits=["apple","banana"]）的HTML输出为<p>Apple, banana</p>。

3.5 处理缺失的变量

FreeMarker不允许引用缺少的变量，除非你明确指出如果变量丢失了该怎么办。

注意：在FreeMarker中，缺失的变量和值为null的变量是一样的。

两种典型的处理：

示例一：

<h1>Welcome ${user!"visitor"}!</h1>

紧跟在感叹号（!）后面的值为默认值，当且仅当user变量值为null或丢失时，将user变量值显示为"visitor"。

示例二：

<#if user??><h1>Welcome ${user}!</h1></#if>

配合if指令使用，当user变量值为null或丢失时跳过这部分内容。

注意：使用(animals.python.price)!0来替代animals.python.price!0，以防 animals 或 animals.python 的值为null或丢失。前者可以在 animals 或 animals.python 或 animals.python.price 为null或丢失时显示0，而后者只能在animals.python.price为null或丢失时显示0（animals 或 animals.python 为null或丢失时报错“undefined variable”）。同理地，使用(animals.python.price)??替代animals.python.price??。

3.6 转义为HTML，XML和其他标记（特殊符号）

如果做了合适的配置（配置由programmers修改），FreeMarker可以将${...}中的值自动转义。

推荐的做法：使用ftlh文件来激活HTML的自动转义，使用ftlx来激活XML的自动转义。

如果ftl文档目前没有自动转义且不能修改配置，则可以在ftl文档首行加入下面这行代码来实现自动转义：

<#--生成HTML文件-->
<#ftl output_format="HTML">

<#--生成XML文件-->
<#ftl output_format="HTML">

如果要打印的字符串值是故意包含特殊符号，需要这样禁止自动转义：${value?no_esc}

巴特西

【翻译】FreeMarker——入门