FreeMarker2.3.10
―Programmer's Guide（中文版）
翻译：Magice（魔冰）
QQ: 8163090
前言......................................................................... 3
一、快速入门..............................................................4
1.1、创建配置实例..............................................................................4
1.2、创建数据模型（Data Model） ..........................................................4
1.3、获取模版（template） ..................................................................5
1.4、把模版与数据模型合并...................................................................6
1.5、完整的代码 ................................................................................6
二、数据模型（Data Model） ..........................................7
2.1、基础类型 ...................................................................................7
2.2、Scalar 类型（单值对应的 Data Model） ...............................................8
2.3、容器类型 ...................................................................................8
2.4、方法变量 ...................................................................................9
2.5、转换器变量 .............................................................................. 10
2.6、节点变量 ................................................................................. 12
2.7、对象包裹 ................................................................................. 12
三、配置（Configuration）........................................... 15
3.1、基础....................................................................................... 15
3.2、共享变量 ................................................................................. 15
3.3、配置参数 ................................................................................. 16
3.4、加载模板 ................................................................................. 17
3.5、异常处理 ................................................................................. 19
四、其它说明............................................................ 20
4.1、变量....................................................................................... 20
4.2、字符编码 ................................................................................. 20
4.3、多线程.................................................................................... 21
4.5、Bean 包裹................................................................................ 21
前言
FreeMarker 官方参考文档总共有四份，它们分别是
Designer's Guide（网上已有翻译，主要从 FreeMarker 的概念上介绍）
Programmer's Guide（本文档所以翻译的部分，主要从框架的设计方面介绍）
XML Processing Guide（对 XML 数据模型处理的介绍）
Reference（FreeMarker 的参考文档，语言使用介绍）
中 文翻 译 之所以 选择 Programmer's Guide 是因为个 人 觉 得 该部 分对 如 何实现
FreeMarker 进行了比较深入的阐述。有助于读者很好的了解其运作机制，以及去理解其他
模板引擎（如 Velocity）的工作机理。
注：由于原文档部分内容直译可能难于被读者理解，所以有些地方采用意译为主，因此在翻译用词上
难 免 可 能 会 有 出 入 ， 大 家 对 翻 译 的 内 容 有 任 何 意 见 都 可 以 给 我 直 接 发 邮 件 告 知
motomagice@yahoo.com.cn
一、快速入门
1.1、创建配置实例
首先你需要创建一个 Configuration（freemarker.template.Configuration）的实例，
设置其中的某些属性。Configuration 是存放 FreeMarker 的 Application 级别配置信息的一
个重要地方。同时，它还负责创建及预解析模版(template)。
在应用系统的生命周期中（servlet）你只需要初始化创建一次 Configure 实例（因为它
保存的是全局配置信息）
Configuration cfg = new Configuration();
// 指定一个加载模版的数据源
// 这里我设置模版的根目录
cfg.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
// 指定模版如何查看数据模型.这个话题是高级主题…
// 你目前只需要知道这么用就可以了:
cfg.setObjectWrapper(new DefaultObjectWrapper());
你仅仅只需要这么一个配置就可以了。注意：如果你的系统中有多个独立的模块都要使
用 FreeMarker 那么你就需要多个 Configuration 实例（也就是说你每一个组建都需要一个
私有的配置）
1.2、创建数据模型（Data Model）
如果配置简单的数据模型，你可能只需要 java.lang 和 java.util 以及一些 Java
Beans 来构建 FreeMarker 的数据库模型。
字符串使用 java.lang.String .
数字使用 java.lang.Number
布尔使用 java.lang.Boolean
数组以及序列使用 java.util.List
Hashes（一种容器类型可以包含的多种基本类型）使用 java.util.Map
对于 hashes类型的数据模型你也可以使用 bean 对象来存放，而数据项必须和 bean
对象的属性项名称要一致。例如 product 有一个 price 属性，那么 FreeMarker
则可以通过 product.price 来获取相应的值。
让我们来看一看怎么创建下面这个数据模型。
以下是创建该模型的 java 代码：
//创建一个 hash 类型作为数据模型的 root
Map root = new HashMap();
//把字符串 user 放置到 root 中
root.put("user", "Big Joe");
//再创建一个 hash 类型名字叫做 latestProduct
Map latest = new HashMap();
//同样把它放置到 root 中
root.put("latestProduct", latest);
//放置 url 和 name 属性到 latest
latest.put("url", "products/greenmouse.html");
latest.put("name", "green mouse");
对于数据模型中的 latestProduct 属性来说，你也可以使用普通 Java Bean 存储，但是
bean 必须要拥有 url 和 name 两个属性（也就是它有 getURL()这些方法），对于
FreeMarker 模版来说两种定义数据库模型（Map，bean 方式）的方式实质上是一样的。
1.3、获取模版（template）
模版对象一般就是指代 freemarker.template.Template 实例。通常你可以从一
个 Configuration 实例中获取模版实例。你可以通过 getTemplate 这个方法来获得。
Template temp = cfg.getTemplate("test.ftl");
当你调用如上代码的时候，它将会创建一个与 test.ftl 对应的模版实例，也就是读取
/where/you/store/templates/test.ftl 路径下的文件然后解析（编译）。模版对
象一般存储的是经过解析过的模版内容。
如果 Configuration 实例配置缓存 Template 实例策略的话，那么当你再次要获取
test.ftl 的时候，那么就可以从缓存中获得，而不会重新生成一个新的模版实例。
(root)
|
+- user = "Big Joe"
|
+- latestProduct
|
+- url = "products/greenmouse.html"
|
+- name = "green mouse"
