ftl

Page Contents

• Synopsis

• Description

Synopsis

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

Where:

• param1，param2，...等：参数名称。不是表达。允许的参数为：encoding，strip_whitespace，strip_text，...等。见下文。

• value1，value2，...等：参数的值。这必须是一个常量表达式(如true或"ISO-8859-5"或{x:1, y:2})。它不能使用变量。

Description

告诉有关 FreeMarker 和其他工具模板的信息，还帮助程序自动检测文本文件是否为 FTL 文件。该指令(如果存在)必须是模板中的第一件事。该指令之前的任何white-space都将被忽略。不支持此指令的旧语法(# -less)格式。

此处给出的设置(编码，空格剥离等)具有最高优先级，也就是说，无论任何 FreeMarker 配置设置如何，它们都将用于模板。

Possible parameters:

• attributes：这是将任意属性(名称/值对)与模板相关联的哈希。属性的值可以是任何类型(字符串，数字，序列等)。 FreeMarker 不会尝试理解属性的含义。这取决于封装 FreeMarker 的应用程序(作为 Web 应用程序框架)。因此，允许的属性集及其语义取决于应用程序(Web 应用程序框架)。程序员：您可以通过getCustomAttributeNames和getCustomAttribute方法(继承自freemarker.core.Configurable)获取与Template对象关联的属性。由于在解析模板时模板属性与Template对象相关联，因此可以随时读取属性，因此无需执行模板。提到的方法返回未包装的属性值，即 FreeMarker 独立类型为java.util.List。

• auto_esc：用于打开或关闭auto-escaping的布尔常量。它取决于 FreeMarker 配置的auto_escaping_policy，但是如果当前output format默认使用自动转义，通常默认情况下会启用自动转义。因此，您通常使用它来禁用自动转义(false值)。当当前输出格式为非标记输出格式(因此无法转义)时尝试使用true值将导致parse-time error。请注意，您只能使用autoesc和noautoesc directives打开/关闭模板的自动转义。

• encoding：可以在模板文件本身中指定模板的编码(字符集)。 (也就是说，这将是新创建的Template的encoding设置，甚至Configuration.getTemplate的encoding参数都不能覆盖它)。但是请注意，FreeMarker 会首先尝试使用自动猜测的编码(取决于程序员设置的 FreeMarker 配置)来查找和解释ftl指令，然后才意识到ftl指令是否规定了其他内容，然后重新读取具有新编码的模板。因此，模板必须是有效的 FTL，直到ftl标记的末尾先尝试编码。此参数的有效值是 IANA 字符集注册表中 MIME 首选的字符集名称，例如 ISO-8859-5，UTF-8 或 Shift_JIS。

• ns_prefixes：这是将前缀与节点名称空间相关联的哈希。例如：{"e":"http://example.com/ebook", "vg":"http://example.com/vektorGraphics"}。这主要用于 XML 处理，在 XML 处理中可以在 XML 查询中使用前缀，但是它也会影响指令访问和递归的工作。同一节点名称空间只能注册一个前缀(否则会发生错误)，因此前缀和节点名称空间之间存在一对一的关系。前缀D和N保留。如果注册前缀D，则除了将节点名称空间与前缀D关联之外，还需要设置默认的节点名称空间。前缀N无法注册；当(仅)注册前缀D时，它用于表示某些位置没有节点名称空间的节点。 (要了解默认节点名称空间N和前缀的一般用法，请参见参考中有关XML processing和访问并递归的部分。)ns_prefixes的作用仅限于单个FTL namespace，即，针对该名称创建的 FTL 名称空间模板。这也意味着ns_prefixes仅在为包含 FTL 名称空间的模板创建 FTL 名称空间时才有效，否则ns_prefixes参数无效。在以下情况下为模板创建 FTL 命名空间：(a)模板是“主”模板，也就是说，它不是<#include ...>的结果而调用，而是直接调用(使用Template类的process Java 方法)。或Environment)； (b)使用<#import ...>直接调用模板。

• output_format：指定此模板的output format。这必须是字符串 Literals，它表示输出格式的名称。参见此处的 sched 义输出格式表。如果程序员通过registered_custom_output_formats配置设置(Configuration.setRegisteredCustomOutputFormats(...))添加了其他名称，则可以存在其他名称。 Configuration必须知道引用的输出格式，否则会出现parse-time error。该名称还可以将所谓的组合输出格式称为"outerFormatName{innerFormatName}"； 在此处查看有关组合输出格式的更多信息。

• strict_syntax：这将打开/关闭“严格语法”，这是 FreeMarker 2.1 之后的标准语法。有效值为布尔常量true和false。 (并且为了向后兼容，使用字符串"yes"，"no"，"true"，"false")。默认值(即不使用此参数时)取决于程序员设置的 FreeMarker 配置，但最确定的是设置为true。有关更多信息，请阅读：不建议使用的 FTL 构造/旧的 FTL 语法

• strip_text：启用后，解析模板时，模板中的所有顶级文本都会被删除。这不会影响宏，指令或插值中的文本。有效值为布尔常量true和false。 (并且为了向后兼容，使用字符串"yes"，"no"，"true"，"false")。默认值(即不使用此参数时)为false。

• strip_whitespace：这将启用/禁用white-space stripping。有效值为布尔常量true和false。 (并且为了向后兼容，使用字符串"yes"，"no"，"true"，"false")。默认值(即当您不使用此参数时)取决于程序员设置的 FreeMarker 配置，但对于新项目，它应为true。

该指令还确定模板是否使用尖括号语法(例如<#include 'foo.ftl'>)或方括号语法(例如[#include 'foo.ftl'])。简而言之，无论 FreeMarker 配置设置如何，此指令使用的语法都将是整个模板使用的语法。