include

Page Contents

Synopsis

<#include path>
or
<#include path options>

Where:

Description

Note:

使用include指令几乎总是一个坏习惯，您应该考虑改用导入指令！即使使用import会增加一些详细信息，但从长远来看，它也会有所回报。参见原因在这里...

您可以使用它将另一个 FreeMarker 模板文件(由path参数指定)插入模板。包含的模板的输出将插入出现include标签的位置。包含文件与包含模板共享变量，就像将其复制粘贴到其中一样。 include指令并没有 true 被包含文件的内容替换，而是每次 FreeMarker 在模板处理过程中每次到达include指令时都处理包含文件。因此，例如，如果include在list循环内，则可以在每个循环中指定不同的文件名。

Note:

该指令不会与 JSP(Servlet)include 混淆，因为它根本不涉及 Servlet 容器，只处理另一个 FreeMarker 模板，而不会“离开” FreeMarker。关于如何进行“ JSP 包含” read this...

path参数可以是相对路径，例如"foo.ftl"和"../foo.ftl"，也可以是绝对路径，例如"/foo.ftl"。相对路径是相对于包含import指令的模板目录的。绝对路径是相对于程序员在配置 FreeMarker 时定义的基础(通常称为“模板的根目录”)。

Note:

这与 FreeMarker 2.1 之前的工作方式不同，后者始终是绝对路径。若要保留旧的行为，请在Configuration对象中启用经典兼容模式。

始终使用/(斜杠)分隔路径组成部分，切勿使用\(反斜杠)分隔。即使您是从本地文件系统加载模板并且它使用反斜杠(例如 Windows 下)，也请使用/。

Example:

假设/common/copyright.ftl 包含：

Copyright 2001-2002 ${me}<br>
All rights reserved.

Then this:

<#assign me = "Juila Smith">
<h1>Some test</h1>
<p>Yeah.
<hr>
<#include "/common/copyright.ftl">

将输出以下内容：

<h1>Some test</h1>
<p>Yeah.
<hr>
Copyright 2001-2002 Juila Smith
All rights reserved.

受支持的options是：

Note:

如果ignore_missing是true，但缺少模板时include指令失败并显示“模板包含失败”错误，这通常是因为您的应用程序使用自定义freemarker.cache.TemplateLoader实现，该实现错误地(针对 API 文档)在findTemplateSource方法中抛出了IOException如果找不到模板，则返回null。如果是这样，则 Java 程序员需要修复该问题。当然，另一种可能性是，由于某些技术问题，确实无法确定模板是否存在，在这种情况下，错误停止是正确的行为。请参阅 Java 堆栈跟踪中的原因IOException以确定是哪种情况。

Example:

<#include "/common/navbar.html" parse=false encoding="Shift_JIS">

请注意，可以使用Configuration的“自动包含”设置来自动执行所有模板的常用包含。

Using acquisition

有一个特殊的路径组件，由星号(*)表示。它被解释为“此目录或其任何父目录”。因此，如果位于/foo/bar/template.ftl的模板具有以下行：

<#include "*/footer.ftl">

然后引擎将在以下位置按以下 Sequences 查找模板：

这种机制称为“获取”，使设计人员可以将通常包含的文件放在父目录中，并根据需要在每个子目录的基础上重新定义它们。我们说 include 模板从拥有它的第一个父目录中获取要包含的模板。请注意，您不仅可以在星号右侧指定模板名称，还可以指定子路径。即如果以前的模板改为：

<#include "*/commons/footer.ftl">

那么引擎将在以下位置按以下 Sequences 查找模板：

最后，星号不必是路径的第一个元素：

<#include "commons/*/footer.ftl">

会导致引擎按以下 Sequences 在以下位置查找模板：

但是，路径中最多可以有一个星号。如果指定更多星号，将找不到该模板。

Localized lookup

语言环境是一种语言和可选的国家/地区或方言标识符(可能还包括其他变体标识符，例如“ MAC”)。每当请求模板时，总是(显式或隐式)指定所需的语言环境，FreeMarke 将尝试查找与该语言环境匹配的模板变体。当模板包含或导入另一个模板时，在内部也会要求一个语言环境，设置locale设置的语言环境(通常是顶层模板的语言环境)。

假设您的模板加载了语言环境en_US，这表示美国英语。当您包含另一个模板时：

<#include "footer.ftl">

实际上，引擎将按以下 Sequences 查找几个模板：

它将使用存在的第一个。

请注意，FreeMarker 如何(以及是否)搜索本地化版本是可以由程序员配置的，因此我们仅在此处描述默认行为。您可以使用localized_lookup设置(Configuration.setLocalizedLookup(boolean))禁用本地化查找。另外，您可以使用template_lookup_strategy设置(Configuration.setTemplateLookupStrategy(TemplateLookupStrategy))定义自己的推导模板名称序列。

当您同时使用获取(即路径中的*步骤)和本地化模板查找时，父目录中具有特定区域设置的模板优先于子目录中具有特定区域设置的模板。假设您使用来自/foo/bar/template.ftl的以下包含：

<#include "*/footer.ftl">

引擎将按以下 Sequences 查找这些模板：

为什么应使用导入而不是包含

通常，使用导入指令比使用include更好。

乍一看，仅当您拥有一组常用的宏，函数和其他变量并将它们放入模板中以供重用时，导入才合适。但是，人们经常使用include将常见的输出片段(例如页面页脚)插入多个模板。 import指令没有输出，因此显然不是直接替代。但是，将这些输出片段放入宏通常是更好的做法，因为宏可以具有参数，甚至可以嵌套内容。如果执行此操作，则模板中将包含一组宏，您可以import。

因此，如果模板中包含宏，函数和其他变量的集合，这就是为什么import通常是更好的选择的原因：

上一章 首页 下一章