blob: e5a0fbe94a4acab6763a069ef594ea4f34d5bdd1 [file] [log] [blame]
<!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 - FreeMarker Manual</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker Manual">
<meta property="og:title" content="Interpolations">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/dgui_template_valueinsertion.html">
<link rel="canonical" href="http://example.com/dgui_template_valueinsertion.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338519184">
</head>
<body itemscope itemtype="https://schema.org/Code">
<meta itemprop="url" content="http://example.com/">
<meta itemprop="name" content="FreeMarker Manual">
<!--[if lte IE 9]>
<div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
<![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo">
</a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="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 class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</a></li></ul></div></div></div> <div class="main-content site-width">
<div class="content-wrapper">
<div id="table-of-contents-wrapper" class="col-left">
<script>var breadcrumb = ["FreeMarker Manual","Template Author\'s Guide","The Template","Interpolations"];</script>
<script src="toc.js?1594338519184"></script>
<script src="docgen-resources/main.min.js?1594338519184"></script>
</div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="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><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><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">[#include
&quot;/footer/${company}.html&quot;]</code>).</p> <div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>A frequent mistake is the usage of interpolations in places
where it shouldn&#39;t/can&#39;t be used. A typical bad usage is
<code class="inline-code">[#if ${isBig}]Wow![/#if]</code>, which is syntactically
<em>WRONG</em>. You should simply write <code class="inline-code">[#if
isBig]Wow![/#if]</code>. Also, <code class="inline-code">[#if
&quot;${isBig}&quot;]Wow![/#if]</code> is <em>WRONG</em>, since
the parameter value will be a string, and the <code class="inline-code">if</code>
directive wants a boolean value, so it will cause a runtime
error.</p>
</div>
<p>The result of the expression must be a string, number or date
value. This is because only numbers and dates will be converted to
string by the interpolation automatically, other types of values (such
as booleans, sequences) must be converted to string &quot;manually&quot; somehow
(see some advices later), or an error will stop the template
processing.</p><p>If the interpolation is in a <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> section</a> (i.e., not in a <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">string literal
expression</a>), the string that it will insert will be
automatically escaped if an <a href="ref_directive_escape.html#ref.directive.escape"><code>escape</code>
directive</a> is in effect.</p>
<h2 class="content-header header-simplesect" id="autoid_18">Guide for 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 don&#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>). 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-wrapper"><pre class="code-block code-template">${1.5}</pre></div>
<p>will print something like this if the current locale is
English:</p>
<div class="code-wrapper"><pre class="code-block code-output">1.5</pre></div>
<p>but if the current locale is Hungarian then it will print
something like:</p>
<div class="code-wrapper"><pre class="code-block code-output">1,5</pre></div>
<p>since Hungarian people use comma as decimal separator.</p>
<p>You can modify the formatting for a single interpolation with
the <a href="ref_builtins_number.html#ref_builtin_string_for_number"><code>string</code>
built-in</a>.</p>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>As you can see, interpolations print for human audience (by
default at least), as opposed to &#39;&#39;computer audience&#39;&#39;. In some
cases this is not good, like when you print a database record ID-s
as the part of an URL or as an invisible field value in a HTML
form, or when you print CSS/JavaScript numerical literals, because
these printed values will be read by computer programs and not by
humans. Most computer programs are very particular about the
format of the numbers, and understand only a kind of simple US
number formatting. For that, use the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code></a> (stands for
&#39;&#39;computer audience&#39;&#39;) built-in, for example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;a href=&quot;/shop/productdetails?id=${product.id?c}&quot;&gt;Details...&lt;/a&gt;</pre></div>
</div>
<h2 class="content-header header-simplesect" id="dgui_template_valueinserion_universal_date">Guide for inserting date/time values</h2>
<p>If the expression evaluates to a date then the numerical value
will be transformed to a text according to a default format. Usually
the programmer should set the default format; you don&#39;t have to deal
with it (but if you care, see the <code class="inline-code">date_format</code>,
<code class="inline-code">time_format</code> and
<code class="inline-code">datetime_format</code> settings in the <a href="ref_directive_setting.html">documentation of the
<code>setting</code> directive</a>).</p>
<p>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 as text, FreeMarker must know which parts
of the date 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. If it is 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, or it will stop with error.</p>
</div>
<h2 class="content-header header-simplesect" id="autoid_19">Guide for inserting boolean values</h2>
<p>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.</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>
<h2 class="content-header header-simplesect" id="autoid_20">The exact conversion rules</h2>
<p>For those who are interested, the exact rules of conversion
from the expression value to string (that is then still subject to
escaping) are these, in 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 whatever kind of date, time or
date-time, then it is converted to string in the format
specified with the <code class="inline-code">time_format</code>,
<code class="inline-code">date_format</code>, or
<code class="inline-code">datetime_format</code> setting, depending on whether
the date information is time-only, date-only, or a date-time. If
it can&#39;t be detected what kind of date 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><div class="col-right"><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated">
Last generated:
<time itemprop="dateModified" datetime="2020-07-09T23:48:39Z" title="Thursday, July 9, 2020 11:48:39 PM GMT">2020-07-09 23:48:39 GMT</time> </p>
<p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2020
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p>
</div></div></div></body>
</html>