FreeMarker手册全篇

FreeMarker 手册
用于 FreeMarker 2.3.19

Translated By Nan Lei
南磊 译
Copyright：
The Chinese translation of the FreeMarker Manual by Nan Lei is licensed under a Creative
Commons Attribution 3.0 Unported License (see http://creativecommons.org/licenses/by/3.0/ ).
This licence only applies to the Chinese translation, not to the original (English) FreeMarker
Manual.
版权说明：
FreeMarker 中文版手册由南磊翻译，本文档基于 Creative Commons Attribution 3.0
Unported 授权许可（参见 http://creativecommons.org/licenses/by/3.0/deed.zh）
本许可仅应用于中文版，不对原版英文手册。
（译者联系方式为：nanlei1987@gmail.com 或 http://weibo.com/nanlei1987）
目录
前言… 7
什么是 FreeMarker？… 7
我们应该阅读什么内容？… 8
文档规约… 8
联系我们… 8
几点说明… 9
第一部分 模板开发指南… 10
第一章 模板开发入门 … 10
1.1 简介 … 10
1.2 模板 + 数据模型 = 输出… 10
1.3 数据模型一览 … 11
1.4 模板一览 … 14
第二章 数值和类型… 20
2.1 基本内容 … 20
2.2 类型 … 22
第三章 模板 … 26
3.1 总体结构 … 26
3.2 指令 … 27
3.3 表达式… 28
3.4 插值 … 43
第四章 其它 … 46
4.1 自定义指令… 46
4.2 在模板中定义变量 … 51
4.3 命名空间 … 54
4.4 空白处理 … 57
4.5 替换（方括号）语法… 60
第二部分 程序开发指南… 62
第一章 程序开发入门 … 62
1.1 创建配置实例 … 62
1.2 创建数据模型 … 62
1.3 获得模板 … 63
1.4 合并模板和数据模型… 64
1.5 将代码放在一起… 64
第二章 数据模型 … 66
2.1 基本内容 … 66
2.2 标量 … 66
2.3 容器 … 67
2.4 方法 … 68
2.5 指令 … 69
2.6 节点变量 … 75
2.7 对象包装 … 76
第三章 配置 … 80
3.1 基本内容 … 80
3.2 共享变量 … 80
3.3 配置信息 … 81
3.4 模板加载 … 83
3.5 错误控制 … 86
第四章 其它 … 90
4.1 变量 … 90
4.2 字符集问题… 90
4.3 多线程… 92
4.4 Bean 的包装… 92
4.5 日志 … 98
4.6 在 Servlet 中使用 FreeMarker… 99
4.7 为 FreeMarker 配置安全策略…106
4.8 遗留的 XML 包装实现…107
4.9 和 Ant 一起使用 FreeMarker…111
4.10 Jython 包装器…112
第三部分 XML 处理指南…114
前言…114
第一章 揭示 XML 文档…115
1.1 节点树…115
1.2 将 XML 放到数据模型中…117
第二章 必要的 XML 处理…119
2.1 通过例子来学习…119
2.2 形式化描述…126
第三章 声明的 XML 处理…131
3.1 基础内容 …131
3.2 详细内容 …133
第四部分 参考文档…136
第一章 内建函数参考文档 …136
1.1 处理字符串的内建函数 …136
1.2 处理数字的内建函数…150
1.3 处理日期的内建函数…153
1.4 处理布尔值的内建函数 …158
1.5 处理序列的内建函数…158
1.6 处理哈希表的内建函数 …164
1.7 处理节点（XML）的内建函数…164
1.8 很少使用的和专家级的内建函数 …166
第二章 指令参考文档 …170
2.1 if，else，elseif 指令 …170
2.2 switch，case，default，break 指令…172
2.3 list，break 指令…173
2.4 include 指令 …174
2.5 import 指令…177
2.6 noparse 指令…178
2.7 compress 指令…179
2.8 escape，noescape 指令…180
2.9 assign 指令…182
2.10 global 指令 …184
2.11 local 指令 …185
2.12 setting 指令…185
2.13 用户自定义指令（<@…>）…187
2.14 macro，nested，return 指令 …189
2.15 function，return 指令…193
2.16 flush 指令…195
2.17 stop 指令…195
2.18 ftl 指令…196
2.19 t，lt，rt 指令…197
2.20 nt 指令…198
2.21 attempt，recover 指令…199
2.22 visit，recurse，fallback 指令…200
第三章 特殊变量参考文档 …205
第四章 FTL 中的保留名称…207
第五章 废弃的 FTL 结构…208
5.1 废弃的指令列表…208
5.2 废弃的内建函数列表…208
5.3 老式的 macro 和 call 指令…208
5.4 转换指令 …210
5.5 老式 FTL 语法…211
5.6 #{…}式的数字插值…212
第五部分 附录…214
附录 A FAQ …214

1. JSP 和 FreeMarker 的对比…214
2. Velocity 和 FreeMarker 的对比…215
3. 为什么 FreeMarker 对 null-s 和不存在的变量很敏感，如何来处理它？ …215
4. 文档编写了特性 X，但是好像 FreeMarker 并不知道它，或者它的行为和文档描
   述的不同，或者一个据称已经修改的 BUG 依然存在。…216
5. 为什么 FreeMarker 打印奇怪的数字数字格式（比如 1,000,000 或 1 000 000 而不
   是 1000000）？…216
6. 为什么 FreeMarker 会打印不好的小数和/或分组分隔符号（比如 3.14 而不是 3,14）
   …217
7. 为什么当我想用如格式打印布尔值时，FreeMarker 会抛出错误，又如何来修正
   呢？…217
8. FreeMarker 标签中的<和>混淆了编辑器或 XML 处理器，应该怎么做？…217
9. 什么是合法的变量名？…217
10. 如何使用包含空格，或其他特殊字符的变量（宏）名？ …218
11. 当我试图使用 JSP 客户标签时为什么会得到非法参数异常：形式参数类型不匹
    配？…218
12. 如何像 jsp:include 一样的方式引入其它的资源？…219
13. 如 何 给 普 通 Java 方 法 / TemplateMethodModelEx/
    TemplateTransformModel/ TemplateDirectiveModel 的实现传递普通
    java.lang.* / java.util.*对象的参数？ …219
14. 为什么在 myMap[myKey]表达式中不能使用非字符串的键？那现在应该怎么
    做？…220
15. 当使用?keys/?values 遍历 Map（哈希表）的内容时，得到了混合真正 map
    条目的 java.util.Map 的方法。当然，只是想获取 map 的条目。…221
16. 在 FreeMarker 的模板中如何改变序列（lists）和哈希表（maps）？…221
17. 关于 null 在 FreeMarker 模板语言是什么样的？…222
18. 我该怎么在表达式（作为另外一个指令参数）中使用指令（宏）的输出？ 223
19. 在输出中为什么用“？”来代替字符 X？…223
20. 在模板执行完成后，怎么在模板中获取计算过的值？…224
21. 我能允许用户上传模板吗？又如何保证安全呢？…224
22. 如何在 Java 语言中实现方法或宏而不是在模板语言中？…225
23. 为什么 FreeMarker 的日志压制了我的应用程序？…225
24. 在基于 Servlet 的应用程序中，如何在模板执行期间发生错误时，展示一个友
    好的错误提示页面，而不是堆栈轨迹？…226
25. 我正使用一个可视化的 HTML 割裂模板标记的编辑器。你们可以改变模板语言
    的语法来兼容我的编辑器么？…226
26. FreeMarker 有多快？真的是 2.X 版本的要比 1.X 版本（经典的 FreeMarker）的慢
    吗？…226
27. 我的 Java 类怎么才能获取到关于模板结构的信息（比如所有变量的列表）？
    …227
28. 你会一直提供向后的兼容性吗？ …227
29. 如果我们把 FreeMarker 和我们的产品一起发行，我们需要发布我们产品的源代
    码么？…228
    附录 B 安装 FreeMarker…229
    附录 C 构建 FreeMarker…230
    附录 D 版本…231
    2.3.18 版…231
    2.3.17 版…233
    2.3.16 版…235
    2.3.15 版…236
    2.3.14 版…237
    2.3.13 版…238
    2.3.12 版…238
    2.3.11 版…239
    2.3.10 版…240
    2.3.9 版…241
    2.3.8 版…242
    2.3.7 版…242
    2.3.7 RC1 版…243
    2.3.6 版…244
    2.3.5 版…244
    2.3.4 版…245
    2.3.3 版…246
    2.3.2 版…247
    2.3.1 版…248
    2.3 版…250
    2.2.8 版…262
    2.2.7 版…263
    2.2.6 版…263
    2.2.5 版…264
    2.2.4 版…264
    2.2.3 版…265
    2.2.2 版…265
    2.2.1 版…266
    2.2 版…266
    2.1.5 版…275
    2.1.4 版…275
    2.1.3 版…275
    2.1.2 版…276
    2.1.1 版…276
    2.1 版…277
    2.01 版…281
    2.0 版…281
    2.0 RC3 版…282
    2.0 RC2 版…283
    2.0 RC1 版…284
    附录 E 许可…287
    词汇表…288
    前言
    什么是 FreeMarker？
    FreeMarker 是一款模板引擎：即一种基于模板、用来生成输出文本(任何来自于 HTML
    格式的文本用来自动生成源代码)的通用工具。它是为 Java 程序员提供的一个开发包，或者
    说是一个类库。它不是面向最终用户的，而是为程序员提供的一款可以嵌入他们所开发产品
    的应用程序。
    FreeMarker 实际上是被设计用来生成 HTML 页面，尤其是通过实现了基于 MVC(Model
    View Controller，模型-视图-控制器)模式的 Java Servlet 应用程序。使用 MVC 模式的动态页面
    的设计构思使得你可以将前端设计师(编写 HTML 页面的人员)从程序员中分离出来。那么，
    所有人各司其职，发挥其最擅长的一面。网页设计师可以改写页面的显示效果而不受程序员
    编译代码的影响，因为应用程序的逻辑(这里是 Java 程序)和页面设计(这里是 FreeMarker 模
    板)已经被分开了。页面模板代码不会受到复杂程序代码的影响。这种分离的思想即便对一
    个程序员和页面设计师是同一个人的项目来说也都是非常有用的，因为分离使得代码保持简
    洁而且易于维护。
    尽管 FreeMarker 也拥有一些编程能力，但是它却不像 PHP 那样，是的一种全面的编程
    语言。反而，Java 程序准备的数据来进行显示(比如 SQL 数据库查询)，FreeMarker 仅仅是使
    用模板生成文本页面来呈现已经准备好的数据而已。
    FreeMarker 不是 Web 开发的应用程序框架。它是一个适用于 Web 应用程序框架中的组
    件，但是 FreeMarker 引擎本身并不知道 HTTP 协议或 Java Servlet 的存在。它仅仅来生成文
    本内容。既然是这样，它也非常适用于非 Web 应用程序的开发环境。只是要注意的是，我
    们使用 FreeMarker 作为视图层的组件，是为了给诸如 Struts 这样的 Model 2 应用框架提供现
    成的解决方案。
    FreeMarker 本身是免费的，它基于 BSD 规则的许可协议。它也是 OSI 认证的开源软件。
    OSI 认证是开源倡议的认证标识。
    我们应该阅读什么内容？
    如果你是一名…
    前端设计师，首先，你应该阅读的是模板开发指南部分，然后如果有需要的话，可以再
    阅读参考手册来获取更多的技术细节。
    程序员，那么，你应该先阅读模板开发指南部分，然后是程序开发指南部分，最后如果
    需要的话可以阅读参考手册来获取更多技术细节。
    本文档规约
    变量名，模板代码段，Java 类名等用如下格式书写，如：foo。
    如果需要具体值来代替某些内容，那么用斜体书写，如&