java-阅读篇（2）：Freemarker

简介

FreeMarker 是一款 模板引擎： 即一种基于模板和要改变的数据， 并用来生成输出文本(HTML网页，电子邮件，配置文件，源代码等)的通用工具。 它不是面向最终用户的，而是一个Java类库，是一款程序员可以嵌入他们所开发产品的组件。

知识点

• 数据模型可以被看成是树形结构。
• 标量用于存储单一的值。这种类型的值可以是字符串，数字，日期/时间或者是布尔值。
• 哈希表是一种存储变量及其相关且有唯一标识名称的容器。
• 序列是存储有序变量的容器。存储的变量可以通过数字索引来检索，索引通常从0开始。
• ${…}： FreeMarker插值。
• FTL 标签 (FreeMarker模板的语言标签)： FTL标签不会在输出中打印，标签名字以 #
  开头。(用户自定义的FTL标签则需要使用 @ 来代替 #)。
• 注释：使用 <#-- and --> 来标识。FTL注释不会出现在输出中。
• if-else指令：有条件输出片段。
• list指令：列表显示内容。
• items指令：在第一列表项之前或在最后一个列表项之后打印一些东西，如果没有迭代项，不用以空的 ul 来结束。
• seq指令：显示介于每个迭代项(但不能在第一项之前或最后一项之后) 之间的一些内容时。
• include指令：在模板中插入其他文件的内容。
• FreeMarker不解析FTL标签以外的文本、插值和注释， 在HTML属性中使用FTL标签也不会有问题.
• 不论在哪里引用变量，都可以指定一个默认值来避免变量丢失这种情况， 通过在变量名后面跟着一个 !(叹号)和默认值。
• 在变量名后面通过放置 ?? 来询问一个变量是否存在。
• 除了字符串和数字， 序列或哈希表也是一种值的表示形式。
• 标量：字符串，数字，布尔值，日期/时间 (日期，时间或日期时间)。
• 容器：，哈希表，序列，集合。
• 子程序：方法和函数，用户自定义指令。
• 集合：集合是有限制的序列。不能获取集合的大小， 也不能通过索引取出集合中的子变量，但是它们仍然可以通过 list 指令来遍历。
• 方法/函数是一等类型值， 就像函数化的编程语言。也就是说函数/方法也可以是其他函数/方法的参数或者返回值， 并可以把它们定义成变量等。
• 方法是来自于数据模型 (它们反射了Java对象的方法) ，函数是定义在模板内的 (使用 function 指令 – 也是高级话题)，但二者可以用同一种方式来使用。
• 模板(FTL编程)是由文本，插值，FTL标签和注释混合而成的。
• FTL是区分大小写，FTL 标签 不可以在其他 FTL 标签 和 插值中使用。
• 注释 可以放在 FTL 标签 和 插值中。
• FreeMarker的"空格剥离"， 它会自动去除一些多余的空格，制表符和换行符。
• 指令有两种类型： 预定义指令 和 用户自定义指令。
• 用户自定义的指令使用 @ 来代替 #。
• 如果指令没有嵌套内容，那么必须这么使用 <@mydirective parameters />。
• 字符串切分： 包含结尾： name[0…4]，不包含结尾： name[0…<5]，基于长度(宽容处理)： name[0…*5]，去除开头： name[5…]。
• 值域也是序列，但它们由指定包含的数字范围所创建， 而不需指定序列中每一项。
• 插值是用来给 表达式 插入具体值然后转换为文本(字符串)。插值仅仅可以在两种位置使用：在 文本 区 和 字符串表达式 (比如 <#include"/footer/${company}.html">)中。
• 如果插值在 文本 区，escape可以 将被插入的字符串会自动转义。如果要生成HTML，可以利用它来阻止跨站脚本攻击和非格式良好的HTML页面。noescape 用来来抵消 escape 的转义。
• 布尔值使用插值方式来打印布尔值会引起错误，可以使用内建函数 ?string 来将布尔值转换为字符串形式。
• ?c 也可以用来输出给计算机看的数字。
• 数字，按照指定的 number_format 设置规则来转换为字符串。
• 日期，时间或时间日期类型的一种，按照指定的 date_format， time_format 或者 datetime_format 设置规则来转换为字符串。
• 自定义指令可以使用 macro 指令来定义。在Java语言中实现指令的定义， 可以使用 freemarker.template.TemplateDirectiveModel 类来扩展 。
• macro 指令自身不输出任何内容， 它只是用来创建宏变量。在 <#macro greet> 和 </#macro> 之间的内容 (称为 宏定义体) 将会在使用该变量作为指令时执行。在FTL标记中通过 @代替#来使用自定义指令。它可以包含插值 (${…}) 和FTL标签 (如 <#if …>…</#if>)。
• 在 macro 指令中，宏名称的后面位置是用来定义参数的。
• 使用 预定义指令时，参数的值 (=号后边的值)可以是 FTL 表达式。
• 调用宏的时候，只能使用在 macro 指令中定义的参数。同时也必须给出在宏中定义所有参数的值。没有特定值，则可以在macro指令中指定变量： param_name=usual_value。
• 自定义指令可以嵌套内容，和预定义指令相似：<#if …>nested content</#if>。<#nested> 指令位于宏定义开始和结束标记指令之间。如果不使用 nested 指令， 那么嵌套的内容就不会被执行。
• 在嵌套的内容中，宏的 局部变量 不可见。
• 循环变量的名称在自定义指令的开始标记(<@…>) 的参数后面通过分号确定。
• 模板里定义的变量，比定义在数据模型中的同名参数有更高的优先级.
• assign 指令来创建或替换简单变量，它能从模板中的任何位置或者从使用 include 指令引入的模板来访问。
• local指令在宏定义体内创建或替换局部变量。
• 循环变量是由如 list 指令自动创建的，而且它们只在指令的开始和结束标记内有效。
• 全局变量通过 global指令来定义。
• 局部变量会隐藏(不是覆盖)同名的’‘简单’‘变量。 循环变量也会隐藏(不是覆盖)同名的’‘简单’'变量。
• 内部循环变量可以隐藏外部循环变量。
• 当一个变量隐藏数据模型中的同名变量， 如果想访问数据模型中的变量，可以使用 特殊变量 globals。如：${.globals.user}。通过 global指令设置的变量可以隐藏数据模型中的同名变量时，可以使用如下方式来访问数据模型变量：.data_model.user。
• 模板的命名空间（ assign 或 macro 指令来创建） 中的变量有着比数据模型中的变量更高的优先级。
• 命名空间是不分层次的，它们相互之间是独立存在的。 如果在命名空间N1中 import 命名空间N2， 那N2也不在N1中，N1只是可以通过哈希表来访问N2。
• 剥离空白：这个特性会自动忽略在FTL标签周围多余的空白。 这个特性可以通过模板来随时启用和禁用。
• 微调指令：t，rt， lt。使用这些指令可以明确地告诉 FreeMarker 去忽略某些空白。
• ftl 参数 strip_text：这将从模板中删除所有顶级文本。比如移除宏定义和其他顶级指令中的换行符。
• 从输出中移除空白的工具 (移除临近的空白)：compress 指令。
• 缩进空白和在行末尾的尾部空白(包括换行符)在只包含FTL标签的行中会被忽略。两个FTL标签之间的空白是嵌入的空白，不是缩进的或尾部空白。
• 加在下面这些指令之间的空白会被忽略：macro， function，assign， global，local， ftl， import， 但也是指令之间仅仅只有一个空白或FTL注释。
• 剥离空白时 不会 降低模板执行的效率，剥离空白的操作在模板加载时就已经完成了。
• compress 指令，和剥离空白相反，直接基于生成的输出内容， 而不是对于模板进行。强制移除缩进， 空行和重复的空格/制表符。设置 single_line 参数， 这将会移除所有的介于其中的换行符。
• FreeMarker支持在指令和注释中用 [ 和 ] 来代替 < 和 >。整个模板要么全部使用替换语法，要么全部使用默认语法。如果模板使用了替换语法，那么如 <#if …> 这样的部分就会被算作是静态文本。第一个FreeMarker标签决定了语法形式。