特殊变量参考

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

Note:

在 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 指令创建的变量。请注意,用 assignmacro 创建的变量不是全局的。 因此当你使用 globals 时你不能隐藏变量。
  • lang:返回当前本地化设置的语言部分的值。 比如 .localeen_US, 那么 .langen
  • 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):可以用访问者模式(也就是用 visitrecurse 等指令)处理的当前结点。 而且,当使用 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_namemain_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.