| <!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?1594338519184"> |
| </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><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["FreeMarker Manual","Reference","Directive Reference","include"];</script> |
| <script src="toc.js?1594338519184"></script> |
| <script src="docgen-resources/main.min.js?1594338519184"></script> |
| </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"><#include <em class="code-color">path</em>></code> |
| or |
| <code class="inline-code"><#include <em class="code-color">path</em> <em class="code-color">options</em>></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't have to be a fixed string, |
| it can also be something like, for example, |
| <code class="inline-code">profile.baseDir + "/menu.ftl"</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't involve the Servlet container at all, just |
| processes another FreeMarker template, without "leaving" |
| FreeMarker. Regarding how to do a "JSP include" <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">"foo.ftl"</code> |
| and <code class="inline-code">"../foo.ftl"</code>, or an absolute like |
| <code class="inline-code">"/foo.ftl"</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 ''root directory of the templates'') 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}<br> |
| All rights reserved.</pre></div> |
| |
| <p>Then this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign me = "Juila Smith"> |
| <h1>Some test</h1> |
| <p>Yeah. |
| <hr> |
| <strong><#include "/common/copyright.ftl"></strong></pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><h1>Some test</h1> |
| <p>Yeah. |
| <hr> |
| <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"><#include "/common/navbar.html" parse=false encoding="Shift_JIS"></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 "auto includes" 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's a special path component represented by an asterisk |
| (<code class="inline-code">*</code>). It is interpreted as "this directory or |
| any of its parents". 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"><#include "*/footer.ftl"></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"><#include "*/commons/footer.ftl"></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't be the first element of the |
| path:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#include "commons/*/footer.ftl"></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"><include "footer.ftl"></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"><#include "*/footer.ftl"></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-top"><div class="col-left sitemap"></div><div class="col-right"><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2020-07-09T23:48:39Z" title="Thursday, July 9, 2020 11:48:39 PM GMT">2020-07-09 23:48:39 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> |