概要

<#ftl param1=value1 param2=value2 ... paramN=valueN>

这里:

  • param1, param2 等: 参数的名字,不是表达式。允许的参数有: encodingstrip_whitespacestrip_text 等。参见下面。
  • value1, value2 等: 参数的值。必须是一个常量表达式(如 true, 或 "ISO-8859-5",或 {x:1, y:2})。它不能用变量。

描述

告诉 FreeMarker 和其他工具关于模板的信息, 而且帮助程序员来自动检测一个文本文件是否是 FTL 文件。该指令, 如果存在,必须是模板的第一句代码。该指令前的任何 空白 将被忽略。 该指令的老式语法(#-less)格式是不支持的。

一些设置(编码方式,空白剥离等)在这里给定的话就有最高的优先级, 也就是说,它们直接作用于模板而不管其他任何 FreeMarker 的配置设置。

参数:

  • encoding: 使用它,你可以在模板文件本身中为模板指定编码方式(字符集) (也就是说,这是新创建 Templateencoding 设置, 而且 Configuration.getTemplate 中的 encoding 参数不能覆盖它)。要注意, FreeMarker 会尝试会和自动猜测的编码方式 (这依赖于程序员对 FreeMarker 的配置)找到 ftl 指令并解释它,然后就会发现 ftl 指令会让一些东西有所不同,之后以新的编码方式来重新读取模板。 因此,直到 ftl 标记使用第一个编码方式读取到结尾, 模板必须是合法的FTL。 这个参数的合法值是从IANA字符集注册表中参考MIME中的字符集名称。 比如 ISO-8859-5,UTF-8 或 Shift_JIS。

  • strip_whitespace: 这将开启/关闭 空白剥离。 合法的值是布尔值常量 truefalse (为了向下兼容,字符串 "yes""no""true""false" 也是可以的)。 默认值(也就是当你不使用这个参数时)是依赖于程序员对 FreeMarker 的配置, 但是对新的项目还应该是 true

  • strip_text:当开启它时, 当模板被解析时模板中所有顶级文本被移除。这个不会影响宏,指令,或插值中的文本。 合法值是布尔值常量 truefalse (为了向下兼容,字符串 "yes""no""true""false" 也是可以的)。 默认值(也就是当你不使用这个参数时)是 false

  • strict_syntax:这会开启/关闭"严格的语法"。 合法值是布尔值常量 truefalse (为了向下兼容,字符串 "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查询,但是它也影响 指令 visitrecurse的工作。 相同结点的命名空间只能注册一个前缀(否则会发生错误), 所以在前缀和结点命名空间中是一对一的关系。前缀 DN 是保留的。如果你注册前缀 D, 那么除了你可以使用前缀 D 来关联结点命名空间, 你也可以设置默认的结点命名空间。前缀 N 不能被注册; 当且仅当前缀 D 被注册时, 它被用来表示在特定位置没有结点命名空间的结点。 (要参考默认结点命名空间的用法,N,一般的前缀, 可以参考 XML 处理visitrecurse)。ns_prefixes 的作用限制在单独的 FTL 命名空间内, 换句话说,就是为模板创建的FTL命名空间内。这也意味着 ns_prefixes 当一个FTL命名空间为包含它的模板所创建时才有作用, 否则 ns_prefixes 参数没有效果。FTL命名空间当下列情况下为模板创建: (a)模板是"主"模板,也就是说它不是被 <#include ...> 来调用的模板,但是直接被调用的(和类 TemplateEnvironment 中的Java方法 process); (b)模板直接被 <#import ...> 调用。

  • attributes:这是关联模板任意属性(名-值对)的哈希表。 属性的值可以是任意类型(字符串,数字,序列等)。FreeMarker 不会尝试去理解属性的含义。 它是由封装 FreeMarker(比如Web应用框架)的应用程序决定的。 因此,允许的属性的设置是它们依赖的应用(Web应用框架)的语义。 程序员:你可以通过关联 Template 对象的 getCustomAttributeNamesgetCustomAttribute 方法 (从 freemarker.core.Configurable 继承而来)获得属性。 如当模板被解析时,关联 Template 对象的模板属性, 属性可以在任意时间被读取,而模板不需要被执行。 上面提到的方法返回未包装的属性值,也就是说, 使用 FreeMarker 独立的类型,如 java.util.List

该指令也决定模板是否使用尖括号语法(比如 <#include 'foo.ftl'>)或 方括号语法 (如 [#include 'foo.ftl'])。简单而言, 该指令使用的语法将会是整个模板使用的语法, 而不管 FreeMarker 是如何配置的。