Google Git
Sign in
apache / freemarker-docgen / f6eb79676240e0fa3a9154cdb825da28220fc9b9 / . / legacy-tests / build / test / 4 / ref_directive_include.html
blob: ac8d278dd1e315a62a192a4019f4262a7a9033f5 [file] [log] [blame]
<!doctype html>
<!-- Generated by FreeMarker/Docgen from DocBook -->
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>include - FreeMarker Manual</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker Manual">
<meta property="og:title" content="include">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/ref_directive_include.html">
<link rel="canonical" href="http://example.com/ref_directive_include.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338517553">
</head>
<body itemscope itemtype="https://schema.org/Code">
<meta itemprop="url" content="http://example.com/">
<meta itemprop="name" content="FreeMarker Manual">
<!--[if lte IE 9]>
<div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
<![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo">
</a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">Directive Reference</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_include.html"><span itemprop="name">include</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li></ul></div></div></div> <div class="main-content site-width">
<div class="content-wrapper no-toc">
<div id="table-of-contents-wrapper" class="col-left">
</div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_directive_list.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_import.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="ref_directive_include" itemprop="headline">include</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_84" data-menu-target="autoid_84">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_85" data-menu-target="autoid_85">Description</a><ul><li><a class="page-menu-link" href="#ref_directive_include_acquisition" data-menu-target="ref_directive_include_acquisition">Using acquisition</a></li><li><a class="page-menu-link" href="#ref_directive_include_localized" data-menu-target="ref_directive_include_localized">Localized lookup</a></li></ul></li></ul> </div><a name="ref.directive.include"></a>
<h2 class="content-header header-section2" id="autoid_84">Synopsis</h2>
<pre class="metaTemplate">
<code class="inline-code">&lt;#include <em class="code-color">path</em>&gt;</code>
or
<code class="inline-code">&lt;#include <em class="code-color">path</em> <em class="code-color">options</em>&gt;</code>
</pre>
<p>Where:</p>
<ul>
<li>
<code class="inline-code"><em class="code-color">path</em></code>: The
path of the file to include; an expression that evaluates to a
string. (With other words, it doesn&#39;t have to be a fixed string,
it can also be something like, for example,
<code class="inline-code">profile.baseDir + &quot;/menu.ftl&quot;</code>.)
</li>
<li>
<code class="inline-code"><em class="code-color">options</em></code>: One
or more of these:
<code class="inline-code">encoding=<em class="code-color">encoding</em></code>,
<code class="inline-code">parse=<em class="code-color">parse</em></code>
<ul>
<li>
<code class="inline-code"><em class="code-color">encoding</em></code>:
Expression evaluates to string
</li>
<li>
<code class="inline-code"><em class="code-color">parse</em></code>:
Expression evaluates to boolean (also accepts a few string
values for backward compatibility)
</li>
</ul>
</li>
</ul>
<h2 class="content-header header-section2" id="autoid_85">Description</h2>
<p>You can use it to insert another FreeMarker template file
(specified by the <code class="inline-code"><em class="code-color">path</em></code>
parameter) into your template. The output from the included template
is inserted at the point where the <code class="inline-code">include</code> tag
occurs. The included file shares the variables with the including
template, similarly like if it was copy-pased into it. The
<code class="inline-code">include</code> directive is not replaced by the content
of the included file, it just processes the included file each time
when FreeMarker reaches the <code class="inline-code">include</code> directive in
the course of template processing. So for example if the
<code class="inline-code">include</code> is inside a <code class="inline-code">list</code>loop,
you can specify different file names in each cycle.</p>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This directive is not be confused with the JSP (Servlet)
include, as it doesn&#39;t involve the Servlet container at all, just
processes another FreeMarker template, without &quot;leaving&quot;
FreeMarker. Regarding how to do a &quot;JSP include&quot; <a href="app_faq.html#faq_servlet_include">read this...</a></p>
</div>
<p>The <code class="inline-code"><em class="code-color">path</em></code>
parameter can be a relative path like <code class="inline-code">&quot;foo.ftl&quot;</code>
and <code class="inline-code">&quot;../foo.ftl&quot;</code>, or an absolute like
<code class="inline-code">&quot;/foo.ftl&quot;</code>. Relative paths are relative to the
directory of the template that uses the <code class="inline-code">import</code>
directive. Absolute paths are relative to a base (often referred as
the &#39;&#39;root directory of the templates&#39;&#39;) that the programmer defines
when he configures FreeMarker.</p>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>This is different than the way it worked prior FreeMarker
2.1, where the path was always absolute. To preserve the old
behavior, enable the classic compatible mode in the
<code class="inline-code">Configuration</code> object.</p>
</div>
<p>Always use <code class="inline-code">/</code> (slash) to separate path
components, never <code class="inline-code">\</code> (backslash). If you are
loading templates from your local file system and it uses
backslashes (like under. Windows), FreeMarker will convert them
automatically.</p>
<p>Example:</p>
<p>Assume /common/copyright.ftl contains:</p>
<div class="code-wrapper"><pre class="code-block code-template">Copyright 2001-2002 ${me}&lt;br&gt;
All rights reserved.</pre></div>
<p>Then this:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign me = &quot;Juila Smith&quot;&gt;
&lt;h1&gt;Some test&lt;/h1&gt;
&lt;p&gt;Yeah.
&lt;hr&gt;
<strong>&lt;#include &quot;/common/copyright.ftl&quot;&gt;</strong></pre></div>
<p>will output this:</p>
<div class="code-wrapper"><pre class="code-block code-output">&lt;h1&gt;Some test&lt;/h1&gt;
&lt;p&gt;Yeah.
&lt;hr&gt;
<strong>Copyright 2001-2002 Juila Smith
All rights reserved.</strong></pre></div>
<p>The supported
<code class="inline-code"><em class="code-color">options</em></code> are:</p>
<ul>
<li>
<p>parse: If it is true, then the included file will be
parsed as FTL, otherwise the whole file will be considered as
simple text (i.e, no FreeMarker constructs will be searched in
it). If you omit this option, then it defaults to true.</p>
</li>
<li>
<p>encoding: The included file inherits the encoding (in
practice: the charset) of the including template, unless you
specify an encoding with this option. <span class="marked-for-programmers">Encoding names are the same as the ones
supported be java.io.InputStreamReader (as of Java API 1.3:
MIME-preferred charset names from the IANA Charset
Registry).</span> Examples of valid names: ISO-8859-2, UTF-8,
Shift_JIS, Big5, EUC-KR, GB2312.</p>
</li>
</ul>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#include &quot;/common/navbar.html&quot; parse=false encoding=&quot;Shift_JIS&quot;&gt;</pre></div>
<p><span class="marked-for-programmers">Note, that it is possible to
automatically do the commonly used inclusions for all templates,
with the &quot;auto includes&quot; setting of
<code class="inline-code">Configuration</code>.</span></p>
<h3 class="content-header header-section3" id="ref_directive_include_acquisition">Using acquisition</h3>
<p>There&#39;s a special path component represented by an asterisk
(<code class="inline-code">*</code>). It is interpreted as &quot;this directory or
any of its parents&quot;. Therefore, if the template located in
<code class="inline-code">/foo/bar/template.ftl</code> has the following
line:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#include &quot;*/footer.ftl&quot;&gt;</pre></div>
<p>then the engine will look for the template in following
locations, in this order:</p>
<ul>
<li>
<code class="inline-code">/foo/bar/footer.ftl</code>
</li>
<li>
<code class="inline-code">/foo/footer.ftl</code>
</li>
<li>
<code class="inline-code">/footer.ftl</code>
</li>
</ul>
<p>This mechanism is called <strong>acquisition</strong> and allows the designers to
place commonly included files in a parent directory, and redefine
them on a per-subdirectory basis as needed. We say that the
including template acquires the template to include from the first
parent directory that has it. Note that you can specify not only a
template name to the right of the asterisk, but a subpath as well.
I.e. if the previous template instead read:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#include &quot;*/commons/footer.ftl&quot;&gt;</pre></div>
<p>then the engine would look for the template in following
locations, in this order:</p>
<ul>
<li>
<code class="inline-code">/foo/bar/commons/footer.ftl</code>
</li>
<li>
<code class="inline-code">/foo/commons/footer.ftl</code>
</li>
<li>
<code class="inline-code">/commons/footer.ftl</code>
</li>
</ul>
<p>Finally, the asterisk needn&#39;t be the first element of the
path:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#include &quot;commons/*/footer.ftl&quot;&gt;</pre></div>
<p>would cause the engine to look for the template in following
locations, in this order:</p>
<ul>
<li>
<code class="inline-code">/foo/bar/commons/footer.ftl</code>
</li>
<li>
<code class="inline-code">/foo/bar/footer.ftl</code>
</li>
<li>
<code class="inline-code">/foo/footer.ftl</code>
</li>
<li>
<code class="inline-code">/footer.ftl</code>
</li>
</ul>
<p>However, there can be at most one asterisk in the path.
Specifying more than one asterisk will result in a template not
being found.</p>
<h3 class="content-header header-section3" id="ref_directive_include_localized">Localized lookup</h3>
<p>Whenever a template is loaded, it is assigned a locale. A
locale is a language and an optional country or dialect
identifier. A template is typically loaded by some code that the
programmer wrote and he chooses a locale for the template based on
some aspect. For example, when the
<code class="inline-code">FreemarkerServlet</code> loads templates, it always
requests the template with locale matching the language preference
of the browser that requested the web page.</p>
<p>Whenever a template is loaded, it is assigned a locale. A
locale is a language and an optional country or dialect
identifier. A template is typically loaded by some code that the
programmer wrote and he chooses a locale for the template based on
some aspect. For example, when the
<code class="inline-code">FreeMarkerServlet</code> loads templates, it always
requests the template with locale matching the language preference
of the browser that requested the web page.</p>
<p>When a template includes another template, it attempts to
load a template with the same locale. Suppose your template was
loaded with locale <code class="inline-code">en_US</code>, which means U.S.
English. When you include another template:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;include &quot;footer.ftl&quot;&gt;</pre></div>
<p>the engine will in fact look for several templates, in this
order:</p>
<ul>
<li>
<code class="inline-code">footer_en_US.ftl</code>,
</li>
<li>
<code class="inline-code">footer_en.ftl</code>, and finally
</li>
<li>
<code class="inline-code">footer.ftl</code>
</li>
</ul>
<p><span class="marked-for-programmers">Note that you can disable
localized lookup feature with the
<code class="inline-code">setLocalizedLookup</code> method of
<code class="inline-code">Configuration</code>.</span></p>
<p>When you use both acquisition and localized template lookup,
the template with more specific locale in a parent directory takes
precedence over template with less specific locale in a child
directory. Suppose you use the following include from
<code class="inline-code">/foo/bar/template.ftl</code>:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#include &quot;*/footer.ftl&quot;&gt;</pre></div>
<p>the engine will look for these templates, in this
order:</p>
<ul>
<li>
<code class="inline-code">/foo/bar/footer_en_US.ftl</code>
</li>
<li>
<code class="inline-code">/foo/footer_en_US.ftl</code>
</li>
<li>
<code class="inline-code">/footer_en_US.ftl</code>
</li>
<li>
<code class="inline-code">/foo/bar/footer_en.ftl</code>
</li>
<li>
<code class="inline-code">/foo/footer_en.ftl</code>
</li>
<li>
<code class="inline-code">/footer_en.ftl</code>
</li>
<li>
<code class="inline-code">/foo/bar/footer.ftl</code>
</li>
<li>
<code class="inline-code">/foo/footer.ftl</code>
</li>
<li>
<code class="inline-code">/footer.ftl</code>
</li>
</ul>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_list.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_import.html"><span>Next</span></a></div></div></div></div> </div>
</div>
<div class="site-footer"><div class="site-width"><div class="footer-bottom"> <p class="last-generated">
Last generated:
<time itemprop="dateModified" datetime="2020-07-09T23:48:37Z" title="Thursday, July 9, 2020 11:48:37 PM GMT">2020-07-09 23:48:37 GMT</time> </p>
<p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2020
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p>
</div></div></div></body>
</html>