Google Git
Sign in
apache / freemarker-docgen / f6eb79676240e0fa3a9154cdb825da28220fc9b9 / . / legacy-tests / build / test / 1 / dgui_template_exp.html
blob: ea6f4034d720a5f81eb5c3540d092732c5c97598 [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>Expressions - 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="Expressions">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/dgui_template_exp.html">
<link rel="canonical" href="http://example.com/dgui_template_exp.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_exp.html"><span itemprop="name">Expressions</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","Expressions"];</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_directives.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_template_valueinsertion.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="dgui_template_exp" itemprop="headline">Expressions</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#exp_cheatsheet" data-menu-target="exp_cheatsheet">Quick overview (cheat sheet)</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct" data-menu-target="dgui_template_exp_direct">Specify values directly</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_direct_string" data-menu-target="dgui_template_exp_direct_string">Strings</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_number" data-menu-target="dgui_template_exp_direct_number">Numbers</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_boolean" data-menu-target="dgui_template_exp_direct_boolean">Booleans</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_seuqence" data-menu-target="dgui_template_exp_direct_seuqence">Sequences</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_hash" data-menu-target="dgui_template_exp_direct_hash">Hashes</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_var" data-menu-target="dgui_template_exp_var">Retrieving variables</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_var_toplevel" data-menu-target="dgui_template_exp_var_toplevel">Top-level variables</a></li><li><a class="page-menu-link" href="#dgui_template_exp_var_hash" data-menu-target="dgui_template_exp_var_hash">Retrieving data from a hash</a></li><li><a class="page-menu-link" href="#dgui_template_exp_var_sequence" data-menu-target="dgui_template_exp_var_sequence">Retrieving data from a sequence</a></li><li><a class="page-menu-link" href="#dgui_template_exp_var_special" data-menu-target="dgui_template_exp_var_special">Special variables</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_stringop" data-menu-target="dgui_template_exp_stringop">String operations</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_stringop_interpolation" data-menu-target="dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a></li><li><a class="page-menu-link" href="#dgui_template_exp_get_character" data-menu-target="dgui_template_exp_get_character">Getting a character</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_sequenceop" data-menu-target="dgui_template_exp_sequenceop">Sequence operations</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_sequenceop_cat" data-menu-target="dgui_template_exp_sequenceop_cat">Concatenation</a></li><li><a class="page-menu-link" href="#dgui_template_exp_seqenceop_slice" data-menu-target="dgui_template_exp_seqenceop_slice">Sequence slice</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_hashop" data-menu-target="dgui_template_exp_hashop">Hash operations</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_hashop_cat" data-menu-target="dgui_template_exp_hashop_cat">Concatenation</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_arit" data-menu-target="dgui_template_exp_arit">Arithmetical calculations</a></li><li><a class="page-menu-link" href="#dgui_template_exp_comparison" data-menu-target="dgui_template_exp_comparison">Comparison</a></li><li><a class="page-menu-link" href="#dgui_template_exp_logicalop" data-menu-target="dgui_template_exp_logicalop">Logical operations</a></li><li><a class="page-menu-link" href="#dgui_template_exp_builtin" data-menu-target="dgui_template_exp_builtin">Built-ins</a></li><li><a class="page-menu-link" href="#dgui_template_exp_methodcall" data-menu-target="dgui_template_exp_methodcall">Method call</a></li><li><a class="page-menu-link" href="#dgui_template_exp_missing" data-menu-target="dgui_template_exp_missing">Handling missing values</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_missing_default" data-menu-target="dgui_template_exp_missing_default">Default value operator</a></li><li><a class="page-menu-link" href="#dgui_template_exp_missing_test" data-menu-target="dgui_template_exp_missing_test">Missing value test operator</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_parentheses" data-menu-target="dgui_template_exp_parentheses">Parentheses</a></li><li><a class="page-menu-link" href="#dgui_template_exp_whitespace" data-menu-target="dgui_template_exp_whitespace">White-space in expressions</a></li><li><a class="page-menu-link" href="#dgui_template_exp_precedence" data-menu-target="dgui_template_exp_precedence">Operator precedence</a></li></ul> </div><p>When you supply values for interpolations or directive
parameters you can use variables or more complex expressions. For
example, if x is the number 8 and y is 5, the value of <code class="inline-code">(x +
y)/2</code> resolves to the numerical value 6.5.</p><p>Before we go into details, let&#39;s see some concrete
examples:</p><ul>
<li>
<p>When you supply value for interpolations: The usage of
interpolations is
<code class="inline-code">${<em class="code-color">expression</em>}</code> where
expression gives the value you want to insert into the output as
text. So <code class="inline-code">${(5 + 8)/2}</code> prints ``6.5&#39;&#39; to the
output (or possibly ``6,5&#39;&#39; if the language of your output is not
US English).</p>
</li>
<li>
<p>When you supply a value for the directive parameter: You
have already seen the <code class="inline-code">if</code> directive in the
Getting Started section. The syntax of this directive is:
<code class="inline-code">&lt;#if
<em class="code-color">expression</em>&gt;<em class="code-color">...</em>&lt;/#if&gt;</code>.
The expression here must evaluate to a boolean value. For example
in <code class="inline-code">&lt;#if 2 &lt; 3&gt;</code> the <code class="inline-code">2 &lt;
3</code> (2 is less than 3) is an expression which evaluates to
<code class="inline-code">true</code>.</p>
</li>
</ul>
<h2 class="content-header header-section2" id="exp_cheatsheet">Quick overview (cheat sheet)</h2>
<p>This is a reminder for those of you who already know
FreeMarker or are just experienced programmers:</p>
<ul>
<li>
<a href="#dgui_template_exp_direct">Specify values
directly</a>
<ul>
<li>
<a href="#dgui_template_exp_direct_string">Strings</a>:
<code class="inline-code">&quot;Foo&quot;</code> or <code class="inline-code">&#39;Foo&#39;</code> or
<code class="inline-code">&quot;It&#39;s \&quot;quoted\&quot;&quot;</code> or
<code class="inline-code">r&quot;C:\raw\string&quot;</code>
</li>
<li>
<a href="#dgui_template_exp_direct_number">Numbers</a>:
<code class="inline-code">123.45</code>
</li>
<li>
<a href="#dgui_template_exp_direct_boolean">Booleans</a>:
<code class="inline-code">true</code>, <code class="inline-code">false</code>
</li>
<li>
<a href="#dgui_template_exp_direct_seuqence">Sequences</a>:
<code class="inline-code">[&quot;foo&quot;, &quot;bar&quot;, 123.45]</code>,
<code class="inline-code">1..100</code>
</li>
<li>
<a href="#dgui_template_exp_direct_hash">Hashes</a>:
<code class="inline-code">{&quot;name&quot;:&quot;green mouse&quot;,
&quot;price&quot;:150}</code>
</li>
</ul>
</li>
<li>
<a href="#dgui_template_exp_var">Retrieving
variables</a>
<ul>
<li>
<a href="#dgui_template_exp_var_toplevel">Top-level
variables</a>: <code class="inline-code">user</code>
</li>
<li>
<a href="#dgui_template_exp_var_hash">Retrieving
data from a hash</a>: <code class="inline-code">user.name</code>,
<code class="inline-code">user[&quot;name&quot;]</code>
</li>
<li>
<a href="#dgui_template_exp_var_sequence">Retrieving data
from a sequence</a>:
<code class="inline-code">products[5]</code>
</li>
<li>
<a href="#dgui_template_exp_var_special">Special
variable</a>: <code class="inline-code">.main</code>
</li>
</ul>
</li>
<li>
<a href="#dgui_template_exp_stringop">String
operations</a>
<ul>
<li>
<a href="#dgui_template_exp_stringop_interpolation">Interpolation
(or concatenation)</a>:
<code class="inline-code">&quot;Hello ${user}!&quot;</code> (or
<code class="inline-code">&quot;Free&quot; + &quot;Marker&quot;</code>)
</li>
<li>
<a href="#dgui_template_exp_get_character">Getting a
character</a>: <code class="inline-code">name[0]</code>
</li>
</ul>
</li>
<li>
<a href="#dgui_template_exp_sequenceop">Sequence
operations</a>
<ul>
<li>
<a href="#dgui_template_exp_sequenceop_cat">Concatenation</a>:
<code class="inline-code">users + [&quot;guest&quot;]</code>
</li>
<li>
<a href="#dgui_template_exp_seqenceop_slice">Sequence
slice</a>: <code class="inline-code">products[10..19]</code> or
<code class="inline-code">products[5..]</code>
</li>
</ul>
</li>
<li>
<a href="#dgui_template_exp_hashop">Hash
operations</a>
<ul>
<li>
<a href="#dgui_template_exp_hashop_cat">Concatenation</a>:
<code class="inline-code">passwords + {&quot;joe&quot;:&quot;secret42&quot;}</code>
</li>
</ul>
</li>
<li>
<a href="#dgui_template_exp_arit">Arithmetical
calculations</a>: <code class="inline-code">(x * 1.5 + 10) / 2 - y %
100</code>
</li>
<li>
<a href="#dgui_template_exp_comparison">Comparison</a>:
<code class="inline-code">x == y</code>, <code class="inline-code">x != y</code>,
<code class="inline-code">x &lt; y</code>, <code class="inline-code">x &gt; y</code>,
<code class="inline-code">x &gt;= y</code>, <code class="inline-code">x &lt;= y</code>,
<code class="inline-code">x &amp;lt; y</code>, ...etc.
</li>
<li>
<a href="#dgui_template_exp_logicalop">Logical
operations</a>: <code class="inline-code">!registered &amp;&amp; (firstVisit
|| fromEurope)</code>
</li>
<li>
<a href="#dgui_template_exp_builtin">Built-ins</a>:
<code class="inline-code">name?upper_case</code>
</li>
<li>
<a href="#dgui_template_exp_methodcall">Method
call</a>: <code class="inline-code">repeat(&quot;What&quot;, 3)</code>
</li>
<li>
<a href="#dgui_template_exp_missing">Missing value
handler operators</a>:
<ul>
<li>
<a href="#dgui_template_exp_missing_default">Default
value</a>: <code class="inline-code">name!&quot;unknown&quot;</code> or
<code class="inline-code">(user.name)!&quot;unknown&quot;</code> or
<code class="inline-code">name!</code> or
<code class="inline-code">(user.name)!</code>
</li>
<li>
<a href="#dgui_template_exp_missing_test">Missing
value test</a>: <code class="inline-code">name??</code> or
<code class="inline-code">(user.name)??</code>
</li>
</ul>
</li>
</ul>
<p>See also: <a href="#dgui_template_exp_precedence">Operator
precedence</a></p>
<h2 class="content-header header-section2" id="dgui_template_exp_direct">Specify values directly</h2>
<p>Often you want to specify a value directly and not as a result
of some calculations.</p>
<h3 class="content-header header-section3" id="dgui_template_exp_direct_string">Strings</h3>
<p>To specify a string value directly you give the text in
quotation marks, e.g.: <code class="inline-code">&quot;some text&quot;</code> or in
apostrophe-quote, e.g. <code class="inline-code">&#39;some text&#39;</code>. The two
forms are equivalent. If the text itself contains the character
used for the quoting (either <code class="inline-code">&quot;</code> or
<code class="inline-code">&#39;</code>) or backslashes, you have to precede them
with a backslash; this is called escaping. You can type any other
character, including <a href="gloss.html#gloss.lineBreak">line
breaks</a>, in the text directly. Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot;It&#39;s \&quot;quoted\&quot; and
this is a backslash: \\&quot;}
${&#39;It\&#39;s &quot;quoted&quot; and
this is a backslash: \\&#39;}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">It&#39;s &quot;quoted&quot; and
this is a backslash: \
It&#39;s &quot;quoted&quot; and
this is a backslash: \</pre></div>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>Of course, you could simply type the above text into the
template, without using
<code class="inline-code">${<em class="code-color">...</em>}</code>. But we do
it here just for the sake of example, to demonstrate
expressions.</p>
</div>
<a name="topic.escapeSequence"></a>
<p>This is the list of all supported escape sequences. All
other usage of backlash in string literals is an error and any
attempt to use the template will fail.</p>
<div class="table-responsive">
<table class="table">
<thead>
<tr>
<th>Escape sequence</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="inline-code">\&quot;</code></td>
<td>Quotation mark (u0022)</td>
</tr>
<tr>
<td><code class="inline-code">\&#39;</code></td>
<td>Apostrophe (a.k.a. apostrophe-quote) (u0027)</td>
</tr>
<tr>
<td><code class="inline-code">\\</code></td>
<td>Back slash (u005C)</td>
</tr>
<tr>
<td><code class="inline-code">\n</code></td>
<td>Line feed (u000A)</td>
</tr>
<tr>
<td><code class="inline-code">\r</code></td>
<td>Carriage return (u000D)</td>
</tr>
<tr>
<td><code class="inline-code">\t</code></td>
<td>Horizontal tabulation (a.k.a. tab) (u0009)</td>
</tr>
<tr>
<td><code class="inline-code">\b</code></td>
<td>Backspace (u0008)</td>
</tr>
<tr>
<td><code class="inline-code">\f</code></td>
<td>Form feed (u000C)</td>
</tr>
<tr>
<td><code class="inline-code">\l</code></td>
<td>Less-than sign: <code class="inline-code">&lt;</code></td>
</tr>
<tr>
<td><code class="inline-code">\g</code></td>
<td>Greater-than sign: <code class="inline-code">&gt;</code></td>
</tr>
<tr>
<td><code class="inline-code">\a</code></td>
<td>Ampersand: <code class="inline-code">&amp;</code></td>
</tr>
<tr>
<td><code class="inline-code">\x<em class="code-color">Code</em></code></td>
<td>Character given with its hexadecimal <a href="gloss.html#gloss.unicode">Unicode</a> code (<a href="gloss.html#gloss.UCS">UCS</a> code)</td>
</tr>
</tbody>
</table>
</div>
<p>The <code class="inline-code"><em class="code-color">Code</em></code> after
the <code class="inline-code">\x</code> is 1 to 4 hexadecimal digits. For
example this all put a copyright sign into the string:
<code class="inline-code">&quot;\xA9 1999-2001&quot;</code>,
<code class="inline-code">&quot;\x0A9 1999-2001&quot;</code>,
<code class="inline-code">&quot;\x00A9 1999-2001&quot;</code>. When the character directly
after the last hexadecimal digit can be interpreted as hexadecimal
digit, you must use all 4 digits or else FreeMarker will be
confused.</p>
<p>Note that the character sequence <code class="inline-code">${</code> (and
<code class="inline-code">#{</code>) has special meaning. It&#39;s used to insert
the value of expressions (typically: the value of variables, as in
<code class="inline-code">&quot;Hello ${user}!&quot;</code>). This will be explained <a href="#dgui_template_exp_stringop_interpolation">later</a>.
If you want to print <code class="inline-code">${</code>, you should use raw
string literals as explained below.</p>
<p>A special kind of string literals is the raw string
literals. In raw string literals, backslash and
<code class="inline-code">${</code> have no special meaning, they are considered
as plain characters. To indicate that a string literal is a raw
string literal, you have to put an <code class="inline-code">r</code> directly
before the opening quotation mark or apostrophe-quote.
Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${r&quot;${foo}&quot;}
${r&quot;C:\foo\bar&quot;}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">${foo}
C:\foo\bar</pre></div>
<h3 class="content-header header-section3" id="dgui_template_exp_direct_number">Numbers</h3>
<p>To specify a numerical value directly you type the number
without quotation marks. You have to use the dot as your decimal
separator and must not use any grouping separator symbols. You can
use <code class="inline-code">-</code> or <code class="inline-code">+</code> to indicate the
sign (<code class="inline-code">+</code> is redundant). Scientific notation is
not yet supported (so <code class="inline-code">1E3</code> is wrong). Also, you
cannot omit the 0 before the decimal separator (so
<code class="inline-code">.5</code> is wrong).</p>
<p>Examples of valid number literals: <code class="inline-code">0.08</code>,
<code class="inline-code">-5.013</code>, <code class="inline-code">8</code>,
<code class="inline-code">008</code>, <code class="inline-code">11</code>,
<code class="inline-code">+11</code></p>
<p>Note that numerical literals like <code class="inline-code">08</code>,
<code class="inline-code">+8</code>, <code class="inline-code">8.00</code> and
<code class="inline-code">8</code> are totally equivalent as they all symbolize
the number eight. Thus, <code class="inline-code">${08}</code>,
<code class="inline-code">${+8}</code>, <code class="inline-code">${8.00}</code> and
<code class="inline-code">${8}</code> will all print exactly same.</p>
<h3 class="content-header header-section3" id="dgui_template_exp_direct_boolean">Booleans</h3>
<p>To specify a boolean value you write <code class="inline-code">true</code>
or <code class="inline-code">false</code>. Don&#39;t use quotation marks.</p>
<h3 class="content-header header-section3" id="dgui_template_exp_direct_seuqence">Sequences</h3>
<p>To specify a literal sequence, you list the <a href="dgui_quickstart_datamodel.html#topic.dataModel.subVar">subvariables</a> separated by
commas, and put the whole list into square brackets. For
example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#list <strong>[&quot;winter&quot;, &quot;spring&quot;, &quot;summer&quot;, &quot;autumn&quot;]</strong> as x&gt;
${x}
&lt;/#list&gt;</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">winter
spring
summer
autumn
</pre></div>
<p>The items in the list are expressions, so you can do this
for example: <code class="inline-code">[2 + 2, [1, 2, 3, 4], &quot;whatnot&quot;]</code>.
Here the first subvariable will be the number 4, the second will
be another sequence, and the third subvariable will be the string
&quot;whatnot&quot;.</p>
<p>You can define sequences that store a numerical range with
<code class="inline-code"><em class="code-color">start</em>..<em class="code-color">end</em></code>,
where <code class="inline-code"><em class="code-color">start</em></code> and
<code class="inline-code"><em class="code-color">end</em></code> are expressions
that resolve to numerical values. For example
<code class="inline-code">2..5</code> is the same as <code class="inline-code">[2, 3, 4,
5]</code>, but the former is much more efficient (occupies less
memory and faster). Note that the square brackets are missing. You
can define decreasing numerical ranges too, e.g.:
<code class="inline-code">5..2</code>. (Furthermore, you can omit the
<code class="inline-code"><em class="code-color">end</em></code>, for example
<code class="inline-code">5..</code>, in which case the sequence will contain 5,
6, 7, 8, ...etc up to the infinity.)</p>
<h3 class="content-header header-section3" id="dgui_template_exp_direct_hash">Hashes</h3>
<p>To specify a hash in a template, you list the key/value
pairs separated by commas, and put the list into curly brackets.
The key and value within a key/value pair are separated with a
colon. Here is an example: <code class="inline-code">{&quot;name&quot;:&quot;green mouse&quot;,
&quot;price&quot;:150}</code>. Note that both the names and the values
are expressions. However, the lookup names must be strings.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_var">Retrieving variables</h2>
<h3 class="content-header header-section3" id="dgui_template_exp_var_toplevel">Top-level variables</h3>
<p>To access a top-level variable, you simply use the variable
name. For example, the expression <code class="inline-code">user</code> will
evaluate to the value of variable stored with name ``user&#39;&#39; in the
root. So this will print what you store there:</p>
<div class="code-wrapper"><pre class="code-block code-template">${user}</pre></div>
<p>If there is no such top-level variable, then an error will
result when FreeMarker tries to evaluate the expression, and it
aborts template processing (unless programmers has configured
FreeMarker differently).</p>
<p>In this expression the variable name can contain only
letters (including non-Latin letters), digits (including non-Latin
digits), underline (_), dollar ($), at sign (@) and hash (#).
Furthermore, the name must not start with digit.</p>
<h3 class="content-header header-section3" id="dgui_template_exp_var_hash">Retrieving data from a hash</h3>
<p>If we already have a hash as a result of an expression, then
we can get its subvariable with a dot and the name of the
subvariable. Assume that we have this data-model:</p>
<div class="code-wrapper"><pre class="code-block code-data-model">(root)
|
+- book
| |
| +- title = &quot;Breeding green mouses&quot;
| |
| +- author
| |
| +- name = &quot;Julia Smith&quot;
| |
| +- info = &quot;Biologist, 1923-1985, Canada&quot;
|
+- test = &quot;title&quot;</pre></div>
<p>Now we can read the <code class="inline-code">title</code> with
<code class="inline-code">book.title</code>, since the book expression will
return a hash (as explained in the last chapter). Applying this
logic further, we can read the name of the author with this
expression: <code class="inline-code">book.author.name</code>.</p>
<p>There is an alternative syntax if we want to give the
subvariable name with an expression:
<code class="inline-code">book[&quot;title&quot;]</code>. In the square brackets you can
give any expression as long as it evaluates to a string. So with
this data-model you can also read the title with
<code class="inline-code">book[test]</code>. More examples; these are all
equivalent: <code class="inline-code">book.author.name</code>,
<code class="inline-code">book[&quot;author&quot;].name</code>,
<code class="inline-code">book.author.[&quot;name&quot;]</code>,
<code class="inline-code">book[&quot;author&quot;][&quot;name&quot;]</code>.</p>
<p>When you use the dot syntax, the same restrictions apply
regarding the variable name as with top-level variables (name can
contain only letters, digits, _, $, @, etc.). There are no such
restrictions when you use the square bracket syntax, since the
name is the result of an arbitrary expression. (Note, that to help
the FreeMarker XML support, if the subvariable name is
<code class="inline-code">*</code> (asterisk) or <code class="inline-code">**</code>, then you
do not have to use square bracket syntax.)</p>
<p>As with the top-level variables, trying to access a
non-existent subvariable causes an error and aborts the processing
of the template (unless programmers has configured FreeMarker
differently).</p>
<h3 class="content-header header-section3" id="dgui_template_exp_var_sequence">Retrieving data from a sequence</h3>
<p>This is the same as for hashes, but you can use the square
bracket syntax only, and the expression in the brackets must
evaluate to a number, not a string. For example to get the name of
the first animal of the <a href="dgui_datamodel_basics.html#example.stdDataModel">example data-model</a> (remember
that the number of the first item is 0, not 1):
<code class="inline-code">animals[0].name</code></p>
<h3 class="content-header header-section3" id="dgui_template_exp_var_special">Special variables</h3>
<p>Special variables are variables defined by the FreeMarker
engine itself. To access them, you use the
<code class="inline-code">.<em class="code-color">variable_name</em></code>
syntax.</p>
<p>Normally you don&#39;t need to use special variables. They are
for expert users. The complete list of special variables can be
found in the <a href="ref_specvar.html">reference</a>.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_stringop">String operations</h2>
<h3 class="content-header header-section3" id="dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</h3>
<p>If you want to insert the value of an expression into a
string, you can use
<code class="inline-code">${<em class="code-color">...</em>}</code> (and
<code class="inline-code">#{<em class="code-color">...</em>}</code>) in string
literals. <code class="inline-code">${<em class="code-color">...</em>}</code>
behaves similarly as in <span class="marked-text">text</span>
sections. For example (assume that user is ``Big Joe&#39;&#39;):</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot;Hello ${user}!&quot;}
${&quot;${user}${user}${user}${user}&quot;}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">Hello Big Joe!
Big JoeBig JoeBig JoeBig Joe</pre></div>
<p>Alternatively, you can use the <code class="inline-code">+</code> operator
to achieve similar result. This is the old method, and it is
called string concatenation. Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${&quot;Hello &quot; + user + &quot;!&quot;}
${user + user + user + user}</pre></div>
<p>This will print the same as the example with the
<code class="inline-code">${<em class="code-color">...</em>}</code>-s.</p>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>A frequent mistake of users is the usage of interpolations
in places where it 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
string literals (e.g. <code class="inline-code">&lt;#include
&quot;/footer/${company}.html&quot;&gt;</code>). A typical bad usage is
<code class="inline-code">&lt;#if ${isBig}&gt;Wow!&lt;/#if&gt;</code>, which
is syntactically <em>WRONG</em>. You should simply
write <code class="inline-code">&lt;#if isBig&gt;Wow!&lt;/#if&gt;</code>.
Also, <code class="inline-code">&lt;#if &quot;${isBig}&quot;&gt;Wow!&lt;/#if&gt;</code>
is <em>WRONG</em> too, 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>
<h3 class="content-header header-section3" id="dgui_template_exp_get_character">Getting a character</h3>
<p>You can get a single character of a string at a given index
similarly as you can <a href="#dgui_template_exp_var_sequence">read the subvariable of a
sequence</a>, e.g. <code class="inline-code">user[0]</code>. The result will
be a string whose length is 1; FTL doesn&#39;t have a separate
character type. As with sequence subvariables, the index must be a
number that is at least 0 and less than the length of the string,
or else an error will abort the template processing.</p>
<p>Since the sequence subvariable syntax and the character
getter syntax clashes, you can use the character getter syntax
only if the variable is not a sequence as well (which is possible
because FTL supports multi-typed values), since in that case the
sequence behavior prevails. (To work this around, you can use
<a href="ref_builtins_string.html#ref_builtin_string_for_string">the
<code>string</code> built-in</a>, e.g.
<code class="inline-code">user?string[0]</code>. Don&#39;t worry if you don&#39;t
understand this yet; built-ins will be discussed later.)</p>
<p>Example (assume that user is ``Big Joe&#39;&#39;):</p>
<div class="code-wrapper"><pre class="code-block code-template">${user[0]}
${user[4]}</pre></div>
<p>will print (note that the index of the first character is
0):</p>
<div class="code-wrapper"><pre class="code-block code-output">B
J</pre></div>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>You can get a range of characters in the same way as you
<a href="#dgui_template_exp_seqenceop_slice">get a sequence
slice</a>, e.g <code class="inline-code">${user[1..4]}</code> and
<code class="inline-code">${user[4..]}</code>. However, it&#39;s now depreacted to
utilize this, and instead you should use <a href="ref_builtins_string.html#ref_builtin_substring">the <code>substring</code>
built-in</a>; built-ins will be discussed later.</p>
</div>
<h2 class="content-header header-section2" id="dgui_template_exp_sequenceop">Sequence operations</h2>
<h3 class="content-header header-section3" id="dgui_template_exp_sequenceop_cat">Concatenation</h3>
<p>You can concatenate sequences in the same way as strings,
with <code class="inline-code">+</code>. Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#list [&quot;Joe&quot;, &quot;Fred&quot;] + [&quot;Julia&quot;, &quot;Kate&quot;] as user&gt;
- ${user}
&lt;/#list&gt;</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">- Joe
- Fred
- Julia
- Kate
</pre></div>
<p>Note that sequence concatenation is not to be used for many
repeated concatenations, like for appending items to a sequence
inside a loop. It&#39;s just for things like <code class="inline-code">&lt;#list users
+ admins as person&gt;</code>. Although concatenating sequences
is fast and its speed is independently of the size of the
concatenated sequences, the resulting sequence will be always a
little bit slower to read than the original two sequences were.
This way the result of many repeated concatenations is a sequence
that is slow to read.</p>
<h3 class="content-header header-section3" id="dgui_template_exp_seqenceop_slice">Sequence slice</h3>
<p>With
<code class="inline-code">[<em class="code-color">firstindex</em>..<em class="code-color">lastindex</em>]</code>
you can get a slice of a sequence, where
<code class="inline-code"><em class="code-color">firstindex</em></code> and
<code class="inline-code"><em class="code-color">lastindex</em></code> are
expressions evaluate to number. For example, if
<code class="inline-code">seq</code> stores the sequence <code class="inline-code">&quot;a&quot;</code>,
<code class="inline-code">&quot;b&quot;</code>, <code class="inline-code">&quot;c&quot;</code>,
<code class="inline-code">&quot;d&quot;</code>, <code class="inline-code">&quot;e&quot;</code>,
<code class="inline-code">&quot;f&quot;</code> then the expression
<code class="inline-code">seq[1..4]</code> will evaluate to a sequence that
contains <code class="inline-code">&quot;b&quot;</code>, <code class="inline-code">&quot;c&quot;</code>,
<code class="inline-code">&quot;d&quot;</code>, <code class="inline-code">&quot;e&quot;</code> (since the item at
index 1 is <code class="inline-code">&quot;b&quot;</code>, and the item at index 4 is
<code class="inline-code">&quot;e&quot;</code>).</p>
<p>The <code class="inline-code"><em class="code-color">lastindex</em></code>
can be omitted, in which case it defaults to the index of the last
item of the sequence. For example, if <code class="inline-code">seq</code>
stores the sequence <code class="inline-code">&quot;a&quot;</code>,
<code class="inline-code">&quot;b&quot;</code>, <code class="inline-code">&quot;c&quot;</code>,
<code class="inline-code">&quot;d&quot;</code>, <code class="inline-code">&quot;e&quot;</code>,
<code class="inline-code">&quot;f&quot;</code> again, then <code class="inline-code">seq[3..]</code>
will evaluate to a sequence that contains <code class="inline-code">&quot;d&quot;</code>,
<code class="inline-code">&quot;e&quot;</code>, <code class="inline-code">&quot;f&quot;</code>.</p>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p><code class="inline-code"><em class="code-color">lastindex</em></code>
can be omitted only since FreeMarker 2.3.3.</p>
</div>
<p>An attempt to access a subvariable past the last subvariable
or before the first subvariable of the sequence will cause an
error and abort the processing of the template.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_hashop">Hash operations</h2>
<h3 class="content-header header-section3" id="dgui_template_exp_hashop_cat">Concatenation</h3>
<p>You can concatenate hashes in the same way as strings, with
<code class="inline-code">+</code>. If both hashes contain the same key, the
hash on the right-hand side of the <code class="inline-code">+</code> takes
precedence. Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign ages = {&quot;Joe&quot;:23, &quot;Fred&quot;:25} + {&quot;Joe&quot;:30, &quot;Julia&quot;:18}&gt;
- Joe is ${ages.Joe}
- Fred is ${ages.Fred}
- Julia is ${ages.Julia}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">- Joe is 30
- Fred is 25
- Julia is 18</pre></div>
<p>Note that hash concatenation is not to be used for many
repeated concatenations, like for adding items to a hash inside a
loop. It&#39;s the same as with the <a href="#dgui_template_exp_sequenceop_cat">sequence
concatenation</a>.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_arit">Arithmetical calculations</h2>
<p>This is the basic 4-function calculator arithmetic plus the
modulus operator. So the operators are:</p>
<ul>
<li>
Addition: <code class="inline-code">+</code>
</li>
<li>
Subtraction: <code class="inline-code">-</code>
</li>
<li>
Multiplication: <code class="inline-code">*</code>
</li>
<li>
Division: <code class="inline-code">/</code>
</li>
<li>
Modulus (remainder): <code class="inline-code">%</code>
</li>
</ul>
<p>Example:</p>
<p>Assuming that <code class="inline-code">x</code> is 5, it will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">-75
2.5
2</pre></div>
<p>Both operands must be expressions which evaluate to a
numerical value. So the example below will cause an error when
FreeMarker tries to evaluate it, since <code class="inline-code">&quot;5&quot;</code> is a
string and not the number 5:</p>
<div class="code-wrapper"><pre class="code-block code-template">${3 * &quot;5&quot;} &lt;#-- WRONG! --&gt;</pre></div>
<p>There is an exception to the above rule. The
<code class="inline-code">+</code> operator, is used to <a href="#dgui_template_exp_stringop_interpolation">concatenate
strings</a> as well. If on one side of <code class="inline-code">+</code> is a
string and on the other side of <code class="inline-code">+</code> is a numerical
value, then it will convert the numerical value to string (using the
format appropriate for language of the page) and then use the
<code class="inline-code">+</code> as string concatenation operator.
Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${3 + &quot;5&quot;}</pre></div>
<p>will output this:</p>
<div class="code-wrapper"><pre class="code-block code-output">35</pre></div>
<p>Generally, FreeMarker never converts a string to a number
automatically, but it may convert a number to a string
automatically.</p>
<p> People often want only the integer part of the result
of a division (or of other calculations). This is possible with the
<code class="inline-code">int</code> built-in. (Built-ins are explained <a href="#dgui_template_exp_builtin">later</a>):</p>
<div class="code-wrapper"><pre class="code-block code-template">${(x/2)?int}
${1.1?int}
${1.999?int}
${-1.1?int}
${-1.999?int}</pre></div>
<p>Assuming that <code class="inline-code">x</code> is 5, it will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">2
1
1
-1
-1</pre></div>
<h2 class="content-header header-section2" id="dgui_template_exp_comparison">Comparison</h2>
<p>Sometimes you want to know if two values are equal or not, or
which value is the greater.</p>
<p>To show concrete examples I will use the <code class="inline-code">if</code>
directive here. The usage of <code class="inline-code">if</code> directive is:
<code class="inline-code">&lt;#if
<em class="code-color">expression</em>&gt;...&lt;/#if&gt;</code>,
where expression must evaluate to a boolean value or else an error
will abort the processing of the template. If the value of
expression is <code class="inline-code">true</code> then the things between the
begin and end-tag will be processed, otherwise they will be
skipped.</p>
<p>To test two values for equality you use <code class="inline-code">=</code>
(or <code class="inline-code">==</code> as in Java or C; the two are absolutely
equivalent.) To test two values for inequality you use
<code class="inline-code">!=</code>. For example, assume that
<code class="inline-code">user</code> is ``Big Joe&#39;&#39;:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#if <strong>user = &quot;Big Joe&quot;</strong>&gt;
It is Big Joe
&lt;/#if&gt;
&lt;#if <strong>user != &quot;Big Joe&quot;</strong>&gt;
It is not Big Joe
&lt;/#if&gt;</pre></div>
<p>The <code class="inline-code">user = &quot;Big Joe&quot;</code> expression in the
<code class="inline-code">&lt;#if ...&gt;</code> will evaluate to the boolean
<code class="inline-code">true</code>, so the above will say ``It is Big
Joe&#39;&#39;.</p>
<p>The expressions on both sides of the <code class="inline-code">=</code> or
<code class="inline-code">!=</code> must evaluate to a scalar. Furthermore, the
two scalars must have the same type (i.e. strings can only be
compared to strings and numbers can only be compared to numbers,
etc.) or else an error will abort template processing. For example
<code class="inline-code">&lt;#if 1 = &quot;1&quot;&gt;</code> will cause an error. Note
that FreeMarker does exact comparison, so string comparisons are
case and white-space sensitive: <code class="inline-code">&quot;x&quot;</code> and
<code class="inline-code">&quot;x &quot;</code> and <code class="inline-code">&quot;X&quot;</code> are not equal
values.</p>
<p>For numerical and date values you can also use
<code class="inline-code">&lt;</code>, <code class="inline-code">&lt;=</code>,
<code class="inline-code">&gt;=</code> and <code class="inline-code">&gt;</code>. You can&#39;t use
them for strings! Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#if x <strong>&lt;=</strong> 12&gt;
x is less or equivalent with 12
&lt;/#if&gt;</pre></div>
<p>There is a little problem with <code class="inline-code">&gt;=</code> and
<code class="inline-code">&gt;</code>. FreeMarker interprets the
<code class="inline-code">&gt;</code> as the closing character of the FTL tag. To
prevent this, you have to put the expression into <a href="#dgui_template_exp_parentheses">parenthesis</a>:
<code class="inline-code">&lt;#if (x &gt; y)&gt;</code>. Or, you can use
<code class="inline-code">&amp;gt;</code> and <code class="inline-code">&amp;lt;</code> on the
place of the problematic relation marks: <code class="inline-code">&lt;#if x &amp;gt;
y&gt;</code>. (Note that in general FTL does not support entity
references (those
<code class="inline-code">&amp;<em class="code-color">...</em>;</code> things) in
FTL tags; it is just an exception with the arithmetical
comparisons.). Also, as an alternative you can use
<code class="inline-code">lt</code> instead of <code class="inline-code">&lt;</code>,
<code class="inline-code">lte</code> instead of <code class="inline-code">&lt;=</code>,
<code class="inline-code">gt</code> instead of <code class="inline-code">&gt;</code> and
<code class="inline-code">gte</code> instead of <code class="inline-code">&gt;=</code>. And, for
historical reasons FTL also understands <code class="inline-code">\lt</code>,
<code class="inline-code">\lte</code>, <code class="inline-code">\gt</code> and
<code class="inline-code">\gte</code> which are the same as the ones without the
backslash.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_logicalop">Logical operations</h2>
<p>Just the usual logical operators:</p>
<ul>
<li>
Logical or: <code class="inline-code">||</code>
</li>
<li>
Logical and: <code class="inline-code">&amp;&amp;</code>
</li>
<li>
Logical not: <code class="inline-code">!</code>
</li>
</ul>
<p>The operators will work with boolean values only. Otherwise an
error will abort the template processing.</p>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#if x &lt; 12 <strong>&amp;&amp;</strong> color = &quot;green&quot;&gt;
We have less than 12 things, and they are green.
&lt;/#if&gt;
&lt;#if <strong>!</strong>hot&gt; &lt;#-- here hot must be a boolean --&gt;
It&#39;s not hot.
&lt;/#if&gt;</pre></div>
<h2 class="content-header header-section2" id="dgui_template_exp_builtin">Built-ins</h2>
<p>Built-ins provide, as the name suggest, certain built-in
functionality that is always available. Typically, a built-in
provides a different version of a variable, or some information
about the variable in question. The syntax for accessing a built-in
is like that of accessing a subvariable in a hash, except that you
use the question mark instead of a dot. For example, to get the
upper case version of a string:
<code class="inline-code">user?upper_case</code>.</p>
<p>You can find the complete <a href="ref_builtins.html">list of
built-ins in the Reference</a>. For now, just a few of the more
important ones:</p>
<ul>
<li>
<p>Built-ins to use with strings:</p>
<ul>
<li>
<p><code class="inline-code">html</code>: The string with all special
HTML characters replaced with entity references (E.g.
<code class="inline-code">&lt;</code> with
<code class="inline-code">&amp;lt;</code>)</p>
</li>
<li>
<p><code class="inline-code">cap_first</code>: The string with the
first letter converted to upper case</p>
</li>
<li>
<p><code class="inline-code">lower_case</code>: The lowercase version
of the string</p>
</li>
<li>
<p><code class="inline-code">upper_case</code>: The uppercase version
of the string</p>
</li>
<li>
<p><code class="inline-code">trim</code>: The string without leading
and trailing <a href="gloss.html#gloss.whiteSpace">white-spaces</a></p>
</li>
</ul>
</li>
<li>
<p>Built-ins to use with sequences:</p>
<ul>
<li>
<p><code class="inline-code">size</code>: The number of elements in the
sequence</p>
</li>
</ul>
</li>
<li>
<p>Built-ins to use with numbers:</p>
<ul>
<li>
<p><code class="inline-code">int</code>: The integer part of a number
(e.g. <code class="inline-code">-1.9?int</code> is
<code class="inline-code">-1</code>)</p>
</li>
</ul>
</li>
</ul>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${test?html}
${test?upper_case?html}</pre></div>
<p>Assuming that <code class="inline-code">test</code> stores the string ``Tom
&amp; Jerry&#39;&#39;, the output will be:</p>
<div class="code-wrapper"><pre class="code-block code-output">Tom &amp;amp; Jerry
TOM &amp;amp; JERRY</pre></div>
<p>Note the <code class="inline-code">test?upper_case?html</code>. Since the
result of <code class="inline-code">test?upper_case</code> is a string, you can
use the <code class="inline-code">html</code> built-in with it.</p>
<p>Another example:</p>
<div class="code-wrapper"><pre class="code-block code-template">${seasons?size}
${seasons[1]?cap_first} &lt;#-- left side can by any expression --&gt;
${&quot;horse&quot;?cap_first}</pre></div>
<p>Assuming that <code class="inline-code">seasons</code> stores the sequence
<code class="inline-code">&quot;winter&quot;</code>, <code class="inline-code">&quot;spring&quot;</code>,
<code class="inline-code">&quot;summer&quot;</code>, <code class="inline-code">&quot;autumn&quot;</code>, the output
will be:</p>
<div class="code-wrapper"><pre class="code-block code-output">4
Spring
Horse</pre></div>
<h2 class="content-header header-section2" id="dgui_template_exp_methodcall">Method call</h2>
<p>If you have a method then you can use the method call
operation on it. The method call operation is a comma-separated list
of expressions in parentheses. These values are called parameters.
The method call operation passes these values to the method which
will in turn return a result. This result will be the value of the
whole method call expression.</p>
<p>For example, assume the programmers have made available a
method variable called <code class="inline-code">repeat</code>. You give a string
as the first parameter, and a number as the second parameter, and it
returns a string which repeats the first parameter the number of
times specified by the second parameter.</p>
<div class="code-wrapper"><pre class="code-block code-template">${repeat(&quot;What&quot;, 3)}</pre></div>
<p>will print:</p>
<div class="code-wrapper"><pre class="code-block code-output">WhatWhatWhat</pre></div>
<p>Here <code class="inline-code">repeat</code> was evaluated to the method
variable (according to how you <a href="#dgui_template_exp_var_toplevel">access top-level
variables</a>) and then <code class="inline-code">(&quot;What&quot;, 3)</code> invoked
that method.</p>
<p>I would like to emphasize that method calls are just plain
expressions, like everything else. So this:</p>
<div class="code-wrapper"><pre class="code-block code-template">${repeat(repeat(&quot;x&quot;, 2), 3) + repeat(&quot;What&quot;, 4)?upper_case}</pre></div>
<p>will print this:</p>
<div class="code-wrapper"><pre class="code-block code-output">xxxxxxWHATWHATWHATWHAT</pre></div>
<h2 class="content-header header-section2" id="dgui_template_exp_missing">Handling missing values</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>These operators exist since FreeMarker 2.3.7 (replacing the
<code class="inline-code">default</code>, <code class="inline-code">exists</code> and
<code class="inline-code">if_exists</code> built-ins).</p>
</div>
<p>As we explained earlier, an error will occur and abort the
template processing if you try to access a missing variable. However
two special operators can suppress this error, and handle the
problematic situation. The handled variable can be top-level
variable, hash subvariable, or sequence subvariable as well.
Furthermore these operators handle the situation when a method call
doesn&#39;t return a value <span class="marked-for-programmers">(from the
viewpoint of Java programmers: it returns <code class="inline-code">null</code> or
it&#39;s return type is <code class="inline-code">void</code>)</span>, so it&#39;s more
correct to say that these operators handle missing values in
general, rather than just missing variables.</p>
<p><span class="marked-for-programmers">For those who know what&#39;s Java
<code class="inline-code">null</code>, FreeMarker 2.3.<em>x</em>
treats them as missing values. Simply, the template language doesn&#39;t
know the concept of <code class="inline-code">null</code>. For example, if you
have a bean that has a <code class="inline-code">maidenName</code> property, and
the value of that property is <code class="inline-code">null</code>, then that&#39;s
the same as if there were no such property at all, as far as the
template is concerned (assuming you didn&#39;t configured FreeMarker to
use some extreme object wrapper, that is). The result of a method
call that returns <code class="inline-code">null</code> is also treated as a
missing variable (again, assuming that you use some usual object
wrapper). See more <a href="app_faq.html#faq_null">in the
FAQ</a>.</span></p>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p>If you wonder why is FreeMarker so picky about missing
variables, <a href="app_faq.html#faq_picky_about_missing_vars">read this
FAQ entry</a>.</p>
</div>
<h3 class="content-header header-section3" id="dgui_template_exp_missing_default">Default value operator</h3>
<p>Synopsis:
<code class="inline-code"><em class="code-color">unsafe_expr</em>!<em class="code-color">default_expr</em></code>
or <code class="inline-code"><em class="code-color">unsafe_expr</em>!</code> or
<code class="inline-code">(<em class="code-color">unsafe_expr</em>)!<em class="code-color">default_expr</em></code>
or
<code class="inline-code">(<em class="code-color">unsafe_expr</em>)!</code></p>
<p>This operator allows you to specify a default value for the
case when the value is missing.</p>
<p>Example. Assume no variable called <code class="inline-code">mouse</code>
is present:</p>
<div class="code-wrapper"><pre class="code-block code-template">${mouse!&quot;No mouse.&quot;}
&lt;#assign mouse=&quot;Jerry&quot;&gt;
${mouse!&quot;No mouse.&quot;}</pre></div>
<p>The output will be:</p>
<div class="code-wrapper"><pre class="code-block code-output">No mouse.
Jerry</pre></div>
<p>The default value can be any kind of expression, so it
doesn&#39;t have to be a string. For example you can write
<code class="inline-code">hits!0</code> or <code class="inline-code">colors![&quot;red&quot;, &quot;green&quot;,
&quot;blue&quot;]</code>. There is no restriction regarding the
complexity of the expression that specifies the default value, for
example you can write: <code class="inline-code">cargo.weight!(item.weight *
itemCount + 10)</code>.</p>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>If you have a composite expression after the
<code class="inline-code">!</code>, like <code class="inline-code">1 + x</code>,
<em>always</em> use parenthesses, like
<code class="inline-code">${x!(1 + y)}</code> or <code class="inline-code">${(x!1) +
y)}</code>, depending on which interpretation you meant.
That&#39;s needed because due to a programming mistake in FreeMarker
2.3.x, the precedence of <code class="inline-code">!</code> (when it&#39;s used as
default value operator) is very low at its right side. This
means that, for example, <code class="inline-code">${x!1 + y}</code> is
misinterpreted by FreeMarker as <code class="inline-code">${x!(1 + y)}</code>
while it should mean <code class="inline-code">${(x!1) + y}</code>. This
programming error will be fixed in FreeMarker 2.4, so you should
not utilize this wrong behavior, or else your templates will
break with FreeMarker 2.4!</p>
</div>
<p>If the default value is omitted, then it will be empty
string and empty sequence and empty hash at the same time. (This
is possible because FreeMarker allows multi-type values.) Note the
consequence that you can&#39;t omit the default value if you want it
to be <code class="inline-code">0</code> or <code class="inline-code">false</code>.
Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">(${mouse!})
&lt;#assign mouse = &quot;Jerry&quot;&gt;
(${mouse!})</pre></div>
<p>The output will be:</p>
<div class="code-wrapper"><pre class="code-block code-output">()
(Jerry)</pre></div>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>Due to syntactical ambiguities <code class="inline-code">&lt;@something
a=x! b=y /&gt;</code> will be interpreted as
<code class="inline-code">&lt;@something a=x!(b=y) /&gt;</code>, that is, the
<code class="inline-code">b=y</code> will be interpreted as a comparison that
gives the default value for <code class="inline-code">x</code>, rather than
the specification of the <code class="inline-code">b</code> parameter. To
prevent this, write: <code class="inline-code">&lt;@something a=(x!) b=y
/&gt;</code></p>
</div>
<p>You can use this operator in two ways with non-top-level
variables:</p>
<div class="code-wrapper"><pre class="code-block code-template">product.color!&quot;red&quot;</pre></div>
<p>This will handle if <code class="inline-code">color</code> is missing
inside <code class="inline-code">product</code> (and returns
<code class="inline-code">&quot;red&quot;</code> if so), but will not handle if
<code class="inline-code">product</code> is missing. That is, the
<code class="inline-code">product</code> variable itself must exist, otherwise
the template processing will die with error.</p>
<div class="code-wrapper"><pre class="code-block code-template">(product.color)!&quot;red&quot;</pre></div>
<p>This will handle if <code class="inline-code">product.color</code> is
missing. That is, if <code class="inline-code">product</code> is missing, or
<code class="inline-code">product</code> exists but it does not contain
<code class="inline-code">color</code>, the result will be
<code class="inline-code">&quot;red&quot;</code>, and no error will occur. The important
difference between this and the previous example is that when
surrounded with parentheses, it is allowed for any component of
the expression to be undefined, while without parentheses only the
last component of the expression is allowed to be
undefined.</p>
<p>Of course, the default value operator can be used with
sequence subvariables as well:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign seq = [&#39;a&#39;, &#39;b&#39;]&gt;
${seq[0]!&#39;-&#39;}
${seq[1]!&#39;-&#39;}
${seq[2]!&#39;-&#39;}
${seq[3]!&#39;-&#39;}</pre></div>
<p>the outpur will be:</p>
<div class="code-wrapper"><pre class="code-block code-output">a
b
-
-</pre></div>
<p>A negative sequence index (as
<code class="inline-code">seq[-1]!&#39;-&#39;</code>) will always cause an error, you
can&#39;t suppress that with this or any other operator.</p>
<h3 class="content-header header-section3" id="dgui_template_exp_missing_test">Missing value test operator</h3>
<p>Synopsis:
<code class="inline-code"><em class="code-color">unsafe_expr</em>??</code> or
<code class="inline-code">(<em class="code-color">unsafe_expr</em>)??</code></p>
<p>This operator tells if a value is missing or not. Depending
on that, the result is either <code class="inline-code">true</code> or
<code class="inline-code">false</code>.</p>
<p>Example. Assume no variable called <code class="inline-code">mouse</code>
is present:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#if mouse??&gt;
Mouse found
&lt;#else&gt;
No mouse found
&lt;/#if&gt;
Creating mouse...
&lt;#assign mouse = &quot;Jerry&quot;&gt;
&lt;#if mouse??&gt;
Mouse found
&lt;#else&gt;
No mouse found
&lt;/#if&gt;</pre></div>
<p>The output will be:</p>
<div class="code-wrapper"><pre class="code-block code-output"> No mouse found
Creating mouse...
Mouse found</pre></div>
<p>With non-top-level variables the rules are the same as with
the default value operator, that is, you can write
<code class="inline-code">product.color??</code> and
<code class="inline-code">(product.color)??</code>.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_parentheses">Parentheses</h2>
<p>Parentheses can be used to group any expressions. Some
examples:</p>
<div class="code-wrapper"><pre class="code-block code-template"> &lt;#-- Output will be: --&gt;
${3 * 2 + 2} &lt;#-- 8 --&gt;
${3 * (2 + 2)} &lt;#-- 12 --&gt;
${3 * ((2 + 2) * (1 / 2))} &lt;#-- 6 --&gt;
${&quot;green &quot; + &quot;mouse&quot;?upper_case} &lt;#-- green MOUSE --&gt;
${(&quot;green &quot; + &quot;mouse&quot;)?upper_case} &lt;#-- GREEN MOUSE --&gt;
&lt;#if !( color = &quot;red&quot; || color = &quot;green&quot;)&gt;
The color is nor red nor green
&lt;/#if&gt;</pre></div>
<p>Note that the parentheses of a <a href="#dgui_template_exp_methodcall">method call
expressions</a> have nothing to do with the parentheses used for
grouping.</p>
<h2 class="content-header header-section2" id="dgui_template_exp_whitespace">White-space in expressions</h2>
<p>FTL ignores superfluous <a href="gloss.html#gloss.whiteSpace">white-space</a> in expressions. So
these are totally equivalent:</p>
<div class="code-wrapper"><pre class="code-block code-template">${x + &quot;:&quot; + book.title?upper_case}</pre></div>
<p>and</p>
<div class="code-wrapper"><pre class="code-block code-template">${x+&quot;:&quot;+book.title?upper_case}</pre></div>
<p>and</p>
<div class="code-wrapper"><pre class="code-block code-template">${
x
+ &quot;:&quot; + book . title
? upper_case
}</pre></div>
<h2 class="content-header header-section2" id="dgui_template_exp_precedence">Operator precedence</h2>
<p>The following table shows the precedence assigned to the
operators. The operators in this table are listed in precedence
order: the higher in the table an operator appears, the higher its
precedence. Operators with higher precedence are evaluated before
operators with a relatively lower precedence. Operators on the same
line have equal precedence. When binary operators (operators with
two ``parameters&#39;&#39;, as <code class="inline-code">+</code> and
<code class="inline-code">-</code>) of equal precedence appear next to each other,
they are evaluated in left-to-right order.</p>
<div class="table-responsive">
<table class="table">
<thead>
<tr>
<th>Operator group</th>
<th>Operators</th>
</tr>
</thead>
<tbody>
<tr>
<td>highest precedence operators</td>
<td><code class="inline-code">[<em class="code-color">subvarName</em>]
[<em class="code-color">subStringRange</em>] . ?
(<em class="code-color">methodParams</em>)
<em class="code-color">expr</em>!
<em class="code-color">expr</em>??</code></td>
</tr>
<tr>
<td>unary prefix operators</td>
<td><code class="inline-code">+<em class="code-color">expr</em>
-<em class="code-color">expr</em> !expr</code></td>
</tr>
<tr>
<td>multiplicative</td>
<td><code class="inline-code">* / %</code></td>
</tr>
<tr>
<td>additive</td>
<td><code class="inline-code">+ -</code></td>
</tr>
<tr>
<td>relational</td>
<td><code class="inline-code">&lt; &gt; &lt;= &gt;=</code> (and quivalents:
<code class="inline-code">gt</code>, <code class="inline-code">lt</code>, etc.)</td>
</tr>
<tr>
<td>equality</td>
<td><code class="inline-code">== !=</code> (and equivalents:
<code class="inline-code">=</code>)</td>
</tr>
<tr>
<td>logical AND</td>
<td><code class="inline-code">&amp;&amp;</code></td>
</tr>
<tr>
<td>logical OR</td>
<td><code class="inline-code">||</code></td>
</tr>
<tr>
<td>numerical range</td>
<td><code class="inline-code">..</code></td>
</tr>
</tbody>
</table>
</div>
<p>For those of you who master C, Java language or JavaScript,
note that the precedence rules are the same as in those languages,
except that FTL has some operators that do not exist in those
languages.</p>
<p>The default value operator
(<code class="inline-code"><em class="code-color">exp</em>!<em class="code-color">exp</em></code>)
is not yet in the table because of a programming mistake, which will
be only fixed in FreeMarker 2.4 due to backward compatibility
constraints. It meant to be a &quot;highest precedence operator&quot;, but in
FreeMarker 2.3.x the precedence on its right side is very low by
accident. So if you have a composite expression on the right side,
always use paranthesses, etiher like <code class="inline-code">x!(y + 1)</code> or
like <code class="inline-code">(x!y) + 1</code>. Never write just <code class="inline-code">x!y +
1</code>.</p>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_template_directives.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_template_valueinsertion.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>