| <!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?1594338517553"> |
| </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'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></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper no-toc"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| </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'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'' to the |
| output (or possibly ``6,5'' 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"><#if |
| <em class="code-color">expression</em>><em class="code-color">...</em></#if></code>. |
| The expression here must evaluate to a boolean value. For example |
| in <code class="inline-code"><#if 2 < 3></code> the <code class="inline-code">2 < |
| 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">"Foo"</code> or <code class="inline-code">'Foo'</code> or |
| <code class="inline-code">"It's \"quoted\""</code> or |
| <code class="inline-code">r"C:\raw\string"</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">["foo", "bar", 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">{"name":"green mouse", |
| "price":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["name"]</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">"Hello ${user}!"</code> (or |
| <code class="inline-code">"Free" + "Marker"</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 + ["guest"]</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 + {"joe":"secret42"}</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 < y</code>, <code class="inline-code">x > y</code>, |
| <code class="inline-code">x >= y</code>, <code class="inline-code">x <= y</code>, |
| <code class="inline-code">x &lt; y</code>, ...etc. |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_logicalop">Logical |
| operations</a>: <code class="inline-code">!registered && (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("What", 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!"unknown"</code> or |
| <code class="inline-code">(user.name)!"unknown"</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">"some text"</code> or in |
| apostrophe-quote, e.g. <code class="inline-code">'some text'</code>. The two |
| forms are equivalent. If the text itself contains the character |
| used for the quoting (either <code class="inline-code">"</code> or |
| <code class="inline-code">'</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">${"It's \"quoted\" and |
| this is a backslash: \\"} |
| |
| ${'It\'s "quoted" and |
| this is a backslash: \\'}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">It's "quoted" and |
| this is a backslash: \ |
| |
| It's "quoted" 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">\"</code></td> |
| |
| |
| <td>Quotation mark (u0022)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\'</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"><</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\g</code></td> |
| |
| |
| <td>Greater-than sign: <code class="inline-code">></code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\a</code></td> |
| |
| |
| <td>Ampersand: <code class="inline-code">&</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">"\xA9 1999-2001"</code>, |
| <code class="inline-code">"\x0A9 1999-2001"</code>, |
| <code class="inline-code">"\x00A9 1999-2001"</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's used to insert |
| the value of expressions (typically: the value of variables, as in |
| <code class="inline-code">"Hello ${user}!"</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"${foo}"} |
| ${r"C:\foo\bar"}</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'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"><#list <strong>["winter", "spring", "summer", "autumn"]</strong> as x> |
| ${x} |
| </#list></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], "whatnot"]</code>. |
| Here the first subvariable will be the number 4, the second will |
| be another sequence, and the third subvariable will be the string |
| "whatnot".</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">{"name":"green mouse", |
| "price":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'' 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 = "Breeding green mouses" |
| | | |
| | +- author |
| | | |
| | +- name = "Julia Smith" |
| | | |
| | +- info = "Biologist, 1923-1985, Canada" |
| | |
| +- test = "title"</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["title"]</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["author"].name</code>, |
| <code class="inline-code">book.author.["name"]</code>, |
| <code class="inline-code">book["author"]["name"]</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'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''):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${"Hello ${user}!"} |
| ${"${user}${user}${user}${user}"}</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">${"Hello " + user + "!"} |
| ${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'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 |
| string literals (e.g. <code class="inline-code"><#include |
| "/footer/${company}.html"></code>). 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 "${isBig}">Wow!</#if></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'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't worry if you don't |
| understand this yet; built-ins will be discussed later.)</p> |
| |
| <p>Example (assume that user is ``Big Joe''):</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'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"><#list ["Joe", "Fred"] + ["Julia", "Kate"] as user> |
| - ${user} |
| </#list></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's just for things like <code class="inline-code"><#list users |
| + admins as person></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">"a"</code>, |
| <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, |
| <code class="inline-code">"d"</code>, <code class="inline-code">"e"</code>, |
| <code class="inline-code">"f"</code> then the expression |
| <code class="inline-code">seq[1..4]</code> will evaluate to a sequence that |
| contains <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, |
| <code class="inline-code">"d"</code>, <code class="inline-code">"e"</code> (since the item at |
| index 1 is <code class="inline-code">"b"</code>, and the item at index 4 is |
| <code class="inline-code">"e"</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">"a"</code>, |
| <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, |
| <code class="inline-code">"d"</code>, <code class="inline-code">"e"</code>, |
| <code class="inline-code">"f"</code> again, then <code class="inline-code">seq[3..]</code> |
| will evaluate to a sequence that contains <code class="inline-code">"d"</code>, |
| <code class="inline-code">"e"</code>, <code class="inline-code">"f"</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"><#assign ages = {"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}> |
| - 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'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">"5"</code> is a |
| string and not the number 5:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${3 * "5"} <#-- WRONG! --></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 + "5"}</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"><#if |
| <em class="code-color">expression</em>>...</#if></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'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if <strong>user = "Big Joe"</strong>> |
| It is Big Joe |
| </#if> |
| <#if <strong>user != "Big Joe"</strong>> |
| It is not Big Joe |
| </#if></pre></div> |
| |
| <p>The <code class="inline-code">user = "Big Joe"</code> expression in the |
| <code class="inline-code"><#if ...></code> will evaluate to the boolean |
| <code class="inline-code">true</code>, so the above will say ``It is Big |
| Joe''.</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"><#if 1 = "1"></code> will cause an error. Note |
| that FreeMarker does exact comparison, so string comparisons are |
| case and white-space sensitive: <code class="inline-code">"x"</code> and |
| <code class="inline-code">"x "</code> and <code class="inline-code">"X"</code> are not equal |
| values.</p> |
| |
| <p>For numerical and date values you can also use |
| <code class="inline-code"><</code>, <code class="inline-code"><=</code>, |
| <code class="inline-code">>=</code> and <code class="inline-code">></code>. You can't use |
| them for strings! Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x <strong><=</strong> 12> |
| x is less or equivalent with 12 |
| </#if></pre></div> |
| |
| <p>There is a little problem with <code class="inline-code">>=</code> and |
| <code class="inline-code">></code>. FreeMarker interprets the |
| <code class="inline-code">></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"><#if (x > y)></code>. Or, you can use |
| <code class="inline-code">&gt;</code> and <code class="inline-code">&lt;</code> on the |
| place of the problematic relation marks: <code class="inline-code"><#if x &gt; |
| y></code>. (Note that in general FTL does not support entity |
| references (those |
| <code class="inline-code">&<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"><</code>, |
| <code class="inline-code">lte</code> instead of <code class="inline-code"><=</code>, |
| <code class="inline-code">gt</code> instead of <code class="inline-code">></code> and |
| <code class="inline-code">gte</code> instead of <code class="inline-code">>=</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">&&</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"><#if x < 12 <strong>&&</strong> color = "green"> |
| We have less than 12 things, and they are green. |
| </#if> |
| <#if <strong>!</strong>hot> <#-- here hot must be a boolean --> |
| It's not hot. |
| </#if></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"><</code> with |
| <code class="inline-code">&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 |
| & Jerry'', the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Tom &amp; Jerry |
| TOM &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} <#-- left side can by any expression --> |
| ${"horse"?cap_first}</pre></div> |
| |
| <p>Assuming that <code class="inline-code">seasons</code> stores the sequence |
| <code class="inline-code">"winter"</code>, <code class="inline-code">"spring"</code>, |
| <code class="inline-code">"summer"</code>, <code class="inline-code">"autumn"</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("What", 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">("What", 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("x", 2), 3) + repeat("What", 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'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's return type is <code class="inline-code">void</code>)</span>, so it'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's Java |
| <code class="inline-code">null</code>, FreeMarker 2.3.<em>x</em> |
| treats them as missing values. Simply, the template language doesn'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's |
| the same as if there were no such property at all, as far as the |
| template is concerned (assuming you didn'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!"No mouse."} |
| <#assign mouse="Jerry"> |
| ${mouse!"No mouse."}</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't have to be a string. For example you can write |
| <code class="inline-code">hits!0</code> or <code class="inline-code">colors!["red", "green", |
| "blue"]</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's needed because due to a programming mistake in FreeMarker |
| 2.3.x, the precedence of <code class="inline-code">!</code> (when it'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'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!}) |
| <#assign mouse = "Jerry"> |
| (${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"><@something |
| a=x! b=y /></code> will be interpreted as |
| <code class="inline-code"><@something a=x!(b=y) /></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"><@something a=(x!) b=y |
| /></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!"red"</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">"red"</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)!"red"</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">"red"</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"><#assign seq = ['a', 'b']> |
| ${seq[0]!'-'} |
| ${seq[1]!'-'} |
| ${seq[2]!'-'} |
| ${seq[3]!'-'}</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]!'-'</code>) will always cause an error, you |
| can'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"><#if mouse??> |
| Mouse found |
| <#else> |
| No mouse found |
| </#if> |
| Creating mouse... |
| <#assign mouse = "Jerry"> |
| <#if mouse??> |
| Mouse found |
| <#else> |
| No mouse found |
| </#if></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"> <#-- Output will be: --> |
| ${3 * 2 + 2} <#-- 8 --> |
| ${3 * (2 + 2)} <#-- 12 --> |
| ${3 * ((2 + 2) * (1 / 2))} <#-- 6 --> |
| ${"green " + "mouse"?upper_case} <#-- green MOUSE --> |
| ${("green " + "mouse")?upper_case} <#-- GREEN MOUSE --> |
| <#if !( color = "red" || color = "green")> |
| The color is nor red nor green |
| </#if></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 + ":" + book.title?upper_case}</pre></div> |
| |
| <p>and</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${x+":"+book.title?upper_case}</pre></div> |
| |
| <p>and</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${ |
| x |
| + ":" + 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'', 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">< > <= >=</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">&&</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 "highest precedence operator", 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-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2020-07-09T23:48:37Z" title="Thursday, July 9, 2020 11:48:37 PM GMT">2020-07-09 23:48:37 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> |