ftl

优质

小牛编辑

127浏览

2023-12-01

概要

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