FreeMarker 手册
用于 FreeMarker 2.3.18
目录
FreeMarker 手册 .......................................................................................................... 1
用于 FreeMarker 2.3.18 ........................................................................................... 1
目录................................................................................................................................. 2
前言................................................................................................................................. 7
什么是 FreeMarker？ ................................................................................................. 7
我们应该阅读什么内容？ .......................................................................................... 7
文档规约................................................................................................................... 8
联系我们................................................................................................................... 8
几点说明................................................................................................................... 8
第一部分 模板开发指南 ................................................................................................... 9
第一章 模板开发入门 ............................................................................................... 9
1.1 简介 ............................................................................................................ 9
1.2 模板 + 数据模型 = 输出 ............................................................................. 9
1.3 数据模型一览 ............................................................................................ 10
1.4 模板一览 ................................................................................................... 13
第二章 数值和类型 ................................................................................................. 19
2.1 基本内容 ................................................................................................... 19
2.2 类型 .......................................................................................................... 21
第三章 模板 ........................................................................................................... 25
3.1 总体结构 ................................................................................................... 25
3.2 指令 .......................................................................................................... 26
3.3 表达式 ....................................................................................................... 27
3.4 插值 .......................................................................................................... 42
第四章 其它 ........................................................................................................... 45
4.1 自定义指令 ................................................................................................ 45
4.2 在模板中定义变量 ..................................................................................... 50
4.3 命名空间 ................................................................................................... 53
4.4 空白处理 ................................................................................................... 56
4.5 替换（方括号）语法 ................................................................................... 59
第二部分 程序开发指南 ................................................................................................. 61
第一章 程序开发入门 ............................................................................................. 61
1.1 创建配置实例 ............................................................................................ 61
1.2 创建数据模型 ............................................................................................ 61
1.3 获得模板 ................................................................................................... 62
1.4 合并模板和数据模型 .................................................................................. 63
1.5 将代码放在一起 .......................................................................................... 63
第二章 数据模型 .................................................................................................... 65
2.1 基本内容 ................................................................................................... 65
2.2 标量 .......................................................................................................... 65
2.3 容器 .......................................................................................................... 66
2.4 方法 .......................................................................................................... 67
2.5 指令 .......................................................................................................... 68
2.6 节点变量 ................................................................................................... 74
2.7 对象包装 ................................................................................................... 75
第三章 配置 ........................................................................................................... 79
3.1 基本内容 ................................................................................................... 79
3.2 共享变量 ................................................................................................... 79
3.3 配置信息 ................................................................................................... 80
3.4 模板加载 ................................................................................................... 82
3.5 错误控制 ................................................................................................... 85
第四章 其它 ........................................................................................................... 89
4.1 变量 .......................................................................................................... 89
4.2 字符集问题 ................................................................................................ 89
4.3 多线程 ....................................................................................................... 91
4.4 Bean 的包装 ................................................................................................ 91
4.5 日志 .......................................................................................................... 97
4.6 在 Servlet 中使用 FreeMarker ...................................................................... 98
4.7 为 FreeMarker 配置安全策略......................................................................105
4.8 遗留的 XML 包装实现 ................................................................................106
4.9 和 Ant 一起使用 FreeMarker.......................................................................109
4.10 Jython 包装器 ..........................................................................................110
第三部分 XML 处理指南................................................................................................112
前言.......................................................................................................................112
第一章 揭示 XML 文档 ...........................................................................................113
1.1 节点树 ......................................................................................................113
1.2 将 XML 放到数据模型中 ............................................................................115
第二章 必要的 XML 处理 ........................................................................................117
2.1 通过例子来学习 ........................................................................................117
2.2 形式化描述 ...............................................................................................124
第三章 声明的 XML 处理 ........................................................................................129
3.1 基础内容 ..................................................................................................129
3.2 详细内容 ..................................................................................................131
第四部分 参考文档 .......................................................................................................134
第一章 内建函数参考文档 .....................................................................................134
1.1 处理字符串的内建函数 .............................................................................134
1.2 处理数字的内建函数 .................................................................................147
1.3 处理日期的内建函数 .................................................................................151
1.4 处理布尔值的内建函数 .............................................................................155
1.5 处理序列的内建函数 .................................................................................156
1.6 处理哈希表的内建函数 .............................................................................161
1.7 处理节点（XML）的内建函数....................................................................162
1.8 很少使用的和专家级的内建函数 ...............................................................163
第二章 指令参考文档 ............................................................................................167
2.1 if，else，elseif 指令 ...................................................................................167
2.2 switch，case，default，break 指令..............................................................169
2.3 list，break 指令 .........................................................................................170
2.4 include 指令 ...............................................................................................171
2.5 import 指令 ...............................................................................................174
2.6 noparse 指令 ..............................................................................................175
2.7 compress 指令 ............................................................................................176
2.8 escape，noescape 指令...............................................................................177
2.9 assign 指令 ................................................................................................179
2.10 global 指令 ..............................................................................................181
2.11 local 指令 ................................................................................................182
2.12 setting 指令 .............................................................................................182
2.13 用户自定义指令（<@...>） ......................................................................184
2.14 macro，nested，return 指令 ....................................................................186
2.15 function，return 指令...............................................................................190
2.16 flush 指令 ................................................................................................192
2.17 stop 指令.................................................................................................192
2.18 ftl 指令 ....................................................................................................193
2.19 t，lt，rt 指令 ..........................................................................................194
2.20 nt 指令 ....................................................................................................195
2.21 attempt，recover 指令 .............................................................................196
2.22 visit，recurse，fallback 指令 .....................................................................197
第三章 特殊变量参考文档 .....................................................................................202
第四章 FTL 中的保留名称.......................................................................................204
第五章 废弃的 FTL 结构 .........................................................................................205
5.1 废弃的指令列表 ........................................................................................205
5.2 废弃的内建函数列表 .................................................................................205
5.3 老式的 macro和 call 指令 ..........................................................................205
5.4 转换指令 ..................................................................................................207
5.5 老式 FTL 语法 ............................................................................................208
5.6 #{…}式的数字插值 ......................................................................................209
第五部分 附录 ..............................................................................................................211
附录 A FAQ .............................................................................................................211
1. JSP 和 FreeMarker 的对比 .............................................................................211
2. Velocity 和 FreeMarker 的对比.......................................................................212
3. 为什么 FreeMarker 对 null-s 和不存在的变量很敏感，如何来处理它？ ......212
4. 文档编写了特性 X，但是好像 FreeMarker 并不知道它，或者它的行为和文档描
述的不同，或者一个据称已经修改的 BUG 依然存在。 .....................................213
5. 为什么 FreeMarker 打印奇怪的数字数字格式（比如 1,000,000 或 1 000 000 而不
是 1000000）？ ...............................................................................................213
6. 为什么 FreeMarker 会打印不好的小数和/或分组分隔符号 （比如 3.14 而不是 3,14）
.......................................................................................................................214
7. 为什么当我想用如格式打印布尔值时，FreeMarker 会抛出错误，又如何来修正
呢？................................................................................................................214
8. FreeMarker 标签中的<和>混淆了编辑器或 XML 处理器，应该怎么做？ .........214
9. 什么是合法的变量名？ ...............................................................................214
10. 如何使用包含空格，或其他特殊字符的变量（宏）名？ ............................215
11. 当我试图使用 JSP 客户标签时为什么会得到非法参数异常：形式参数类型不匹
配？................................................................................................................215
12. 如何像 jsp:include 一样的方式引入其它的资源？................................216
13. 如 何 给 普 通 Java 方 法 / TemplateMethodModelEx/
TemplateTransformModel/ TemplateDirectiveModel 的实现传递普通
java.lang.* / java.util.*对象的参数？ ...............................................216
14. 为什么在 myMap[myKey]表达式中不能使用非字符串的键？那现在应该怎么
做？................................................................................................................217
15. 当使用?keys/?values 遍历 Map（哈希表）的内容时，得到了混合真正 map
条目的 java.util.Map 的方法。当然，只是想获取 map 的条目。 ...............218
16. 在 FreeMarker 的模板中如何改变序列（lists）和哈希表（maps）？ ...........218
17. 关于 null 在 FreeMarker 模板语言是什么样的？ ......................................219
18. 我该怎么在表达式（作为另外一个指令参数）中使用指令（宏）的输出？ 220
19. 在输出中为什么用“？”来代替字符 X？ ..................................................220
20. 在模板执行完成后，怎么在模板中获取计算过的值？ ................................221
21. 我能允许用户上传模板吗？又如何保证安全呢？ .......................................221
22. 如何在 Java 语言中实现方法或宏而不是在模板语言中？............................222
23. 为什么 FreeMarker 的日志压制了我的应用程序？ ......................................222
24. 在基于 Servlet 的应用程序中，如何在模板执行期间发生错误时，展示一个友
好的错误提示页面，而不是堆栈轨迹？ ...........................................................223
25. 我正使用一个可视化的 HTML 割裂模板标记的编辑器。你们可以改变模板语言
的语法来兼容我的编辑器么？ .........................................................................223
26. FreeMarker 有多快？真的是 2.X 版本的要比 1.X 版本 （经典的 FreeMarker） 的慢
吗？................................................................................................................223
27. 我的 Java 类怎么才能获取到关于模板结构的信息（比如所有变量的列表）？
.......................................................................................................................224
28. 你会一直提供向后的兼容性吗？ ...............................................................224
29. 如果我们把 FreeMarker 和我们的产品一起发行， 我们需要发布我们产品的源代
码么？ ............................................................................................................225
附录 B 安装 FreeMarker..........................................................................................226
附录 C 构建 FreeMarker..........................................................................................227
附录 D 版本 ...........................................................................................................228
2.3.18 版 .........................................................................................................228
2.3.17 版 .........................................................................................................228
2.3.16 版.........................................................................................................231
2.3.15 版.........................................................................................................231
2.3.14 版.........................................................................................................232
2.3.13 版.........................................................................................................233
2.3.12 版.........................................................................................................233
2.3.11 版.........................................................................................................234
2.3.10 版.........................................................................................................235
2.3.9 版 ..........................................................................................................236
2.3.8 版 ..........................................................................................................237
2.3.7 版 ..........................................................................................................237
2.3.7 RC1 版 .....................................................................................................238
2.3.6 版 ..........................................................................................................239
2.3.5 版 ..........................................................................................................239
2.3.4 版 ..........................................................................................................240
2.3.3 版 ..........................................................................................................241
2.3.2 版 ..........................................................................................................242
2.3.1 版 ..........................................................................................................243
2.3 版 .............................................................................................................245
2.2.8 版 ..........................................................................................................258
2.2.7 版 ..........................................................................................................258
2.2.6 版 ..........................................................................................................258
2.2.5 版 ..........................................................................................................259
2.2.4 版 ..........................................................................................................260
2.2.3 版 ..........................................................................................................260
2.2.2 版 ..........................................................................................................261
2.2.1 版 ..........................................................................................................261
2.2 版 .............................................................................................................262
2.1.5 版 ..........................................................................................................270
2.1.4 版 ..........................................................................................................270
2.1.3 版 ..........................................................................................................270
2.1.2 版 ..........................................................................................................271
2.1.1 版 ..........................................................................................................271
2.1 版 .............................................................................................................272
2.01 版 ...........................................................................................................276
2.0 版 .............................................................................................................276
2.0 RC3 版........................................................................................................277
2.0 RC2 版........................................................................................................278
2.0 RC1 版........................................................................................................279
附录 E 许可 ...........................................................................................................282
词汇表 ..........................................................................................................................283
