在 入门 章节中,
我们已经知道如何使用基本的Java类(Map,
String,等)来构建数据模型了。在内部,模板中可用的变量都是实现了
freemarker.template.TemplateModel 接口的Java对象。
但在数据模型中,可以使用基本的Java集合类作为变量,因为这些变量会在内部被替换为适当的
TemplateModel 类型。这种功能特性被称作是
对象包装。对象包装功能可以透明地把
任何 类型的对象转换为实现了 TemplateModel
接口类型的实例。这就使得下面的转换成为可能,如在模板中把
java.sql.ResultSet 转换为序列变量,
把 javax.servlet.ServletRequest 对象转换成包含请求属性的哈希表变量,
甚至可以遍历XML文档作为FTL变量(参考这里)。包装(转换)这些对象,
需要使用合适的,也就是所谓的 对象包装器 实现(可能是自定义的实现);
这将在后面讨论。
现在的要点是想从模板访问任何对象,它们早晚都要转换为实现了 TemplateModel
接口的对象。那么首先你应该熟悉来写 TemplateModel 接口的实现类。
有一个粗略的 freemarker.template.TemplateModel
子接口对应每种基本变量类型(TemplateHashModel 对应哈希表,
TemplateSequenceModel 对应序列,
TemplateNumberModel 对应数字等等)。比如,想为模板使用
java.sql.ResultSet 变量作为一个序列,那么就需要编写一个
TemplateSequenceModel 的实现类,这个类要能够读取
java.sql.ResultSet 中的内容。我们常这么说,使用
TemplateModel 的实现类 包装 了
java.sql.ResultSet,基本上只是封装
java.sql.ResultSet 来提供使用普通的
TemplateSequenceModel 接口访问它。请注意一个类可以实现多个
TemplateModel 接口;这就是为什么FTL变量可以有多种类型
(参看 模板开发指南/数值,类型/基本内容)
请注意,这些接口的一个细小的实现是和
freemarker.template 包一起提供的。
例如,将一个 String 转换成FTL的字符串变量,
可以使用 SimpleScalar,将 java.util.Map
转换成FTL的哈希表变量,可以使用 SimpleHash 等等。
如果想尝试自己的 TemplateModel 实现,
一个简单的方式是创建它的实例,然后将这个实例放入数据模型中
(也就是把它 放到 哈希表的根root上)。
对象包装器将会给模板提供它的原状,因为它已经实现了
TemplateModel 接口,所以没有转换(包装)的需要。
(这个技巧当你不想用对象包装器来包装(转换)某些对象时仍然有用。)