| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-section"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>Interpolations - FreeMarker Manual</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="FreeMarker Manual"> |
| <meta property="og:title" content="Interpolations"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="http://example.com/dgui_template_valueinsertion.html"> |
| <link rel="canonical" href="http://example.com/dgui_template_valueinsertion.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338519184"> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="http://example.com/"> |
| <meta itemprop="name" content="FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> |
| <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo"> |
| </a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui.html"><span itemprop="name">Template Author's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template.html"><span itemprop="name">The Template</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template_valueinsertion.html"><span itemprop="name">Interpolations</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["FreeMarker Manual","Template Author\'s Guide","The Template","Interpolations"];</script> |
| <script src="toc.js?1594338519184"></script> |
| <script src="docgen-resources/main.min.js?1594338519184"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="dgui_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="dgui_template_valueinsertion" itemprop="headline">Interpolations</h1> |
| </div></div><p>The format of interpolations is |
| <code class="inline-code">${<em class="code-color">expression</em>}</code>, where |
| <code class="inline-code"><em class="code-color">expression</em></code> can be all |
| kind of expression (e.g. <code class="inline-code">${100 + x}</code>).</p><p>The interpolation is used to insert the value of the |
| <code class="inline-code"><em class="code-color">expression</em></code> converted to |
| text (to string). Interpolations can be used only on two places: in |
| <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> sections</a> (e.g., |
| <code class="inline-code"><h1>Hello ${name}!</h1></code>) and <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">in string literal |
| expressions</a> (e.g., <code class="inline-code">[#include |
| "/footer/${company}.html"]</code>).</p> <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>A frequent mistake is the usage of interpolations in places |
| where it shouldn't/can't be used. A typical bad usage is |
| <code class="inline-code">[#if ${isBig}]Wow![/#if]</code>, which is syntactically |
| <em>WRONG</em>. You should simply write <code class="inline-code">[#if |
| isBig]Wow![/#if]</code>. Also, <code class="inline-code">[#if |
| "${isBig}"]Wow![/#if]</code> is <em>WRONG</em>, since |
| the parameter value will be a string, and the <code class="inline-code">if</code> |
| directive wants a boolean value, so it will cause a runtime |
| error.</p> |
| </div> |
| <p>The result of the expression must be a string, number or date |
| value. This is because only numbers and dates will be converted to |
| string by the interpolation automatically, other types of values (such |
| as booleans, sequences) must be converted to string "manually" somehow |
| (see some advices later), or an error will stop the template |
| processing.</p><p>If the interpolation is in a <a href="dgui_template_overallstructure.html"><span class="marked-text">text</span> section</a> (i.e., not in a <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">string literal |
| expression</a>), the string that it will insert will be |
| automatically escaped if an <a href="ref_directive_escape.html#ref.directive.escape"><code>escape</code> |
| directive</a> is in effect.</p> |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="autoid_18">Guide for inserting numerical values</h2> |
| |
| |
| <p>If the expression evaluates to a number then the numerical |
| value will be converted to string according the default number |
| format. This may includes the maximum number of decimals, grouping, |
| and like. Usually the programmer should set the default number |
| format; the template author don't have to deal with it (but he can |
| with the <code class="inline-code">number_format</code> setting; see in the <a href="ref_directive_setting.html">documentation of |
| <code>setting</code> directive</a>). You can override the |
| default number format for a single interpolation with the <a href="ref_builtins_number.html#ref_builtin_string_for_number"><code>string</code> |
| built-in</a>.</p> |
| |
| <p>The decimal separator used (and other such symbols, like the |
| group separator) depends on the current locale (language, country), |
| that also should be set by the programmer. For example, this |
| template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${1.5}</pre></div> |
| |
| <p>will print something like this if the current locale is |
| English:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1.5</pre></div> |
| |
| <p>but if the current locale is Hungarian then it will print |
| something like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1,5</pre></div> |
| |
| <p>since Hungarian people use comma as decimal separator.</p> |
| |
| <p>You can modify the formatting for a single interpolation with |
| the <a href="ref_builtins_number.html#ref_builtin_string_for_number"><code>string</code> |
| built-in</a>.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>As you can see, interpolations print for human audience (by |
| default at least), as opposed to ''computer audience''. In some |
| cases this is not good, like when you print a database record ID-s |
| as the part of an URL or as an invisible field value in a HTML |
| form, or when you print CSS/JavaScript numerical literals, because |
| these printed values will be read by computer programs and not by |
| humans. Most computer programs are very particular about the |
| format of the numbers, and understand only a kind of simple US |
| number formatting. For that, use the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code></a> (stands for |
| ''computer audience'') built-in, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><a href="/shop/productdetails?id=${product.id?c}">Details...</a></pre></div> |
| </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="dgui_template_valueinserion_universal_date">Guide for inserting date/time values</h2> |
| |
| |
| <p>If the expression evaluates to a date then the numerical value |
| will be transformed to a text according to a default format. Usually |
| the programmer should set the default format; you don't have to deal |
| with it (but if you care, see the <code class="inline-code">date_format</code>, |
| <code class="inline-code">time_format</code> and |
| <code class="inline-code">datetime_format</code> settings in the <a href="ref_directive_setting.html">documentation of the |
| <code>setting</code> directive</a>).</p> |
| |
| <p>You can override the default formatting for a single |
| interpolation with the <a href="ref_builtins_date.html#ref_builtin_string_for_date"><code>string</code> |
| built-in</a>.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>To display a date as text, FreeMarker must know which parts |
| of the date are in use, that is, if only the date part (year, |
| month, day), or only the time part (hour, minute, second, |
| millisecond), or both. Unfortunately, because of the technical |
| limitations of Java platform, for some variables it is not |
| possible to detect this automatically; ask the programmer if the |
| data-model contains such problematic variables. If it is not |
| possible to find out which parts of the date are in use, then you |
| must help FreeMarker with the <a href="ref_builtins_date.html#ref_builtin_date_datetype"><code>date</code>, |
| <code>time</code> and <code>datetime</code></a> |
| built-ins, or it will stop with error.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="autoid_19">Guide for inserting boolean values</h2> |
| |
| |
| <p>An attempt to print boolean values with interpolation causes |
| an error and aborts template processing. For example this will cause |
| an error: <code class="inline-code">${a == 2}</code> and will not print ''true'' |
| or something like that.</p> |
| |
| <p>However, you can convert booleans to strings with the <a href="ref_builtins_boolean.html#ref_builtin_string_for_boolean"><code>?string</code> |
| built-in</a>. For example, to print the value of the "married" |
| variable (assuming it's a boolean), you could write |
| <code class="inline-code">${married?string("yes", "no")}</code>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="autoid_20">The exact conversion rules</h2> |
| |
| |
| <p>For those who are interested, the exact rules of conversion |
| from the expression value to string (that is then still subject to |
| escaping) are these, in in this order:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>If the value is a number, then it is converted to string |
| in the format specified with the |
| <code class="inline-code">number_format</code> setting. So this usually |
| formats for human audience, as opposed to computer |
| audience.</p> |
| </li> |
| |
| <li> |
| <p>Else if the value is whatever kind of date, time or |
| date-time, then it is converted to string in the format |
| specified with the <code class="inline-code">time_format</code>, |
| <code class="inline-code">date_format</code>, or |
| <code class="inline-code">datetime_format</code> setting, depending on whether |
| the date information is time-only, date-only, or a date-time. If |
| it can't be detected what kind of date it is (date vs time vs |
| date-time), an error will occur.</p> |
| </li> |
| |
| <li> |
| <p>Else if the value is a string, then there is no |
| conversion.</p> |
| </li> |
| |
| <li> |
| <p>Else if the engine is in classic compatibility |
| mode:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>If the value is a boolean, true values are converted |
| to "true", false values are converted to an empty |
| string.</p> |
| </li> |
| |
| <li> |
| <p>If the expression is undefined |
| (<code class="inline-code">null</code> or a variable is undefined), it is |
| converted to an empty string.</p> |
| </li> |
| |
| <li> |
| <p>Else an error will abort the template |
| processing.</p> |
| </li> |
| </ol></div> |
| </li> |
| |
| <li> |
| <p>Else an error will abort the template processing.</p> |
| </li> |
| </ol></div> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"></div><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> |