2.1
Page Contents
发布日期:2002-10-17
模板和 Java API 与 2.0 版本不完全兼容。您将需要重新访问现有的代码和模板,或者仅将 2.1 用于新项目。不便之处,敬请原谅;自 1.x 系列以来,FreeMarker 发生了一些革命性的变化。我们希望事情能够早日成熟,以便我们提供(几乎)向后兼容的发行版。请注意,有一个可以通过Configuration.setClassicCompatible(true)
设置的向后兼容性标志,该标志使新的 FreeMarker 模仿大多数 FreeMarker 1.x 的怪癖。
FTL(FreeMarker 模板语言)的更改
-
更严格,揭示模板中的意外错误,防止出现错误时显示不正确的信息:
-
尝试访问未定义的变量会导致错误并中止模板处理(至少默认情况下;请参阅下文)。在早期版本中,未定义的变量被静默地视为空(零长度)字符串。但是,您可以使用一些新的内置函数处理模板中的未定义变量。例如,
${foo?if_exists}
与早期版本的${foo}
等价。从另一角度来看,从模板设计者的角度来看,空值不再存在。引用的任何内容都必须是已定义的变量。
但是请注意,程序员可以配置 FreeMarker,使其忽略某些错误(例如,未定义的变量),并通过跳过有问题的部分 continue 进行模板处理。此“宽松”策略应仅用于不显示关键信息的网站。
-
新变量类型:boolean。
if
/elseif
中的条件和逻辑运算符(&&
,||
,!
)的操作数必须为布尔值。空字符串不再被视为逻辑错误。 -
局部和全局变量。更多信息:模板作者指南/模板中的其他/定义变量
-
宏的局部变量。您可以使用local directive在宏定义主体中创建/替换局部变量
- 您可以使用global directive创建/替换全局(nonlocal)变量
-
现在,默认情况下,include指令将传递的文件名视为包含模板路径的相对文件名。要指定绝对模板路径,现在必须在其前面加上一个斜线。
-
include指令现在可以使用获取算法(Zope 系统熟悉的算法)来查找要包含的模板。基本上,如果未在首先查找模板的位置找到模板,则会在父目录中查找模板。但是,这不是默认行为,而是由新的语法元素触发的。
-
严格的语法模式:允许您生成任意的 SGML(XML),而不必担心与 FreeMarker 指令的冲突。有关更多信息,请阅读:模板语言参考/不建议使用的 FTL 构造/旧的 FTL 语法
-
简洁的 Comments:您可以使用
<#-- ... -->
代替<comment>...</comment>
-
可用于更改模板内的区域设置(和其他设置)的指令:setting
-
显式刷新输出缓冲区的指令:flush
-
顶级(根)哈希可通过变量
root
获得,该变量现在是保留名称。 -
错误命名的
function
指令已重命名为macro
。 -
字符串 Literals 支持各种新的escape sequences,包括 UNICODE 转义(
\xCODE
) -
compress指令现在在删除换行符时更加保守。
-
内置首字母大写:cap_first
-
内置生成即时模板:interpret
-
stop指令具有一个可选参数来描述终止原因
-
更好的错误消息。
-
新变量类型:日期。 日期支持是实验性的。将来可能会发生重大变化。使用时请记住这一点.
Java 方面的更改
-
ObjectWrapper
:您可以将非TemplateModel
对象直接放入哈希,序列和集合中,并将使用适当的TemplateModel
实现将它们自动包装。据此更改了暴露给模板(SimpleXXX
)的对象的 API,例如,在SimpleHash
中,旧的put(String key, TemplateModel value)
现在为put(String key, Object object)
。另外,您可以将任何类型的对象作为数据模型传递给Template.process
。基于替代的ObjectWrapper
可以为设计人员自动公开任何 Java 对象的成员。详细信息:Object wrapping,Bean wrapper,Jython wrapper。 -
引入
Configuration
对象作为中心点,以保存所有与 FreeMarker 相关的全局设置,以及希望从任何模板中获得的常用变量。它还封装了模板缓存,可用于加载模板。有关更多信息,请阅读程序员指南/配置。 -
TemplateLoader
:可插入模板加载器,将缓存与模板加载分开 -
TemplateNumberModel
-s 不再控制其格式。他们只是存储数据(即数字)。数字格式化由 FreeMarker 内核根据locale
和number_format
设置完成。此逻辑也适用于新的实验日期类型。 -
TemplateBooleanModel
介绍:在 true/false 条件下,只有实现此接口的对象才可以用作布尔值。更多信息:程序员指南/数据模型/标量 -
TemplateDateModel
引入:实现此接口的对象被识别为日期,并且可以按区域设置区分格式。 日期支持在 FreeMarker 2.1 中是试验性的。将来可能会发生重大变化。使用时请记住这一点. -
TemplateModelRoot
界面已弃用。从 FreeMarker 2.1 开始,您可以简单地使用TemplateHashModel
的任何实例。这实际上是由于重大的体系结构更改。在模板中设置或定义的变量存储在单独的Environment
对象中,该对象仅在呈现模板时存在。因此,模板不会修改根哈希。 -
转变的转变
-
完全重写了
TemplateTransformModel
界面。更加灵活,并且不施加输出保持。更多信息:程序员指南/数据模型/指令-
transform
指令现在采用一组可选的键/值对。<transform myTransform; key1=value1, key2=value2 ...>
。更多信息:transform directive -
FreeMarker 核心随附的转换现在默认情况下可用于所有模板-即
<transform html_escape>
将调用freemarker.template.utility.HtmlEscape
转换。更多信息:程序员指南/配置/共享变量
-
-
用户定义的
TemplateModel
对象现在可以使用Environment
实例访问运行时环境(读取和设置变量,获取当前语言环境等),该实例可以通过静态Environment.getCurrentEnvironment()
方法获得。结果,TemplateScalarModel.getAsString
已被更改:它没有语言环境参数。 -
TemplateExceptionHandler
-s 使得您可以定义自己的规则,以便在模板处理期间发生运行时错误(例如访问不存在的变量)时该怎么做。例如,您可以中止模板处理(大多数站点建议使用),或者跳过有问题的语句并 continue 模板处理(类似于旧行为)。 DebugMode 已删除,请改用TemplateExceptionHandler.DEBUG_HANDLER
或HTML_DEBUG_HANDLER
。 -
记录:FreeMarker 记录某些事件(例如运行时错误)。有关更多信息,请阅读Programmer's Guide/Miscellaneous/Logging。
-
SimpleIterator
已删除,但我们提供了TemplateCollectionModel
实现:SimpleCollection
。 -
算术引擎是可插入的(
Configuration.setArithmeticEngine
)。核心发行版带有两个引擎:ArithmeticEngine.BIGDECIMAL_ENGINE
(默认值),它将所有数字转换为BigDecimal
,然后对其进行运算;以及ArithmeticEngine.CONSERVATIVE_ENGINE
使用(或多或少)Java 语言的扩展转换,而不是将所有内容都转换为BigDecimal
。 -
对
freemarker.ext.beans
软件包的更改:JavaBeans 适配器层进行了几项重大更改。首先,BeansWrapper
不再是静态 Util 类-您现在可以创建它的实例,并且每个实例都可以具有自己的实例缓存策略和安全设置。这些安全性设置也是新的-您现在可以创建 JavaBean 包装器,以隐藏在模板环境中被认为不安全或不合适的方法。默认情况下,您不能再从模板中调用System.exit()
之类的方法(尽管您可以手动关闭这些保护措施)。StaticModel
和StaticModels
类消失了;现在,它们的功能已被BeansWrapper.getStaticModels()
方法代替。 -
freemarker.ext.jython
软件包:FreeMarker 现在可以使用Jython wrapper直接将 Jython 对象用作数据模型。 -
更改为
freemarker.ext.jdom
软件包:软件包现在使用* Jaxen 软件包而不是其前身 werken.xpath 软件包来评估 XPath 表达式。由于 Jaxen 是 werken.xpath *的后继者,因此可以认为这是升级。结果,现在可以在 XPath 表达式中识别名称空间前缀,并且整体 XPath 一致性更好。 -
更好的错误报告:如果由于抛出
TemplateException
或使用<#stop>
指令而中止了模板的处理,则 FreeMarker 现在将输出相对于模板源具有行号和列号的执行跟踪。 -
输出被写入一个简单的
Writer
;不再PrintWriter
。这种重新设计导致 FreeMarker 在模板处理期间不再吞下IOException
。 -
各种 API 清理,主要是消除多余的构造函数和方法重载。
Other changes
- 文档已从头开始重写
RC1 和最终版本之间的差异
-
添加了对日期模型和对语言环境敏感的日期格式的支持。 日期支持在 FreeMarker 2.1 中是试验性的。将来可能会发生重大变化。使用时请记住这一点.
-
添加了内置的
default
,可以为未定义的表达式指定默认值。 -
已删除
SimpleIterator
,已引入SimpleCollection
-
算术引擎是可插入的。核心现在包含两个算术引擎:
ArithmeticEngine.BIGDECIMAL_ENGINE
和ArithmeticEngine.CONSERVATIVE_ENGINE
。 -
BeansWrapper
支持新的曝光级别:EXPOSE_NOTHING
-
Constants
界面已删除。..._WRAPPER
常量已从Constants
移至ObjectWrapper
,EMPTY_STRING
常量已移至TemplateScalarModel
,NOTHING
常量已移至TemplateModel
,TRUE
和FALSE
常量已移至TemplateBooleanModel
。 -
JAVABEANS_WRAPPER
重命名为BEANS_WRAPPER
-
Configuration.get
和put
,putAll
重命名为getSharedVariable
和setSharedVariable
,setAllSharedVariables
-
Configuration.getClassicCompatibility
,setClassicCompatibility
重命名为isClassicCompatible
,setClassicCompatible
-
带有
useReflection
参数的Template.process
方法重载已删除。但是现在Configuration
中有setObjectWrapper
方法,因此您可以在此处设置首选的根对象包装器。 -
消除了一些多余的方法重载;这些更改与 RC1 向后兼容
-
各种 JavaDoc 和 Manual 的小改进
-
错误修正:
include
指令错误地计算了相对路径的基本路径 -
错误修正:我们不小心使用了 J2SE 1.3 类,但是 FreeMarker 2.1 必须能够在 J2SE 1.2 上运行