什么是FreeMarker？
FreeMarker 是一款模板引擎：一种基于模板的、用来生成输出文本(任何来自于 HTML
格式的文本用来自动生成源代码)的通用工具。它是为 Java 程序员提供的一个开发包或者说
是类库。 它不是面向最终用户，而是为程序员提供的可以嵌入他们开发产品的一款应用程序。
FreeMarker 的设计实际上是被用来生成 HTML 网页，尤其是通过基于实现了 MVC(Model
View Controller，模型-视图-控制器)模式的 Servlet 应用程序。使用 MVC 模式的动态网页的构
思使得你可以将前端设计者(编写 HTML)从程序员中分离出来。所有人各司其职，发挥其擅
长的一面。网页设计师可以改写页面的显示效果而不受程序员编译代码的影响，因为应用程
序的逻辑(Java 程序)和页面设计(FreeMarker 模板)已经分开了。页面模板代码不会受到复杂
的程序代码影响。 这种分离的思想即便对一个程序员和页面设计师是同一个人的项目来说都
是非常有用的，因为分离使得代码保持简洁而且便于维护。
尽管 FreeMarker 也有编程能力，但它也不是像 PHP 那样的一种全面的编程语言。 反而，
Java 程序准备的数据来显示(比如 SQL 查询)，FreeMarker 仅仅使用模板生成文本页面来呈现
已经准备好的数据。
FreeMarker 不是 Web 应用框架。它是 Web 应用框架中的一个适用的组件，但是
FreeMarker 引擎本身并不知道 HTTP 协议或 Servlet。它仅仅来生成文本。即便这样，它也非
常适用于非 Web 应用环境的开发。要注意的是，我们使用 FreeMarker 作为视图层组件，是
为给如 Struts 这样的 Model 2 框架提供现成的解决方案。
FreeMarker 是免费的，基于 BSD 规则的许可。它是 OSI 认证的开源软件。OSI 认证是开
源倡议的认证标识。
我们应该阅读什么内容？
如果你是一名…
前端设计师，那么你应该阅读模板开发指南，然后如果需要的话可以阅读参考手册来获
取更多技术细节。
程序员，那么你应该先阅读模板开发指南，然后是程序开发指南，最后如果需要的话可
以阅读参考手册来获取更多技术细节。 文档规约
变量名，模板代码段，Java 类名等用如下格式书写，如：foo。
如果需要具体值来代替某些内容，那么用斜体书写，如：Hello yourName!
目录
FreeMarker 手册 ……. 1
用于 FreeMarker 2.3.16 …….. 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
第四章 其它 …….. 44
4.1 自定义指令 …………. 44
4.2 在模板中定义变量 .. 50
4.3 命名空间 52
4.4 空白处理 55
4.5 替换（方括号）语法 58
第二部分 程序开发指南 ………….. 60
第一章 程序开发入门 ………. 60
1.1 创建配置实例 ……… 60
1.2 创建数据模型 ……… 60
1.3 获得模板 61
1.4 合并模板和数据模型 ………………. 62
1.5 将代码放在一起 ……. 62
第二章 数据模型 . 63
2.1 基本内容 63
2.2 标量 ……. 64
2.3 容器 ……. 65
2.4 方法 ……. 65 2.5
指令 ……. 66
2.6 节点变量 72
2.7 对象包装 73
第三章 配置 …….. 77
3.1 基本内容 77
3.2 共享变量 77
3.3 配置信息 78
3.4 模板加载 80
3.5 错误控制 83
第四章 其它 …….. 86
4.1 变量 ……. 86
4.2 字符集问题 …………. 87
4.3 多线程 …. 88
4.4 Bean 的包装 …………. 89
4.5 日志 ……. 95
4.6 在 Servlet 中使用 FreeMarker ……. 95
4.7 为 FreeMarker 配置安全策略…….102
4.8 遗留的 XML 包装实现 ……………..103
4.9 和 Ant 一起使用 FreeMarker……..107
4.10 Jython 包装器 …….108
第三部分 XML 处理指南………….110
前言………………..110
第一章 揭示 XML 文档 ……..110
1.1 节点树 …110
1.2 将 XML 放到数据模型中 ………….112
第二章 必要的 XML 处理 …..113
2.1 通过例子来学习 …..113
2.2 形式化描述 …………121
第三章 声明的 XML 处理 …..124
3.1 基础内容 ……………124
3.2 详细内容 ……………127
第四部分 参考文档 ….130
第一章 内建函数参考文档 ..130
1.1 处理字符串的内建函数 …………..130
1.2 处理数字的内建函数 ………………143
1.3 处理日期的内建函数 ………………147
1.4 处理布尔值的内建函数 …………..149
1.5 处理序列的内建函数 ………………150
1.6 处理哈希表的内建函数 …………..155
1.7 处理节点（XML）的内建函数…..156
1.8 很少使用的和专家级的内建函数 157
第二章 指令参考文档 ………160
2.1 if，else，elseif 指令 160
2.2 switch，case，default，break
指令……….162 2.3 list，break 指令 ……163
2.4 include 指令 …………165
2.5 import 指令 …………168
2.6 noparse 指令 ………..169
2.7 compress 指令 ………169
2.8 escape，noescape 指令…………….170
2.9 assign 指令 ………….173
2.10 global 指令 ………..174
2.11 local 指令 ………….175
2.12 setting 指令 ……….176
2.13 用户自定义指令（<@…>） …….177
2.14 macro，nested，return 指令 …..180
2.15 function，return 指令…………….184
2.16 flush 指令 ………….185
2.17 stop 指令…………..186
2.18 ftl 指令 .186
2.19 t，lt，rt 指令 …….188
2.20 nt 指令 .189
2.21 attempt，recover 指令 …………..189
2.22 visit，recurse，fallback 指令 ……191
第三章 特殊变量参考文档 ..195
第四章 FTL 中的保留名称….196
第五章 废弃的 FTL 结构 ……196
5.1 废弃的指令列表 …..196
5.2 废弃的内建函数列表 ………………196
>5.3 老式的 macro和 call 指令 ………..197
5.4 转换指令 ……………198
5.5 老式 FTL 语法 ………200
5.6 #{…}式的数字插值 …201
第五部分 附录 ………..202
附录 A FAQ ……….202
1. JSP 和 FreeMarker 的对比 …………..202
2. Velocity 和 FreeMarker 的对比……..203
3. 为什么 FreeMarker 对 null-s 和不存在的变量很敏感，如何来处理它？ ……203
4. 文档编写了特性 X，但是好像 FreeMarker 并不知道它，或者它的行为和文档描
述的不同，或者一个据称已经修改的 BUG 依然存在。 ……………………………….204
5. 为什么 FreeMarker 打印奇怪的数字数字格式（比如 1,000,000或 1 000 000 而不
是 1000000）？ …………204
6. 为什么FreeMarker会打印不好的小数和/或分组分隔符号（比如3.14而不是3,14）
………………..205
7. 为什么当我想用如格式打印布尔值时，FreeMarker 会抛出错误，又如何来修正
呢？………….205
8. FreeMarker 标签中的<和>混淆了编辑器或 XML 处理器，应该怎么做？ ………205
9. 什么是合法的变量名？ …………….205 10. 如何使用包含空格，或其他特殊字符的变量（宏）名？ ……………………….206
11. 当我试图使用 JSP 客户标签时为什么会得到非法参数异常：形式参数类型不匹
配？………….206
12. 如何像 jsp:include 一样的方式引入其它的资源？…………………………..207
13. 如 何 给 普 通 Java 方法 / TemplateMethodModelEx/
TemplateTransformModel/ TemplateDirectiveModel 的实现传递普通
java.lang.* / java.util.*对象的参数？ ………………………………………..207
14. 为什么在 myMap[myKey]表达式中不能使用非字符串的键？那现在应该怎么
做？………….208
15. 当使用?keys/?values 遍历 Map（哈希表）的内容时，得到了混合真正 map
条目的 java.util.Map 的方法。当然，只是想获取 map 的条目。 ……………209
16. 在 FreeMarker 的模板中如何改变序列（lists）和哈希表（maps）？ ………..209
17. 关于 null 在 FreeMarker 模板语言是什么样的？ ………………………………..210
18. 我该怎么在表达式（作为另外一个指令参数）中使用指令（宏）的输出？ 211
19. 在输出中为什么用“？”来代替字符 X？ …………………………………………..211
20. 在模板执行完成后，怎么在模板中获取计算过的值？ …………………………..212
21. 如何在 Java 语言中实现方法或宏而不是在模板语言中？……………………….212
22. 为什么 FreeMarker 的日志压制了我的应用程序？ ………………………………..212
23. 在基于 Servlet 的应用程序中，如何在模板执行期间发生错误时，展示一个友
好的错误提示页面，而不是堆栈轨迹？ …………………………………………………..213
24. 我正使用一个可视化的 HTML 割裂模板标记的编辑器。你们可以改变模板语言
的语法来兼容我的编辑器么？ ……….213
25. FreeMarker 有多快？真的是 2.X 版本的要比 1.X 版本（经典的 FreeMarker）的慢
吗？………….214
26. 我的 Java 类怎么才能获取到关于模板结构的信息（比如所有变量的列表）？
………………..214
27. 你会一直提供向后的兼容性吗？ 214
28. 如果我们把 FreeMarker 和我们的产品一起发行，我们需要发布我们产品的源代
码么？ ………215
附录 B 安装 FreeMarker…….216
附录 C 构建 FreeMarker…….217
FreeMarker 中文版手册由南磊翻译，本文档基于 Creative Commons Attribution 3.0
Unported 授权许可（参见 http://creativecommons.org/licenses/by/3.0/deed.zh ）
本许可仅应用于中文版，不对原版英文手册。
资料星级：     |
资料格式：HTML/CHM |
| 上 传 者：jsp程序员 | 下载次数：3132 |
| 上传时间：2011-02-17 22:23:41
|
|
