ftl

Page Contents

概要

<#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 是如何配置的。