docs/dgui_template_valueinsertion.html - freemarker-site - Git at Google

 <!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>Interpolations - 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="Interpolations">
 <meta property="og:locale" content="en_US">
 <meta property="og:url" content="https://freemarker.apache.org/docs/dgui_template_valueinsertion.html">
 <link rel="canonical" href="https://freemarker.apache.org/docs/dgui_template_valueinsertion.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&#39;s Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template.html"><span itemprop="name">The Template</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template_valueinsertion.html"><span itemprop="name">Interpolations</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","The Template","Interpolations"];</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_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.html"><span>Next</span></a></div><div class="title-wrapper">
 <h1 class="content-header header-section1" id="dgui_template_valueinsertion" itemprop="headline">Interpolations</h1>
 </div></div><div class="page-menu">
 <div class="page-menu-title">Page Contents</div>
 <ul><li><a class="page-menu-link" href="#autoid_14" data-menu-target="autoid_14">Overview</a></li><li><a class="page-menu-link" href="#autoid_15" data-menu-target="autoid_15">Automatic escaping</a></li><li><a class="page-menu-link" href="#autoid_16" data-menu-target="autoid_16">Guide to inserting numerical values</a></li><li><a class="page-menu-link" href="#dgui_template_valueinserion_universal_date" data-menu-target="dgui_template_valueinserion_universal_date">Guide to inserting date/time/date-time values</a></li><li><a class="page-menu-link" href="#autoid_17" data-menu-target="autoid_17">Guide to inserting boolean values</a></li><li><a class="page-menu-link" href="#autoid_18" data-menu-target="autoid_18">Exact conversion rules</a></li></ul> </div>


 <h2 class="content-header header-section2" id="autoid_14">Overview</h2>


           <p>The format of interpolations is
           <code class="inline-code">${<em class="code-color">expression</em>}</code>, where
           <code class="inline-code"><em class="code-color">expression</em></code> can be all
           kind of expression (e.g. <code class="inline-code">${100 + x}</code>).</p>

             <div class="callout note">
     <strong class="callout-label">Note:</strong>

             <p>FreeMarker can be configured to use
             <code class="inline-code">[=<em class="code-color">expression</em>]</code> syntax
             instead. <a href="dgui_misc_alternativesyntax.html">See more
             about alternative syntaxes...</a></p>
             </div>


           <p>The interpolation is used to insert the value of the
           <code class="inline-code"><em class="code-color">expression</em></code> converted
           to text (to string). Interpolations can be used only on two places:
           in <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> sections</a> (e.g.,
           <code class="inline-code">&lt;h1&gt;Hello ${name}!&lt;/h1&gt;</code>) and <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">in string literal
           expressions</a> (e.g., <code class="inline-code">&lt;#include
           &quot;/footer/${company}.html&quot;&gt;</code>).</p>

           <p>The result of the expression must be a string, number or
           date/time/date-time value, because (by default) only these types are
           converted to string by interpolation automatically. Values of other
           types (such as booleans, sequences) must be converted to string
           "manually" (see some advices later), or an error will
           stop the template processing.</p>

             <div class="callout warning">
     <strong class="callout-label">Warning!</strong>

             <p>It&#39;s a frequent mistake to use interpolations on places
             where they needn&#39;t/shouldn&#39;t/can&#39;t be used. Interpolations work
             <em>only</em> in <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> sections</a> (e.g.
             <code class="inline-code">&lt;h1&gt;Hello ${name}!&lt;/h1&gt;</code>) and in
             <a href="dgui_template_exp.html#dgui_template_exp_direct_string">string
             literals</a> (e.g. <code class="inline-code">&lt;#include
             &quot;/footer/${company}.html&quot;&gt;</code>). A typical
             <em>WRONG</em> usage is <code class="inline-code">&lt;#if
             ${big}&gt;...&lt;/#if&gt;</code>, which will give syntactical
             error. You should simply write <code class="inline-code">&lt;#if
             big&gt;...&lt;/#if&gt;</code>. Also, <code class="inline-code">&lt;#if
             &quot;${big}&quot;&gt;...&lt;/#if&gt;</code> is
             <em>WRONG</em>, since it converts the parameter value
             to string and the <code class="inline-code">if</code> directive wants a boolean
             value, so it will cause a runtime error.</p>
             </div>


 <h2 class="content-header header-section2" id="autoid_15">Automatic escaping</h2>


           <p>If the interpolation is in a <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> section</a> (not in a <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">string literal
           expression</a>), the text that it inserts goes through
           automatically escaping, <em>if FreeMarker was properly
           configured</em>. <a href="dgui_quickstart_template.html#dgui_quickstart_template_autoescaping">See more about
           escaping here...</a>.</p>


 <h2 class="content-header header-section2" id="autoid_16">Guide to inserting numerical values</h2>


           <p>If the expression evaluates to a number then the numerical
           value will be converted to string according the default number
           format. This may includes the maximum number of decimals, grouping,
           and like. Usually the programmer should set the default number
           format; the template author doesn&#39;t have to deal with it (but he can
           with the <code class="inline-code">number_format</code> setting; see in the <a href="ref_directive_setting.html">documentation of
           <code>setting</code> directive</a>). Also, you can override
           the default number format for a single interpolation with the <a href="ref_builtins_number.html#ref_builtin_string_for_number"><code>string</code>
           built-in</a>.</p>

           <p>The decimal separator used (and other such symbols, like the
           group separator) depends on the current locale (language, country),
           that also should be set by the programmer. For example, this
           template:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">${1.5}</pre>    </div>


           <p>will print something like this if the current locale is
           English:</p>


     <div class="code-block role-output">
 <div class="code-block-label">Output</div><pre class="code-block-body">1.5</pre>    </div>


           <p>but if the current locale is German then it will print
           something like:</p>


     <div class="code-block role-output">
 <div class="code-block-label">Output</div><pre class="code-block-body">1,5</pre>    </div>


           <p>since German people use comma as decimal separator.</p>

             <div class="callout warning">
     <strong class="callout-label">Warning!</strong>

             <p>When the number you print will be read by some computer
             process, always use the <a href="ref_builtins_number.html#ref_builtin_c"><a href="ref_builtins_number.html#ref_builtin_c"><code>c</code></a>
             built-in</a>, to get rid of any localized, or otherwise fancy
             formatting! Like when you print a database record ID as the part
             of an URL or as an invisible field value in a HTML form, or when
             you print CSS/JavaScript numerical literals. Example:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">&lt;a href=&quot;/shop/productdetails?id=${product.id<strong>?c</strong>}&quot;&gt;Details...&lt;/a&gt;</pre>    </div>


             <p>That <code class="inline-code">?c</code> there formats the number with a
             simple US format, which most computer processes will
             understand.</p>
             </div>


 <h2 class="content-header header-section2" id="dgui_template_valueinserion_universal_date">Guide to inserting date/time/date-time values</h2>


           <p>If the expression evaluates to a date-like value then that
           will be transformed to a text according to a default format. Usually
           the programmer should set the default format; the template author
           doesn&#39;t have to deal with it (but if you care, <a href="ref_directive_setting.html#topic.dateTimeFormatSettings">see the
           <code>date_format</code>, <code>time_format</code> and
           <code>datetime_format</code> settings</a> in the
           documentation of the <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code>
           directive</a>). Also, you can override the default formatting for
           a single interpolation with the <a href="ref_builtins_date.html#ref_builtin_string_for_date"><code>string</code>
           built-in</a>.</p>

             <div class="callout warning">
     <strong class="callout-label">Warning!</strong>

             <p>To display a date-like value as text, FreeMarker must know
             which parts of it are in use, that is, if only the date part
             (year, month, day), or only the time part (hour, minute, second,
             millisecond), or both. Unfortunately, because of the technical
             limitations of Java platform, for some variables it is not
             possible to detect this automatically; ask the programmer if the
             data-model contains such problematic variables. When it&#39;s not
             possible to find out which parts of the date are in use, then you
             must help FreeMarker with the <a href="ref_builtins_date.html#ref_builtin_date_datetype"><code>date</code>,
             <code>time</code> and <code>datetime</code></a>
             built-ins (like <code class="inline-code">${lastUpdated?datetime}</code>), or it
             will stop with error.</p>
             </div>


 <h2 class="content-header header-section2" id="autoid_17">Guide to inserting boolean values</h2>


           <p>By default an attempt to print boolean values with
           interpolation causes an error and aborts template processing. For
           example this will cause an error: <code class="inline-code">${a == 2}</code> and
           will not print &#39;&#39;true&#39;&#39; or something like that. That&#39;s because
           there&#39;s no universally useful way of representing booleans
           (sometimes you want to print yes/no, sometimes enabled/disabled,
           on/off, etc.).</p>

           <p>However, you can convert booleans to strings with the <a href="ref_builtins_boolean.html#ref_builtin_string_for_boolean"><code>?string</code>
           built-in</a>. For example, to print the value of the &quot;married&quot;
           variable (assuming it&#39;s a boolean), you could write
           <code class="inline-code">${married?string(&quot;yes&quot;, &quot;no&quot;)}</code>.</p>

           <p>FreeMarker can be configured with a default boolean format
           with the <code class="inline-code">boolean_format</code> setting, then
           <code class="inline-code">${married}</code> and such will work. However, in most
           applications it&#39;s not recommended, as boolean should be rendered
           differently on different places, and leaving the formatting on the
           default is possibly just an oversight and thus should generate
           error.</p>

           <p>When you want to generate JavaScript or other computer
           language parts, then
           <code class="inline-code">${<em class="code-color">someBoolean</em>?c}</code>
           ("c" stands for computer audience) should be used to
           print true/false. (Remember that <code class="inline-code">?c</code> was also used
           to print numbers for computer audience.)</p>


 <h2 class="content-header header-section2" id="autoid_18">Exact conversion rules</h2>


           <p>For those who are interested, the exact rules of conversion
           from the expression value to string (which is then still subject to
           escaping) are these, in this order:</p>

           <div class="orderedlist"><ol type="1">
             <li>
               <p>If the value is a number, then it is converted to string
               in the format specified with the
               <code class="inline-code">number_format</code> setting. So this usually
               formats for human audience, as opposed to computer
               audience.</p>
             </li>

             <li>
               <p>Else if the value is date, time or date-time, then it is
               converted to string in the format specified with the
               <code class="inline-code">date_format</code>, <code class="inline-code">time_format</code>
               or <code class="inline-code">datetime_format</code> setting, respectively. If
               it can&#39;t be detected what kind of date-like value it is (date vs
               time vs date-time), an error will occur.</p>
             </li>

             <li>
               <p>Else if the value is a string, then there is no
               conversion.</p>
             </li>

             <li>
               <p>Else if the engine is in classic compatibility
               mode:</p>

               <div class="orderedlist"><ol type="1">
                 <li>
                   <p>If the value is a boolean, true values are converted
                   to &quot;true&quot;, false values are converted to an empty
                   string.</p>
                 </li>

                 <li>
                   <p>If the expression is undefined
                   (<code class="inline-code">null</code> or a variable is undefined), it is
                   converted to an empty string.</p>
                 </li>

                 <li>
                   <p>Else an error will abort the template
                   processing.</p>
                 </li>
               </ol></div>
             </li>

             <li>
               <p>Else an error will abort the template processing.</p>
             </li>
           </ol></div>
         <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.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>
	<!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>Interpolations - 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="Interpolations">
	<meta property="og:locale" content="en_US">
	<meta property="og:url" content="https://freemarker.apache.org/docs/dgui_template_valueinsertion.html">
	<link rel="canonical" href="https://freemarker.apache.org/docs/dgui_template_valueinsertion.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_template.html"><span itemprop="name">The Template</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template_valueinsertion.html"><span itemprop="name">Interpolations</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","The Template","Interpolations"];</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_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.html"><span>Next</span></a></div><div class="title-wrapper">
	<h1 class="content-header header-section1" id="dgui_template_valueinsertion" itemprop="headline">Interpolations</h1>
	</div></div><div class="page-menu">
	<div class="page-menu-title">Page Contents</div>
	<ul><li><a class="page-menu-link" href="#autoid_14" data-menu-target="autoid_14">Overview</a></li><li><a class="page-menu-link" href="#autoid_15" data-menu-target="autoid_15">Automatic escaping</a></li><li><a class="page-menu-link" href="#autoid_16" data-menu-target="autoid_16">Guide to inserting numerical values</a></li><li><a class="page-menu-link" href="#dgui_template_valueinserion_universal_date" data-menu-target="dgui_template_valueinserion_universal_date">Guide to inserting date/time/date-time values</a></li><li><a class="page-menu-link" href="#autoid_17" data-menu-target="autoid_17">Guide to inserting boolean values</a></li><li><a class="page-menu-link" href="#autoid_18" data-menu-target="autoid_18">Exact conversion rules</a></li></ul> </div>




	<h2 class="content-header header-section2" id="autoid_14">Overview</h2>


	<p>The format of interpolations is
	<code class="inline-code">${<em class="code-color">expression</em>}</code>, where
	<code class="inline-code"><em class="code-color">expression</em></code> can be all
	kind of expression (e.g. <code class="inline-code">${100 + x}</code>).</p>

	<div class="callout note">
	<strong class="callout-label">Note:</strong>

	<p>FreeMarker can be configured to use
	<code class="inline-code">[=<em class="code-color">expression</em>]</code> syntax
	instead. <a href="dgui_misc_alternativesyntax.html">See more
	about alternative syntaxes...</a></p>
	</div>


	<p>The interpolation is used to insert the value of the
	<code class="inline-code"><em class="code-color">expression</em></code> converted
	to text (to string). Interpolations can be used only on two places:
	in <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> sections</a> (e.g.,
	<code class="inline-code"><h1>Hello ${name}!</h1></code>) and <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">in string literal
	expressions</a> (e.g., <code class="inline-code"><#include
	"/footer/${company}.html"></code>).</p>

	<p>The result of the expression must be a string, number or
	date/time/date-time value, because (by default) only these types are
	converted to string by interpolation automatically. Values of other
	types (such as booleans, sequences) must be converted to string
	"manually" (see some advices later), or an error will
	stop the template processing.</p>

	<div class="callout warning">
	<strong class="callout-label">Warning!</strong>

	<p>It's a frequent mistake to use interpolations on places
	where they needn't/shouldn't/can't be used. Interpolations work
	<em>only</em> in <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> sections</a> (e.g.
	<code class="inline-code"><h1>Hello ${name}!</h1></code>) and in
	<a href="dgui_template_exp.html#dgui_template_exp_direct_string">string
	literals</a> (e.g. <code class="inline-code"><#include
	"/footer/${company}.html"></code>). A typical
	<em>WRONG</em> usage is <code class="inline-code"><#if
	${big}>...</#if></code>, which will give syntactical
	error. You should simply write <code class="inline-code"><#if
	big>...</#if></code>. Also, <code class="inline-code"><#if
	"${big}">...</#if></code> is
	<em>WRONG</em>, since it converts the parameter value
	to string and the <code class="inline-code">if</code> directive wants a boolean
	value, so it will cause a runtime error.</p>
	</div>






	<h2 class="content-header header-section2" id="autoid_15">Automatic escaping</h2>


	<p>If the interpolation is in a <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> section</a> (not in a <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">string literal
	expression</a>), the text that it inserts goes through
	automatically escaping, <em>if FreeMarker was properly
	configured</em>. <a href="dgui_quickstart_template.html#dgui_quickstart_template_autoescaping">See more about
	escaping here...</a>.</p>





	<h2 class="content-header header-section2" id="autoid_16">Guide to inserting numerical values</h2>


	<p>If the expression evaluates to a number then the numerical
	value will be converted to string according the default number
	format. This may includes the maximum number of decimals, grouping,
	and like. Usually the programmer should set the default number
	format; the template author doesn't have to deal with it (but he can
	with the <code class="inline-code">number_format</code> setting; see in the <a href="ref_directive_setting.html">documentation of
	<code>setting</code> directive</a>). Also, you can override
	the default number format for a single interpolation with the <a href="ref_builtins_number.html#ref_builtin_string_for_number"><code>string</code>
	built-in</a>.</p>

	<p>The decimal separator used (and other such symbols, like the
	group separator) depends on the current locale (language, country),
	that also should be set by the programmer. For example, this
	template:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body">${1.5}</pre> </div>


	<p>will print something like this if the current locale is
	English:</p>



	<div class="code-block role-output">
	<div class="code-block-label">Output</div><pre class="code-block-body">1.5</pre> </div>


	<p>but if the current locale is German then it will print
	something like:</p>



	<div class="code-block role-output">
	<div class="code-block-label">Output</div><pre class="code-block-body">1,5</pre> </div>


	<p>since German people use comma as decimal separator.</p>

	<div class="callout warning">
	<strong class="callout-label">Warning!</strong>

	<p>When the number you print will be read by some computer
	process, always use the <a href="ref_builtins_number.html#ref_builtin_c"><a href="ref_builtins_number.html#ref_builtin_c"><code>c</code></a>
	built-in</a>, to get rid of any localized, or otherwise fancy
	formatting! Like when you print a database record ID as the part
	of an URL or as an invisible field value in a HTML form, or when
	you print CSS/JavaScript numerical literals. Example:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"><a href="/shop/productdetails?id=${product.id<strong>?c</strong>}">Details...</a></pre> </div>


	<p>That <code class="inline-code">?c</code> there formats the number with a
	simple US format, which most computer processes will
	understand.</p>
	</div>






	<h2 class="content-header header-section2" id="dgui_template_valueinserion_universal_date">Guide to inserting date/time/date-time values</h2>


	<p>If the expression evaluates to a date-like value then that
	will be transformed to a text according to a default format. Usually
	the programmer should set the default format; the template author
	doesn't have to deal with it (but if you care, <a href="ref_directive_setting.html#topic.dateTimeFormatSettings">see the
	<code>date_format</code>, <code>time_format</code> and
	<code>datetime_format</code> settings</a> in the
	documentation of the <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code>
	directive</a>). Also, you can override the default formatting for
	a single interpolation with the <a href="ref_builtins_date.html#ref_builtin_string_for_date"><code>string</code>
	built-in</a>.</p>

	<div class="callout warning">
	<strong class="callout-label">Warning!</strong>

	<p>To display a date-like value as text, FreeMarker must know
	which parts of it are in use, that is, if only the date part
	(year, month, day), or only the time part (hour, minute, second,
	millisecond), or both. Unfortunately, because of the technical
	limitations of Java platform, for some variables it is not
	possible to detect this automatically; ask the programmer if the
	data-model contains such problematic variables. When it's not
	possible to find out which parts of the date are in use, then you
	must help FreeMarker with the <a href="ref_builtins_date.html#ref_builtin_date_datetype"><code>date</code>,
	<code>time</code> and <code>datetime</code></a>
	built-ins (like <code class="inline-code">${lastUpdated?datetime}</code>), or it
	will stop with error.</p>
	</div>






	<h2 class="content-header header-section2" id="autoid_17">Guide to inserting boolean values</h2>


	<p>By default an attempt to print boolean values with
	interpolation causes an error and aborts template processing. For
	example this will cause an error: <code class="inline-code">${a == 2}</code> and
	will not print ''true'' or something like that. That's because
	there's no universally useful way of representing booleans
	(sometimes you want to print yes/no, sometimes enabled/disabled,
	on/off, etc.).</p>

	<p>However, you can convert booleans to strings with the <a href="ref_builtins_boolean.html#ref_builtin_string_for_boolean"><code>?string</code>
	built-in</a>. For example, to print the value of the "married"
	variable (assuming it's a boolean), you could write
	<code class="inline-code">${married?string("yes", "no")}</code>.</p>

	<p>FreeMarker can be configured with a default boolean format
	with the <code class="inline-code">boolean_format</code> setting, then
	<code class="inline-code">${married}</code> and such will work. However, in most
	applications it's not recommended, as boolean should be rendered
	differently on different places, and leaving the formatting on the
	default is possibly just an oversight and thus should generate
	error.</p>

	<p>When you want to generate JavaScript or other computer
	language parts, then
	<code class="inline-code">${<em class="code-color">someBoolean</em>?c}</code>
	("c" stands for computer audience) should be used to
	print true/false. (Remember that <code class="inline-code">?c</code> was also used
	to print numbers for computer audience.)</p>





	<h2 class="content-header header-section2" id="autoid_18">Exact conversion rules</h2>


	<p>For those who are interested, the exact rules of conversion
	from the expression value to string (which is then still subject to
	escaping) are these, in this order:</p>

	<div class="orderedlist"><ol type="1">
	<li>
	<p>If the value is a number, then it is converted to string
	in the format specified with the
	<code class="inline-code">number_format</code> setting. So this usually
	formats for human audience, as opposed to computer
	audience.</p>
	</li>

	<li>
	<p>Else if the value is date, time or date-time, then it is
	converted to string in the format specified with the
	<code class="inline-code">date_format</code>, <code class="inline-code">time_format</code>
	or <code class="inline-code">datetime_format</code> setting, respectively. If
	it can't be detected what kind of date-like value it is (date vs
	time vs date-time), an error will occur.</p>
	</li>

	<li>
	<p>Else if the value is a string, then there is no
	conversion.</p>
	</li>

	<li>
	<p>Else if the engine is in classic compatibility
	mode:</p>

	<div class="orderedlist"><ol type="1">
	<li>
	<p>If the value is a boolean, true values are converted
	to "true", false values are converted to an empty
	string.</p>
	</li>

	<li>
	<p>If the expression is undefined
	(<code class="inline-code">null</code> or a variable is undefined), it is
	converted to an empty string.</p>
	</li>

	<li>
	<p>Else an error will abort the template
	processing.</p>
	</li>
	</ol></div>
	</li>

	<li>
	<p>Else an error will abort the template processing.</p>
	</li>
	</ol></div>
	<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.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>