freeMarker（十二）——模板语言补充知识

学习笔记，选自freeMarker中文文档，译自 Email: ddekany at users.sourceforge.net

1.特殊变量参考

　　特殊变量是由FreeMarker引擎自己定义的变量。要访问它们， 你可以使用 .variable_name 语法。 比如，你不能仅仅写 version，而必须写.version。

注意：在 FreeMarker 2.3.23 版本中，可以使用驼峰格式的特殊变量名来代替蛇形格式， 比如 dataModel 代替 data_model。 但是需要知道在相同的模板中，FreeMarker 会对模板语言部分的标识符强制使用驼峰格式 (用户自定义名称是无效的)。

　　支持的特殊变量有：

• current_template_name： 当前所在的模板名称(从 FreeMarker 2.3.23 版本开始可用)。 如果模板是在Java中 (通过 new Template(null, ...)) 动态创建的， 而不是从后台通过名称 (通过 cfg.getTemplate(name, ...))加载的。 那么它可以为空(null)。 迁移说明：如果使用它来替换废弃的 template_name， 请注意，如果模板没有名字，那么它是一个长度为0的字符串，而不是空 (null)，所以可以在遗留的模板中编写 current_template_name!''。
• data_model：可以用来直接访问数据模型的哈希表。 也就是，使用 global 指令定义在这里不可见的的变量。
• error (从 FreeMarker 2.3.1 版本开始可用)： 该变量在 recover 指令 体中可以访问，它存储了我们要恢复错误的信息。
• globals：可以用来访问全局可访问的变量的哈希表： 数据模型和由 global 指令创建的变量。请注意，用 assign 或 macro 创建的变量不是全局的。 因此当你使用 globals 时你不能隐藏变量。
• lang：返回当前本地化设置的语言部分的值。 比如 .locale 是 en_US， 那么 .lang 是 en。
• locale：返回当前本地化设置的值。 这是一个字符串，比如 en_US。 要获取关于本地化字符串值的更多内容，请参考 setting 指令。
• locale_object (从 FreeMarker 2.3.21 版本开始可用)： 以 java.util.Locale 对象返回本地化设置的当前值，而不是字符串。 也就是说，当你想要传递一个 java.util.Locale 对象给Java方法时， 它可以用于代替 .locale。(Locale 对象会根据 object_wrapper 设置项的值来被包装。是否真的可以以 Locale 对象传递该值给Java方法依赖于对象包装器， 但是对象包装器允许你直接调用Java方法不太可能不支持它。)
• locals：你可以访问局部变量的哈希表 (由 local 指令创建的变量，还有宏的参数)。
• main：可以用来访问主命名空间的哈希表。 请注意，像数据模型中的全局变量通过这个哈希表是 不 可见的。
• main_template_name：顶级模板的名称 (从 FreeMarker 2.3.23 版本开始可用)。(在Java中，这就是 Template.process 调用的模板) 如果模板是在Java中 (通过 new Template(null, ...)) 动态创建出来的，而不是从存储器中以名称加载(通过 cfg.getTemplate(name, ...))的， 那么它可以不存在(null)。迁移说明： 如果使用它来替换废弃的 template_name， 请注意，如果模板没有名字，那么它是一个长度为0的字符串，而不是空 (null)，所以可以在遗留的模板中编写 current_template_name!''。
• namespace：可以用来访问当前 命名空间 的哈希表。 请注意，像数据模型中的全局变量通过这个哈希表是 不 可见的。
• node (由于历史原因重命名为 current_node)：可以用访问者模式(也就是用 visit， recurse 等指令)处理的当前结点。 而且，当使用 FreeMarker XML Ant 任务 时， 它初始存储根结点。
• now：返回当前的日期-时间。使用示例： "Page generated: ${.now}"， "Today is ${.now?date}"， "The current time is ${.now?time}"。
• output_encoding (从 FreeMarker 2.3.1 版本开始可用)：返回当前输出字符集的名称。 如果框架封装 FreeMarker 却没有为 FreeMarker 指定输出字符集时这个特殊变量是不存在的。 (程序员可以在 这里... 阅读关于字符集问题的更多内容。)
• template_name：不要使用它， 因为当使用宏时，它的行为是很奇怪的；使用 current_template_name 或 main_template_name 来代替(参考那里的迁移说明)。 给出主模板的名字，如果我们运行包含或导入的模板，那么就是它们的名字。 当调用宏时，那就有些困惑了：宏调用不改变该特殊变量的值，但是当 nested 被调用时，它会变成模板所属当前命名空间的名字。 (从FreeMarker 2.3.14 版本开始可用)
• url_escaping_charset (从 FreeMarker 2.3.1 版本开始可用)：如果存在， 它存储了应该用于URL转义的字符集的名称。 如果这个变量不存在就意味着没有人指定URL编码应该使用什么样的字符集。 这种情况下，url 内建函数 使用特殊变量 output_encoding 指定的字符集来进行URL编码。 处理机制和它是相同的。(程序员可以在 这里... 阅读关于字符集问题的更多内容。)
• vars：表达式 .vars.foo 返回和表达式 foo 相同的变量。 出于某些原因你不得不使用方括号语法时这是有用的，因为它只对哈希表子变量有用， 所以你需要一个人工创建的父哈希表。比如，要读取有特殊名称的顶层变量可能会把 FreeMarker 弄糊涂，你可以写 .vars["A strange name!"]。 或者，使用和变量 varName 给定的动态名称访问顶层变量你可以写 .vars[varName]。请注意，这个哈希表由 .vars 返回，并不支持 ?keys 和 ?values。
• version：返回 FreeMarker 版本号的字符串形式， 比如 2.2.8。这可以用来检查你的应用程序使用的是哪个版本的 FreeMarker，但是要注意这个特殊变量在 2.3.0 或 2.2.8 版本之前不存在。 非最终发行版本号在数字包含破折号和进一步信息，比如 2.3.21-nightly_20140726T151800Z.

2.FTL中的保留名称

　　下面的这些名称不能在非方括号语法中被用作顶层变量 (比如 .vars["in"])，因为这是FTL中的关键字：

• true：布尔值"true"
• false：布尔值"false"
• gt：比较运算符"大于"
• gte：比较运算符"大于或等于"
• lt：比较运算符"小于"
• lte：比较运算符"小于或等于"
• as：由少数指令使用
• in：由少数指令使用
• using：由少数指令使用

译自 Email: ddekany at users.sourceforge.net