| <!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>Defining variables in the template - 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="Defining variables in the template"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/dgui_misc_var.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/dgui_misc_var.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="dgui.html"><span itemprop="name">Template Author's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_misc_var.html"><span itemprop="name">Defining variables in the template</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 Author\'s Guide","Miscellaneous","Defining variables in the template"];</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="dgui_misc_userdefdir.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_namespace.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="dgui_misc_var" itemprop="headline">Defining variables in the template</h1> |
| </div></div><p>Most of the variables that a typical template works with comes |
| from the data-model. But templates can also define variables |
| themselves, usually to hold loops variables, temporary results, |
| macros, etc. Such variables are outside the data-model; modifying the |
| data-model from templates is by design unsupported. Note that each |
| <a href="gloss.html#gloss.templateProcessingJob">template processing |
| job</a> has its own private set of these variables, which will be |
| thrown away when the template processing job is finished.</p><p>You access variables defined in the template the same way as you |
| access variables defined in the data-model root. For example, if you |
| create a variable called "foo" in the template, you can |
| print its value with <code class="inline-code">${foo}</code>. If, coincidently, |
| there's a variable called "foo" in the data-model too, |
| the variable created in the template will hide (not overwrite!) |
| it.</p><p>There are these kinds of variables that are defined in a |
| template:</p><ul> |
| <li> |
| <p><strong>"plain" |
| variables</strong>: They are accessible from everywhere in the |
| template, or from another templates that was inserted with the |
| <a href="ref_directive_include.html#ref.directive.include"><code>include</code> |
| directive</a>. You can create and replace these variables with |
| the <a href="ref_directive_assign.html#ref.directive.assign"><a href="ref_directive_assign.html#ref.directive.assign"><code>assign</code></a> |
| directive</a>, or, because macros and functions are just |
| variables, with the <a href="ref_directive_macro.html#ref.directive.macro"><code>macro</code> |
| directives</a> and <a href="ref_directive_function.html#ref.directive.function"><code>function</code> |
| directives</a>.</p> |
| </li> |
| |
| <li> |
| <p><strong>Local variables</strong>: They can |
| only be set inside a <a href="gloss.html#gloss.macroDefinitionBody">macro definition body</a> |
| or <a href="gloss.html#gloss.functionDefinitionBody">function |
| definition body</a>, and are only visible from there, not from |
| other macros or functions called from there. A local variable only |
| exists for the duration of a macro or function call. You can |
| create and replace local variables inside the definition body with |
| the <a href="ref_directive_local.html#ref.directive.local"><code>local</code> |
| directive</a>. <a href="ref_directive_macro.html#ref.directive.macro">Macro</a> |
| and <a href="ref_directive_function.html#ref.directive.function">function</a> |
| parameters are also local variables.</p> |
| </li> |
| |
| <li> |
| <p><strong>Loop variables</strong>: Loop |
| variables are created automatically by directives like <a href="ref_directive_list.html#ref.directive.list"><code>list</code></a> (like |
| <code class="inline-code">x</code> in <code class="inline-code"><#list xs as |
| x><em class="code-color">...</em></#list></code>), and |
| they only exist between the start-tag and end-tag of the |
| directive. (User defined directives, like macros, can also create |
| loop variables.) They are only visible directly between these |
| tags, not from macros or functions called from there. As such, |
| they are quite similar to local variables, but they can't be |
| assigned to directly.</p> |
| </li> |
| |
| <li> |
| <p><strong>Global variables</strong>: These |
| should be seldom used. Global variables are shared by all |
| templates, even if they belong to different name spaces because of |
| <a href="ref_directive_import.html#ref.directive.import"><code>import</code>-ing</a>. |
| Thus, their visibility is similar to data-model variables. They |
| are set via the <a href="ref_directive_global.html#ref.directive.global"><code>global</code> |
| directive</a>. Global variables hide (but don't overwrite) the |
| data-model variables of the same name.</p> |
| </li> |
| </ul><p>Example: Create and replace variables with |
| <code class="inline-code">assign</code>:</p> |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x = 1> <#-- create variable x --> |
| ${x} |
| <#assign x = 2> <#-- replace variable x --> |
| ${x} |
| <#assign x++> <#-- replace variable x --> |
| ${x}</pre> </div> |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">1 |
| 2 |
| 3</pre> </div> |
| <p>In the next example we demonstrate that local variables hide |
| (not overwrite) "plain" variables of the same name, and |
| that loop variables hide (not overwrite) local and |
| "plain" variables of the same name:</p> |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x = "plain"> |
| 1. ${x} <#-- we see the plain var. here --> |
| <@test/> |
| 6. ${x} <#-- the value of plain var. was not changed --> |
| <#list ["loop"] as x> |
| 7. ${x} <#-- now the loop var. hides the plain var. --> |
| <#assign x = "plain2"> <#-- replaces the plain var, not the loop var. --> |
| 8. ${x} <#-- it still hides the plain var. --> |
| </#list> |
| 9. ${x} <#-- now the new value of plain var. becomse visible --> |
| |
| <#macro test> |
| 2. ${x} <#-- we still see the plain var. here --> |
| <#local x = "local"> |
| 3. ${x} <#-- now the local var. hides it --> |
| <#list ["loop"] as x> |
| 4. ${x} <#-- now the loop var. hides the local var. --> |
| </#list> |
| 5. ${x} <#-- now we see the local var. again --> |
| </#macro></pre> </div> |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">1. plain |
| 2. plain |
| 3. local |
| 4. loop |
| 5. local |
| 6. plain |
| 7. loop |
| 8. loop |
| 9. plain2 </pre> </div> |
| <p>In the next example we demonstrate that an inner loop variable |
| can hide (not overwrite) an outer loop variable of the same |
| name:</p> |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#list ["loop 1"] as x> |
| ${x} |
| <#list ["loop 2"] as x> |
| ${x} |
| <#list ["loop 3"] as x> |
| ${x} |
| </#list> |
| ${x} |
| </#list> |
| ${x} |
| </#list></pre> </div> |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body"> loop 1 |
| loop 2 |
| loop 3 |
| loop 2 |
| loop 1</pre> </div> |
| <p>When a variable hides the variable from the data-model, you can |
| still read that variable from the data-model using <a href="dgui_template_exp.html#dgui_template_exp_var_special">special variable</a> |
| <code class="inline-code">globals</code>. For example, assume we have a variable |
| called <code class="inline-code">user</code> in the data-model with value "Big |
| Joe":</p> |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">${user} <#-- prints: Big Joe --> |
| <#assign user = "Joe Hider"> |
| ${user} <#-- prints: Joe Hider --> |
| ${.globals.user} <#-- prints: Big Joe --></pre> </div> |
| <p>You could also write <code class="inline-code">.data_model.user</code> |
| instead, and then not even a <code class="inline-code"><#global user = |
| "<em class="code-color">...</em>"></code> can hide the value in |
| the data-model. However, global variables are often purposely set to |
| override the value coming from the data-model, so using |
| <code class="inline-code">globals</code> is a better practice usually.</p><p>For information about syntax of variables (allowed characters |
| and such) please read: <a href="dgui_template_exp.html">The Template/Expressions</a></p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_misc_userdefdir.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_namespace.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> |
