| <!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>import - Apache 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="Apache FreeMarker Manual"> |
| <meta property="og:title" content="import"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/ref_directive_import.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/ref_directive_import.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs"> |
| <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">Apache 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">Template Language 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_import.html"><span itemprop="name">import</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</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 = ["Apache FreeMarker Manual","Template Language Reference","Directive Reference","import"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></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_if.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_include.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="ref_directive_import" itemprop="headline">import</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_98" data-menu-target="autoid_98">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_99" data-menu-target="autoid_99">Description</a></li></ul> </div><a name="ref.directive.import"></a> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_98">Synopsis</h2> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><#import <em class="code-color">path</em> as <em class="code-color">hash</em>></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">path</em></code>: The |
| path of a template. This is 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">hash</em></code>: The |
| unquoted name of hash variable by which you can access the |
| namespace. Not an expression. (If you have to import into a |
| dynamically constructed name, you have to use <a href="app_faq.html#faq_assign_to_dynamic_variable_name">this |
| trick</a>.) |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_99">Description</h2> |
| |
| |
| <p>Used for making a collection of macros, functions, and other |
| variables available for the importing template, which were defined |
| in the imported template. For example, let's say you have written |
| macros to generate some commonly needed pieces output, and you have |
| put them into <code class="inline-code">/libs/commons.ftl</code>. Then, in the |
| template where you want to use them, do this (near the top of the |
| the template by convention, next to any other |
| <code class="inline-code">import</code>-s):</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#import "/libs/commons.ftl" as com></pre> </div> |
| |
| |
| <p>Later in same template, let's say you want to use the |
| <code class="inline-code">copyright</code> macro defined in |
| <code class="inline-code">/libs/commons.ftl</code>. Then you can call that macro |
| like this:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><@com.copyright date="1999-2002"/></pre> </div> |
| |
| |
| <p>Note the <code class="inline-code">com.</code> before the macro name above. |
| All that was defined in <code class="inline-code">/libs/commons.ftl</code> will be |
| inside <code class="inline-code">com</code>.</p> |
| |
| <p>Described more technically, <code class="inline-code">import</code> first |
| creates a new empty <a href="dgui_misc_namespace.html">namespace</a>, and then executes |
| the template given with |
| <code class="inline-code"><em class="code-color">path</em></code> parameter inside |
| that namespace, so the template populates the namespace with |
| variables (macros, functions, ...etc.). Then the namespace is |
| assigned to the variable specified with the |
| <code class="inline-code"><em class="code-color">hash</em></code> parameter, and |
| you can access its contents through that. A namespace is <a href="dgui_datamodel_types.html#dgui_datamodel_container">a hash</a>, hence <a href="dgui_template_exp.html#dgui_template_exp_var_hash">the dot operator</a> worked |
| above. The assignment is like the <code class="inline-code">assign</code> |
| directive, that is, it sets the variable in the current namespace. |
| Except, if the import happens in the namespace of the main (topmost) |
| template, the hash variable is also created in the global |
| namespace.</p> |
| |
| <p>If you call <code class="inline-code">import</code> with the same |
| <code class="inline-code"><em class="code-color">path</em></code> for multiple |
| times, it will create the namespace and run the template for the |
| first call of <code class="inline-code">import</code> only. The later calls will |
| just give back the namespace that was created and initialized when |
| the template was imported for the first time, and will not execute |
| the imported template.</p> |
| |
| <p>Any output printed by the imported template will be ignored |
| (will not be inserted at the place of <code class="inline-code">import</code> |
| directive invocation). An imported template is executed to populate |
| its namespace with variables, and not to write to the output.</p> |
| |
| <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 configuring FreeMarker.</p> |
| |
| <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 do the necessary |
| conversions automatically.</p> |
| |
| <p>Like with the <code class="inline-code">include</code> directive, <a href="ref_directive_include.html#ref_directive_include_acquisition">acquisition</a> and |
| <a href="ref_directive_include.html#ref_directive_include_localized">localized |
| lookup</a> may be used for resolving the path.</p> |
| |
| <p><span class="marked-for-programmers">Note that it's possible to |
| automatically do the commonly used imports for all templates, with |
| the "auto imports" setting of <code class="inline-code">Configuration</code>. |
| Because templates may not use all the automatically imported |
| namespaces, it's also possible to make imports lazy (on demand), |
| with the "lazy auto imports" setting of |
| <code class="inline-code">Configuration</code>.</span></p> |
| |
| <p>If you are new to namespaces, you should read: <a href="dgui_misc_namespace.html">Template Author's Guide/Miscellaneous/Namespaces</a></p> |
| |
| <p>In case you are not sure if you should use the |
| <code class="inline-code">import</code>, or the somewhat similar |
| <code class="inline-code">include</code> directive, <a href="ref_directive_include.html#topic.import_vs_include">then see this</a>.</p> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_if.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_include.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 class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><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="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
