2.3.23

Page Contents

• FTL 方面的变化

• Java 方面的变化

• Other changes

• Notes

发布日期：2015-07-05

FTL 方面的更改

• 列表(#list)已获得一些专门的便利功能，这些功能针对人们在模板中一次又一次执行的典型任务。

• 新的list指令子指令。有else和items可以处理长度为 0 的列表的特殊情况，还有sep可以在项目之间插入分隔符。有关更多详细信息，请参见参考中的 list 指令。

  • 作用于循环变量的新内置函数：var?index(反对var_index)，var?counter(从 1 开始的索引)，var?has_next(反对var_has_next)，var?is_first，var?is_last，var?item_parity(返回"odd"或"even")，var?item_parity_cap，``等。

• 添加了便利分配操作符，它们只能在分配指令(当前为#assign，#global和#local)中使用：

• ++和--：例如，<#assign counter++>等效于<#assign counter = counter + 1>。

  • +=，-=，*=，/=和%=：例如，<#assign counter += 2>等效于<#assign counter = counter + 2>。

• 添加了内置的then，可以像三元运算符someBoolean?then(whenTrue, whenFalse)一样使用。就像大多数其他语言的三元运算符一样，仅会评估其中一个参数表达式。 More details...

• 添加了switch内置函数，它可以像嵌入式(表达式)switch-case-default 语句一样使用：someValue?switch(case1, result1, case2, result2, ... caseN, resultN, defaultResult)，其中defaultResult可以省略(如果所有情况都不匹配，则会出错)。 More details...

• 为模板语言一部分的标识符添加了驼峰大小写支持(用户定义的名称不受影响)。例如，现在<#noEscape>${x?upperCase}</#noEscape>或<#setting numberFormat="0.0">或<#ftl stripText=true>有效。但是，在同一模板内，FreeMarker 将要求您对属于模板语言一部分的所有标识符始终使用相同的命名约定。也可以通过Configuration.setNamingConvention(int)从 Java 对所有模板强制执行相同的命名约定。可以肯定的是，从将来的某些版本开始，将推荐使用驼峰大小写约定，因为从模板调用的 Java API 用户也使用了这种约定。

• 添加了新的special variables，.current_template_name和.main_template_name。这些弃用.template_name，当涉及宏调用时，它总是被破坏。新的.current_template_name始终返回包含对特殊变量的引用的模板的名称，而.main_template_name始终返回最顶层模板的名称。

• 较小的错误消息改进。例如，当someMap[someNumber]抱怨someMap不是序列也不可以强制串起时，在错误消息中为常见问题添加了提示。

• 已修复错误，并通过将incompatible_improvements设置为 2.3.23 激活：存在一个很长的解析时间规则，该规则指出 FTL 源代码本身中的#break必须嵌套在易碎的指令(例如#list或#switch)内。可以用#macro或#function规避此检查，例如<#list 1..1 as x><#macro callMeLater><#break></#macro></#list><@callMeLater />。激活此修复程序后，这将被视为分析时间错误。

Java 方面的更改

• 添加了Configuration.setNamingConvention(int)。默认情况下，FreeMarker 会自动为每个模板自动检测用于模板语言一部分标识符的命名约定(传统 VS 驼峰式大小写)。此设置使您可以强制实施命名约定。

• Configuration(实际上是任何Configurable)设置名称现在也可以使用驼峰式大小写。例如，如果要从属性文件配置 FreeMarker，则可以使用defaultEncoding=utf-8而不是default_encoding=utf-8。您可以混合使用两种命名约定(骆驼式和传统蛇式)，并且Configuration.setNamingConvention(int)不会影响此行为。

• 添加了Configuration.setTemplateUpdateDelayMilliseconds(long)和Configuration.getTemplateUpdateDelayMilliseconds()。这不赞成setTemplateUpdateDelay(int)，后者使用秒分辨率，因此违反 Java 约定并且经常会引起误解。 (也不能有吸气剂对.)

• template_update_delay设置在指定为字符串时(在java.util.Properties内部)，支持时间单位，例如template_update_delay=500 ms。

• 添加了Environment.getCurrentTemplate()方法，该方法返回当前执行的模板(与主模板相反)。

• 添加了WebappTemplateLoader.setAttemptFileAccess(boolean)，可以用来禁用我们试图通过直接文件访问来加载模板的旧技巧，以便模板更新无需重启就可以进行。禁用 URL 连接缓存(someURLBasedTemplateLoader.setURLConnectionUsesCaches(false)，这是自incompatible_improvements 2.3.21 以来的默认设置)可能可以解决现代 Servlet 容器上的问题。

• 在FreemarkerServlet TemplatePath init 参数中，路径(如/templates)可以具有?settings(...)后缀，您可以使用该后缀设置结果TemplateLoader的 JavaBean 属性。例如：<param-value>/templates?settings(attemptFileAccess=false, URLConnectionUsesCaches=false)</param-value>

• 添加了FileTemplateLoader.setEmulateCaseSensitiveFileSystem(boolean)。在 Windows 上进行开发时，这很方便，但是将部署到具有区分大小写的文件系统的平台上。默认值为false，而true仅用于开发，不适用于生产安装。通过将org.freemarker.emulateCaseSensitiveFileSystem系统属性设置为true可以覆盖默认值。

• 已修复的错误\ [424]：WebappTemplateLoader找不到存储在WEB-INF/lib/*.jar/META-INF/resources中的模板。自 Servlet 3.0 起，该目录下的文件就被视为ServletContext资源，但是WebappTemplateLoader通常由于一些内部技巧而无法看到它们。

• 已修复的错误：如果已成功打开模板“文件”以进行读取，但是在读取其内容时出现了IOException，则解析器(JavaCC)的行为就好像模板“文件”在此结束，并且抑制了异常。它实际上是一个 JavaCC 怪癖，它也影响许多其他基于 JavaCC 的语言，但是现在 FreeMarker 在Template构造函数中添加了解决方法，因此现在将按预期抛出异常。

• 已修复的错误：InvalidReferenceException.FAST_INSTANCE可能会意外地存储对Environment实例的引用，因此永远不会进行垃圾回收。

• 错误修复\ [426]：将incompatible_improvements设置为 2.3.22 时，由于 2.3.22 中的疏忽，模板中的特殊变量引用.template_name始终返回主(最顶部)模板的名称。将incompatible_improvements设置为 2.3.23 将恢复旧的，向后兼容的行为。 (请注意，我们模仿的旧行为本身就被破坏了，因为它在宏调用中不能很好地工作；您应该使用.current_template_name或.main_template_name.)

• 错误已修复\ [53]：对于具有相同层次结构级别的 AST(抽象语法树)节点数量非常多的模板，模板解析异常缓慢。

• 错误修复：当模板在第一次加载期间同时在后备存储上同时替换时，该模板的旧版本可能会与新版本的时间戳一起进入缓存，因此在配置后不会重新加载更新延迟。

• 错误修复：无法通过Configurable.setSetting(String, String) API 设置log_template_exceptions设置(在 2.3.22 中添加)。

• 已修复的错误：StringUtil.FTLStringLiteralEnc逃脱了$(因此产生了非法逃生)，并且在$和#之后没有逃脱{。尽管此功能仅由 FreeMarker 用于生成错误消息，但它是一种公共方法，因此任何人都可以使用它。

• 已修复的错误：各种规范形式的故障(就 FreeMarker 而言，它们仅影响错误消息)。

Other changes

• 借助 Evangelia Dendramis，现代化的手册和站点设计具有改进的功能(始终可见的导航树，在手册中进行搜索等)。 (现在该站点还使用与手册相同的格式和 HTML 生成器.)

• 许多较小的手册和站点内容更新/改进。

Notes

与 2.3.23 RC1 相比的更改：

• 如果模板没有名称，则现在缺少.current_name_name和.main_template_name(null)而不是""

• 一些小的错误消息改进

• Documentation refinements