| <!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>assign - 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="assign"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/ref_directive_assign.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/ref_directive_assign.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_assign.html"><span itemprop="name">assign</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","assign"];</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_alphaidx.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_attempt.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="ref_directive_assign" itemprop="headline">assign</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_78" data-menu-target="autoid_78">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_79" data-menu-target="autoid_79">Description</a></li></ul> </div><a name="ref.directive.assign"></a> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_78">Synopsis</h2> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><#assign <em class="code-color">name1</em>=<em class="code-color">value1</em> <em class="code-color">name2</em>=<em class="code-color">value2</em> <em class="code-color">... nameN</em>=<em class="code-color">valueN</em>></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">same as above...</em> in <em class="code-color">namespacehash</em>></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">name</em>> |
| <em class="code-color">capture this</em> |
| </#assign></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">name</em> in <em class="code-color">namespacehash</em>> |
| <em class="code-color">capture this</em> |
| </#assign></code></pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of the variable. It is not expression. However, it can be |
| written as a string literal, which is useful if the variable |
| name contains reserved characters, for example |
| <code class="inline-code"><#assign "foo-bar" = 1></code>. Note that this |
| string literal does not expand interpolations (as |
| <code class="inline-code">"${foo}"</code>); if you need to assign to a |
| dynamically constructed name, the you have to use <a href="app_faq.html#faq_assign_to_dynamic_variable_name">a different |
| trick</a>. Note that because the FreeMarker template language |
| assumes that sequences (lists, arrays, etc.) and hashes (maps, |
| beans, etc.) are immutable, you can <em>not</em> |
| write something like <code class="inline-code"><#assign myObj.someProperty = |
| 'will NOT work'></code> or <code class="inline-code"><#assign myList[0] |
| = 'will NOT work'></code>. However, adding sequences or |
| hashes with the <code class="inline-code">+</code> operator to form another |
| value is supported; see in the <a href="dgui_template_exp.html#exp_cheatsheet">chapter about expressions</a>, and |
| please note the performance consequences. |
| </li> |
| |
| <li> |
| <code class="inline-code">=</code>: Assignment operator. It can also be |
| one of the assignment shorthand operators (since FreeMarker |
| 2.3.23): <code class="inline-code">++</code>, <code class="inline-code">--</code>, |
| <code class="inline-code">+=</code>, <code class="inline-code">-=</code>, |
| <code class="inline-code">*=</code>, <code class="inline-code">/=</code> or |
| <code class="inline-code">%=</code>. Like <code class="inline-code"><#assign |
| x++></code> is similar to <code class="inline-code"><#assign x = x + |
| 1></code>, and <code class="inline-code"><#assign x += 2></code> |
| is the same as <code class="inline-code"><#assign x = x + 2></code>. |
| Note that <code class="inline-code">++</code> always means arithmetical |
| addition (an so it will fail on non-numbers), unlike |
| <code class="inline-code">+</code> or <code class="inline-code">+=</code> that are |
| overloaded to do string concatenation and such. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value</em></code>: the |
| value to store. Expression. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">namespacehash</em></code>: |
| a hash that was created for a <a href="dgui_misc_namespace.html">namespace</a> (by <a href="ref_directive_import.html#ref.directive.import"><code>import</code></a>). |
| Expression. If not specified, it defaults to the namespace that |
| belongs to the containing template. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_79">Description</h2> |
| |
| |
| <p>With this you can create a new variable, or replace an |
| existing variable. Note that only top-level variables can be |
| created/replaced (i.e. you can't create/replace |
| <code class="inline-code">some_hash.subvar</code>, but |
| <code class="inline-code">some_hash</code>).</p> |
| |
| <p>For more information about variables, read this: <a href="dgui_misc_var.html">Template Author's Guide/Miscellaneous/Defining variables in the template</a></p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>A frequent mistake is trying to use |
| <code class="inline-code">assign</code> to change a local variable like: |
| <code class="inline-code"><#macro m><#local x = 1>${x}<#assign x = |
| 2>${x}</#macro></code>. This prints |
| <code class="inline-code">11</code>, not <code class="inline-code">12</code>, because |
| <code class="inline-code">assign</code> creates/replaces the |
| <code class="inline-code">x</code> of the namespace that the template belongs |
| to, and doesn't change the <code class="inline-code">x</code> local variable. |
| Local variables should be always set with the <a href="ref_directive_local.html#ref.directive.local"><code>local</code> |
| directive</a>, not just for the fist time.</p> |
| </div> |
| |
| |
| <p>Example: variable <code class="inline-code">seq</code> will store a |
| sequence:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign seq = ["foo", "bar", "baz"]></pre> </div> |
| |
| |
| <p>Example: Increments the numerical value stored in variable |
| <code class="inline-code">x</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x++></pre> </div> |
| |
| |
| <p>As a convenience feature, you can do more assignments with one |
| <code class="inline-code">assign</code> tag. For example this will do the same as |
| the two previous examples:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign |
| seq = ["foo", "bar", "baz"] |
| x++ |
| ></pre> </div> |
| |
| |
| <p>If you know what namespaces are: <code class="inline-code">assign</code> |
| directive creates variables in a namespace. Normally it creates the |
| variable in the current namespace (i.e. in the namespace associated |
| with the template where the tag is). However, if you use <code class="inline-code">in |
| <em class="code-color">namespacehash</em></code> then you can |
| create/replace a variable of another <a href="dgui_misc_namespace.html">namespace</a> than the current |
| namespace. For example, here you create/replace variable |
| <code class="inline-code">bgColor</code> of the namespace used for |
| <code class="inline-code">/mylib.ftl</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#import "/mylib.ftl" as my> |
| <#assign bgColor="red" in my></pre> </div> |
| |
| |
| <p>An extreme usage of <code class="inline-code">assign</code> is when it |
| captures the output generated between its start-tag and end-tag. |
| That is, things that are printed between the tags will not be shown |
| on the page, but will be stored in the variable. For example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro myMacro>foo</#macro> |
| <#assign x> |
| <#list 1..3 as n> |
| ${n} <@myMacro /> |
| </#list> |
| </#assign> |
| Number of words: ${x?word_list?size} |
| ${x}</pre> </div> |
| |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">Number of words: 6 |
| 1 foo |
| 2 foo |
| 3 foo |
| </pre> </div> |
| |
| |
| <p>Please note that you should not to use this to insert |
| variables into strings:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x>Hello ${user}!</#assign> <#-- BAD PRACTICE! --></pre> </div> |
| |
| |
| <p>You should simply write:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x="Hello ${user}!"></pre> </div> |
| |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_alphaidx.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_attempt.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> |
