2.1

Page Contents

• FTL(FreeMarker 模板语言)中的更改

• Java 方面的变化

• Other changes

• RC1 和最终版本之间的差异

发布日期：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 上运行