特殊变量

目录

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

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

current_template_name

从 FreeMarker 2.3.23 版本开始可用 current_template_name 来获取当前模板名称。如果模板是在 Java 中 (通过 new Template(null, ...)) 动态创建的, 而不是从后台通过名称 (通过 cfg.getTemplate(name, ...))加载的,那么 current_template_name 为空(null)。 

注意:如果使用 template_name 去获取 Java 动态创建的模版名称,返回一个长度为 0 的字符串,而不是空 (null),所以可以在遗留的模板中编写 current_template_name!''。例如:

<#-- 获取模版名称 -->
<p>${.current_template_name!''}</p>
<p>${.template_name}</p>

data_model

可以用来直接访问数据模型的哈希表。如果 key 存在空格,则可以使用 ${.data_model['hello world']} 访问。 使用 assign 和 global 指令定义的变量 data_model 是不可见的。实例:

<#assign variable1="Hello Freemarker">
<#global variable2="Hi! Freemarker">
${.data_model.variable1!'not access'}
${.data_model['variable1']!'not access'}

${.data_model.variable2!'not access'}
${.data_model['variable2']!'not access'}

${.data_model.siteName!'not access'}
${.data_model['siteName']!'not access'}

输出结果:

not access
not access

not access
not access

https://www.hxstrive.com
https://www.hxstrive.com

注意:上面的 siteName 在 Java 数据模型中进行定义。

error

从 FreeMarker 2.3.1 版本开始可用,该变量存储了错误信息。实例:

<#attempt>
    <div>变量值: ${.data_model.accessNotExistVariable}</div>
<#recover>
    <div>错误信息:${.error}</div>
</#attempt>

输出结果:

    <div>错误信息:The following has evaluated to null or missing:
==> .data_model.accessNotExistVariable  [in template "template19.ftl" at line 52, column 17]
----
Tip: It's the step after the last dot that caused this error, not those before it.
----
Tip: If the failing expression is known to be legally refer to something that's sometimes null or missing, either specify a default value like myOptionalVar!myDefault, or use <#if myOptionalVar??>when-present<#else>when-missing</#if>. (These only cover the last step of the expression; to cover the whole expression, use parenthesis: (myOptionalVar.foo)!myDefault, (myOptionalVar.foo)??
----
----
FTL stack trace ("~" means nesting-related):
- Failed at: ${.data_model.accessNotExistVariable}  [in template "template19.ftl" at line 52, column 15]
----</div>

注意:在 attempt 指令体中抛出错误时,将执行 recover 指令体中的内容(这里是输出错误信息)。

globals

可以用来访问全局可访问的变量的哈希表:数据模型和由 global 指令创建的变量。请注意,用 assign 或 macro 创建的变量不是全局的。 因此当你使用 globals 时你不能隐藏变量。实例:

<#assign globalVar1="https://www.hxstrive.com">
<#global globalVar2="https://www.hxstrive.com">
${.globals.globalVar1!'not access'}
${.globals.globalVar2!'not access'}
${.globals.globalVar3!'not access'}

输出结果:

not access
https://www.hxstrive.com
https://www.hxstrive.com

注意:变量 globalVar3 在 Java 数据模型中进行定义。

lang

返回当前本地化设置的语言部分的值。 比如 .locale 是 en_US,那么 .lang 是 en。例如:

<p>${.lang}</p>

locale

返回当前本地化设置的值。 这是一个字符串,比如 en_US。要获取关于本地化字符串值的更多内容。

<p>${.locale}</p>

locale_object

从 FreeMarker 2.3.21 版本开始可用,以 java.util.Locale 对象返回本地化设置的当前值,而不是字符串。 也就是说,当你想要传递一个 java.util.Locale 对象给Java方法时, 它可以用于代替 .locale。(Locale 对象会根据object_wrapper 设置项的值来被包装。是否真的可以以 Locale 对象传递该值给Java方法依赖于对象包装器, 但是对象包装器允许你直接调用Java方法不太可能不支持它)

locals

你可以访问局部变量的哈希表 (由 local 指令创建的变量,还有宏的参数)。

main

可以用来访问主命名空间的哈希表。 注意:数据模型中的全局变量通过这个哈希表是不可见的。实例:

