ftl
概要
<#ftl param1=value1 param2=value2 ... paramN=valueN>
这里:
-
param1
,param2
等: 参数的名字,不是表达式。允许的参数有:encoding
,strip_whitespace
,strip_text
等。参见下面。 -
value1
,value2
等: 参数的值。必须是一个常量表达式(如true
, 或"ISO-8859-5"
,或{x:1, y:2}
)。它不能用变量。
描述
告诉 FreeMarker 和其他工具关于模板的信息,
而且帮助程序员来自动检测一个文本文件是否是 FTL 文件。该指令,
如果存在,必须是模板的第一句代码。该指令前的任何 空白 将被忽略。
该指令的老式语法(#
-less)格式是不支持的。
一些设置(编码方式,空白剥离等)在这里给定的话就有最高的优先级, 也就是说,它们直接作用于模板而不管其他任何 FreeMarker 的配置设置。
参数:
-
encoding
: 使用它,你可以在模板文件本身中为模板指定编码方式(字符集) (也就是说,这是新创建Template
的encoding
设置, 而且Configuration.getTemplate
中的encoding
参数不能覆盖它)。要注意, FreeMarker 会尝试会和自动猜测的编码方式 (这依赖于程序员对 FreeMarker 的配置)找到ftl
指令并解释它,然后就会发现ftl
指令会让一些东西有所不同,之后以新的编码方式来重新读取模板。 因此,直到ftl
标记使用第一个编码方式读取到结尾, 模板必须是合法的FTL。 这个参数的合法值是从IANA字符集注册表中参考MIME中的字符集名称。 比如 ISO-8859-5,UTF-8 或 Shift_JIS。 -
strip_whitespace
: 这将开启/关闭 空白剥离。 合法的值是布尔值常量true
和false
(为了向下兼容,字符串"yes"
,"no"
,"true"
,"false"
也是可以的)。 默认值(也就是当你不使用这个参数时)是依赖于程序员对 FreeMarker 的配置, 但是对新的项目还应该是true
。 -
strip_text
:当开启它时, 当模板被解析时模板中所有顶级文本被移除。这个不会影响宏,指令,或插值中的文本。 合法值是布尔值常量true
和false
(为了向下兼容,字符串"yes"
,"no"
,"true"
,"false"
也是可以的)。 默认值(也就是当你不使用这个参数时)是false
。 -
strict_syntax
:这会开启/关闭"严格的语法"。 合法值是布尔值常量true
和false
(为了向下兼容,字符串"yes"
,"no"
,"true"
,"false"
也是可以的)。 默认值(也就是当你不使用这个参数时)是依赖于程序员对 FreeMarker 的配置, 但是对新的项目还应该是true
。(程序员:对于config.setStrictSyntaxMode(true);
你必须明确设置它为true
) 要获取更多信息,可以参考:废弃的 FTL 结构/老式 FTL 语法 -
ns_prefixes
:这是关联结点命名空间前缀的哈希表。 比如:{"e":"http://example.com/ebook", "vg":"http://example.com/vektorGraphics"}
。这通常是用于XML处理的, 前缀可以用于XML查询,但是它也影响 指令visit
和recurse
的工作。 相同结点的命名空间只能注册一个前缀(否则会发生错误), 所以在前缀和结点命名空间中是一对一的关系。前缀D
和N
是保留的。如果你注册前缀D
, 那么除了你可以使用前缀D
来关联结点命名空间, 你也可以设置默认的结点命名空间。前缀N
不能被注册; 当且仅当前缀D
被注册时, 它被用来表示在特定位置没有结点命名空间的结点。 (要参考默认结点命名空间的用法,N
,一般的前缀, 可以参考 XML 处理 和visit
和recurse
)。ns_prefixes
的作用限制在单独的 FTL 命名空间内, 换句话说,就是为模板创建的FTL命名空间内。这也意味着ns_prefixes
当一个FTL命名空间为包含它的模板所创建时才有作用, 否则ns_prefixes
参数没有效果。FTL命名空间当下列情况下为模板创建: (a)模板是"主"模板,也就是说它不是被<#include ...>
来调用的模板,但是直接被调用的(和类Template
或Environment
中的Java方法process
); (b)模板直接被<#import ...>
调用。 -
attributes
:这是关联模板任意属性(名-值对)的哈希表。 属性的值可以是任意类型(字符串,数字,序列等)。FreeMarker 不会尝试去理解属性的含义。 它是由封装 FreeMarker(比如Web应用框架)的应用程序决定的。 因此,允许的属性的设置是它们依赖的应用(Web应用框架)的语义。 程序员:你可以通过关联Template
对象的getCustomAttributeNames
和getCustomAttribute
方法 (从freemarker.core.Configurable
继承而来)获得属性。 如当模板被解析时,关联Template
对象的模板属性, 属性可以在任意时间被读取,而模板不需要被执行。 上面提到的方法返回未包装的属性值,也就是说, 使用 FreeMarker 独立的类型,如java.util.List
。
该指令也决定模板是否使用尖括号语法(比如
<#include 'foo.ftl'>
)或 方括号语法
(如 [#include 'foo.ftl']
)。简单而言,
该指令使用的语法将会是整个模板使用的语法,
而不管 FreeMarker 是如何配置的。