<#-- sub/template19_sub.ftl 模版内容 -->
<#macro testMacro arg1>
    arg1=${arg1}
    mainVar=${mainVar!'no'}
    mainVar=${.main.mainVar!'no'}
    mainVar2=${.main.mainVar2!'no'}
</#macro>

<#-- main 模版 -->
<#import "sub/template19_sub.ftl" as My >
<#assign mainVar="main template variable">
<#global mainVar2="global varable">
<@My.testMacro arg1="Hello FreeMarker" />

输出结果:

    arg1=Hello FreeMarker
    mainVar=no
    mainVar=main template variable
    mainVar2=no

上面演示了,在子模板中使用 .main.variableName 访问主模板定义的变量,但是不能访问 globals 指令定义的变量。

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

可以用来访问当前 命名空间 的哈希表。 请注意,像数据模型中的全局变量通过这个哈希表是不可见的。例如:

<#assign title="特殊变量">
<p>${.namespace.title}</p>
<p>${.namespace.currentDate!'-'}</p>

输出结果:

<p>特殊变量</p>
<p>-</p>

其中,currentDate 变量是在数据模型中定义的全局变量,.namespace 不能访问 currentDate 变量。

node

由于历史原因重命名为 current_node,可以用访问者模式 (也就是用 visit,recurse 等指令) 处理的当前结点。而且,当使用 FreeMarker XML Ant 任务时,它初始存储根结点。

now

返回当前的日期-时间。例如:

<#-- 获取当前日期 -->
<p>${.now}</p>
<p>当前日期:${.now?date}</p>
<p>当前时间:${.now?time}</p>

输出结果:

<p>2020-7-2 12:58:54</p>
<p>当前日期:2020-7-2</p>
<p>当前时间:12:58:54</p>

output_encoding 

从 FreeMarker 2.3.1 版本开始可用。

返回当前输出字符集的名称。如果框架封装 FreeMarker 却没有为 FreeMarker 指定输出字符集时这个特殊变量是不存在的。因此,使用时需要指定默认值,否则会报错。例如:

${.output_encoding!''}

template_name

从FreeMarker 2.3.14 版本开始可用。

不推荐使用,因为当使用宏时,它的行为是很奇怪的;使用 current_template_name 或 main_template_name 来代替。

url_escaping_charset

从 FreeMarker 2.3.1 版本开始可用。

如果存在,它存储了应该用于URL转义的字符集的名称。 如果这个变量不存在就意味着没有人指定URL编码应该使用什么样的字符集。 这种情况下,url 内建函数使用特殊变量 output_encoding 指定的字符集来进行URL编码。例如:

<p>${url_escaping_charset!''}</p>

注意:如果没有指定URL编码吗,这个变量将不存在,因此使用时需要指定默认值。

vars

表达式 .vars.foo 返回和表达式 foo 相同的变量。出于某些原因你不得不使用方括号语法时这是有用的,因为它只对哈希表子变量有用, 所以你需要一个人工创建的父哈希表。比如,要读取有特殊名称的顶层变量可能会把 FreeMarker 弄糊涂,你可以写 .vars["A strange name!"]。 或者,使用和变量 varName 给定的动态名称访问顶层变量你可以写 .vars[varName]。例如:

<#!-- 使用变量名获取根变量的值 -->
<#assign verName="variableName">
<#assign variableName="vars 的用法">
<p>${.vars[verName]}</p>
<#-- 访问变量名为 “hello world” 的值 -->
<p>${.vars["hello world"]}</p>

注意:这个哈希表由 .vars 返回,并不支持 ?keys 和 ?values。

version

注意这个特殊变量在 2.3.0 或 2.2.8 版本之前不存在。

返回 FreeMarker 版本号的字符串形式,如:2.2.8。这可以用来检查你的应用程序使用的是哪个版本的 FreeMarker。例如:

<#-- 获取版本信息 -->
<p>${.version}</p>

注意:非最终发行 FreeMarker 的版本号在数字包含破折号和进一步信息,比如:2.3.21-nightly_20140726T151800Z。

说说我的看法
全部评论(
没有评论
关于
本网站属于个人的非赢利性网站,转载的文章遵循原作者的版权声明,如果原文没有版权声明,请来信告知:hxstrive@outlook.com
公众号