| <!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>The template at a glance - Apache FreeMarker Manual</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="Apache FreeMarker Manual"> |
| <meta property="og:title" content="The template at a glance"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/dgui_quickstart_template.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/dgui_quickstart_template.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs"> |
| <ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui.html"><span itemprop="name">Template Author's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_quickstart.html"><span itemprop="name">Getting Started</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_quickstart_template.html"><span itemprop="name">The template at a glance</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["Apache FreeMarker Manual","Template Author\'s Guide","Getting Started","The template at a glance"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="dgui_quickstart_datamodel.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_datamodel.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="dgui_quickstart_template" itemprop="headline">The template at a glance</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_2" data-menu-target="autoid_2">Some basic directives</a><ul><li><a class="page-menu-link" href="#autoid_3" data-menu-target="autoid_3">The if directive</a></li><li><a class="page-menu-link" href="#autoid_4" data-menu-target="autoid_4">The list directive</a></li><li><a class="page-menu-link" href="#autoid_5" data-menu-target="autoid_5">The include directive</a></li></ul></li><li><a class="page-menu-link" href="#autoid_6" data-menu-target="autoid_6">Using directives together</a></li><li><a class="page-menu-link" href="#autoid_7" data-menu-target="autoid_7">Using built-ins</a></li><li><a class="page-menu-link" href="#autoid_8" data-menu-target="autoid_8">Dealing with missing variables</a></li><li><a class="page-menu-link" href="#dgui_quickstart_template_autoescaping" data-menu-target="dgui_quickstart_template_autoescaping">Escaping for HTML, XML and other markup</a></li></ul> </div><p>The simplest template is a plain HTML file (or whatever text |
| file; FreeMarker is not confined to HTML). When the client visits that |
| page, FreeMarker will send that HTML to the client as is. However if |
| you want that page to be more dynamic then you begin to put special |
| parts into the HTML which will be understood by FreeMarker:</p><ul> |
| <li> |
| <p><code class="inline-code">${<em class="code-color">...</em>}</code>: |
| FreeMarker will replace it in the output with the actual value of |
| the expression inside the curly brackets. They are called |
| <strong>interpolation</strong>s.</p> |
| </li> |
| |
| <li> |
| <p><strong>FTL tags</strong> (for FreeMarker |
| Template Language tags): FTL tags are a bit similar to HTML tags, |
| but they are instructions to FreeMarker and will not be printed to |
| the output. The name of these tags start with |
| <code class="inline-code">#</code>. (User-defined FTL tags use |
| <code class="inline-code">@</code> instead of <code class="inline-code">#</code>, but they are |
| an advanced topic.)</p> |
| </li> |
| |
| <li> |
| <p><strong>Comments:</strong> Comments are |
| similar to HTML comments, but they are delimited by |
| <code class="inline-code"><#--</code> and <code class="inline-code">--></code>. Unlike |
| HTML comments, FTL comments won't get into the output (won't be |
| visible in the page source for the visitor), because FreeMarker |
| skips them.</p> |
| </li> |
| </ul><p>Anything not an FTL tag or an interpolation or comment is |
| considered static text and will not be interpreted by FreeMarker; it |
| is just printed to the output as-is.</p><p>With FTL tags you refer to so-called <strong>directives</strong>. This is the same kind of |
| relationship as between HTML tags (e.g.: |
| <code class="inline-code"><table></code> and |
| <code class="inline-code"></table></code>) and HTML elements (e.g., the |
| <code class="inline-code">table</code> element) to which you refer to with the HTML |
| tags. (If you don't understand this difference then consider "FTL tag" |
| and "directive" synonyms.)</p> <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>You can easily try writing templates on <a href="https://try.freemarker.apache.org/">https://try.freemarker.apache.org/</a></p> |
| </div> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_2">Some basic directives</h2> |
| |
| |
| <p>Here we will look at some of the most commonly used directives |
| (<a href="ref_directives.html">but there are much |
| more</a>).</p> |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section3" id="autoid_3">The if directive</h3> |
| |
| |
| <p>With the <code class="inline-code">if</code> directive you can |
| conditionally skip a section of the template. For example, assume |
| that in the <a href="dgui_quickstart_basics.html#example.first">very first |
| example</a> you want to greet your boss, Big Joe, differently |
| than other users:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><html> |
| <head> |
| <title>Welcome!</title> |
| </head> |
| <body> |
| <h1> |
| Welcome ${user}<strong><#if user == "Big Joe"></strong>, our beloved leader<strong></#if></strong>! |
| </h1> |
| <p>Our latest product: |
| <a href="${latestProduct.url}">${latestProduct.name}</a>! |
| </body> |
| </html></pre> </div> |
| |
| |
| <p>Here you have told FreeMarker that the ", our beloved |
| leader" should be there only if the value of the variable |
| <code class="inline-code">user</code> is equal to the string <code class="inline-code">"Big |
| Joe"</code>. In general, things between <code class="inline-code"><#if |
| <em class="code-color">condition</em>></code> and |
| <code class="inline-code"></#if></code> tags are skipped if |
| <code class="inline-code"><em class="code-color">condition</em></code> is false |
| (the boolean value).</p> |
| |
| <p>Let's look at |
| <code class="inline-code"><em class="code-color">condition</em></code> more |
| closely: <code class="inline-code">==</code> is an operator that tests if the |
| values at its left and right side are equivalent, and the results |
| is a boolean value, true or false accordingly. On the left side of |
| <code class="inline-code">==</code> I have <a href="dgui_quickstart_datamodel.html#topic.qStart.accessVariables">referenced a |
| variable</a> with the syntax that should be already familiar; |
| this will be replaced with the value of the variable. In general, |
| unquoted words inside directives or interpolations are treated as |
| references to variables. On the right side I have specified a |
| literal string. Literal strings in templates must |
| <em>always</em> be put inside quotation marks.</p> |
| |
| <p>This will print "Pythons are free today!" if |
| their price is 0:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if animals.python.price == <strong>0</strong>> |
| Pythons are free today! |
| </#if></pre> </div> |
| |
| |
| <p>Similarly as earlier when a string was specified directly, |
| here a number is specified directly (<code class="inline-code">0</code>). Note |
| that the number is <em>not</em> quoted. If you quoted |
| it (<code class="inline-code">"0"</code>), FreeMarker would misinterpret it as a |
| string literal, and because the price to compare it to is a |
| number, you get an error.</p> |
| |
| <p>This will print "Pythons are not free today!" if their price |
| is not 0:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if animals.python.price <strong>!=</strong> 0> |
| Pythons are not free today! |
| </#if></pre> </div> |
| |
| |
| <p>As you probably guessed, <code class="inline-code">!=</code> means |
| "not equals".</p> |
| |
| <p>You can write things like this too (using <a href="dgui_quickstart_datamodel.html#example.qStart.dataModelWithHashes">the data-model used |
| to demonstrate hashes</a>):</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if <strong>animals.python.price < animals.elephant.price</strong>> |
| Pythons are cheaper than elephants today. |
| </#if></pre> </div> |
| |
| |
| <p>With the <code class="inline-code"><#else></code> tag you can |
| specify what to do if the condition is false. For example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if animals.python.price < animals.elephant.price> |
| Pythons are cheaper than elephants today. |
| <strong><#else></strong> |
| Pythons are not cheaper than elephants today. |
| </#if></pre> </div> |
| |
| |
| <p>This prints "Pythons are cheaper than elephants |
| today." if the price of python is less than the price of |
| elephant, or else it prints "Pythons are not cheaper than |
| elephants today." You can refine this further by using |
| <code class="inline-code">elseif</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if animals.python.price < animals.elephant.price> |
| Pythons are cheaper than elephants today. |
| <strong><#elseif animals.elephant.price < animals.python.price></strong> |
| Elephants are cheaper than pythons today. |
| <#else> |
| Elephants and pythons cost the same today. |
| </#if></pre> </div> |
| |
| |
| <p>If you have a variable with boolean value (a true/false |
| thing) then you can use it directly as the |
| <code class="inline-code"><em class="code-color">condition</em></code> of |
| <code class="inline-code">if</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if animals.python.protected> |
| Pythons are protected animals! |
| </#if></pre> </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section3" id="autoid_4">The list directive</h3> |
| |
| |
| <a name="topic.tutorial.list"></a> |
| |
| <p>This is needed when you want to list something. For example |
| if you merge this template with the <a href="dgui_quickstart_datamodel.html#example.qStart.dataModelWithSequences">data-model used |
| earlier to demonstrate sequences</a>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><p>We have these animals: |
| <table border=1> |
| <strong><#list animals as animal></strong> |
| <tr><td>${<strong>animal</strong>.name}<td>${<strong>animal</strong>.price} Euros |
| <strong></#list></strong> |
| </table></pre> </div> |
| |
| |
| <p>then the output will be:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body"><p>We have these animals: |
| <table border=1> |
| <strong><tr><td>mouse<td>50 Euros |
| <tr><td>elephant<td>5000 Euros |
| <tr><td>python<td>4999 Euros</strong> |
| </table></pre> </div> |
| |
| |
| <p>The generic form of the <code class="inline-code">list</code> directive |
| is:<code class="inline-code"> <#list <em class="code-color">sequence</em> as |
| <em class="code-color">loopVariable</em>><em class="code-color">repeatThis</em></#list></code>. |
| The <code class="inline-code"><em class="code-color">repeatThis</em></code> part |
| will be repeated for each item in the sequence that you have |
| specified with |
| <code class="inline-code"><em class="code-color">sequence</em></code>, one after |
| the other, starting from the first item. In all repetitions |
| <code class="inline-code"><em class="code-color">loopVariable</em></code> will |
| hold the value of the current item. This variable exists only |
| between the <code class="inline-code"><#list |
| <em class="code-color">...</em>></code> and |
| <code class="inline-code"></#list></code> tags.</p> |
| |
| <p>The <code class="inline-code"><em class="code-color">sequence</em></code> |
| can be any kind of expression. For example we could list the |
| fruits of the example data model like this:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><ul> |
| <strong><#list misc.fruits as fruit></strong> |
| <li>${fruit} |
| <strong></#list></strong> |
| </ul></pre> </div> |
| |
| |
| <p>The <code class="inline-code">misc.fruits</code> expression should be |
| familiar to you; it <a href="dgui_quickstart_datamodel.html#topic.qStart.accessVariables">references a variable in |
| the data-model</a>.</p> |
| |
| <p>A problem with the above example is that if we happen to |
| have 0 fruits, it will still print an empty |
| <code class="inline-code"><ul></ul></code> instead of just nothing. |
| To avoid that, you can use this form of |
| <code class="inline-code">list</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#list misc.fruits> |
| <ul> |
| <strong> <#items as fruit></strong> |
| <li>${fruit} |
| <strong> </#items></strong> |
| </ul> |
| </#list></pre> </div> |
| |
| |
| <p>Here, the <code class="inline-code">list</code> directive represents the |
| listing as a whole, and only the part inside the |
| <code class="inline-code">items</code> directive is repeated for each fruit. If |
| we have 0 fruits, everything inside <code class="inline-code">list</code> is |
| skipped, hence we will not have <code class="inline-code">ul</code> tags in |
| case.</p> |
| |
| <p>Another frequent listing-related task: let's list the fruits |
| separating them with something, like a comma:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><p>Fruits: <#list misc.fruits as fruit>${fruit}<strong><#sep>, </strong></#list></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body"><p>Fruits: orange, banana</pre> </div> |
| |
| |
| <p>The section covered by <code class="inline-code">sep</code> (which we |
| could be written like this too: |
| <code class="inline-code"><em class="code-color">...</em><#sep>, |
| </#sep></#list></code>) will be only executed when |
| there will be a next item. Hence there's no comma after the last |
| fruit.</p> |
| |
| <p>Here again, what if we have 0 fruits? Just printing |
| "Fruits:" and then nothing is awkward. A |
| <code class="inline-code">list</code>, just like an <code class="inline-code">if</code>, can |
| have an <code class="inline-code">else</code>, which is executed if there were 0 |
| list items:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, <strong><#else>None</strong></#list></pre> </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>As a matter of fact, this simplistic example could be |
| written like this, but it uses language devices that are off |
| topic here:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><p>Fruits: ${fruits?join(", ", "None")}</pre> </div> |
| |
| </div> |
| |
| |
| <p>All these directives (<code class="inline-code">list</code>, |
| <code class="inline-code">items</code>, <code class="inline-code">sep</code>, |
| <code class="inline-code">else</code>) can be used together:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#list misc.fruits> |
| <p>Fruits: |
| <ul> |
| <#items as fruit> |
| <li>${fruit}<#sep> and</#sep> |
| </#items> |
| </ul> |
| <#else> |
| <p>We have no fruits. |
| </#list></pre> </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>You can read more about these directives <a href="ref_directive_list.html">in the Reference</a>.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section3" id="autoid_5">The include directive</h3> |
| |
| |
| <p>With the <code class="inline-code">include</code> directive you can insert |
| the content of another file into the template.</p> |
| |
| <p>Suppose you have to show the same copyright notice on |
| several pages. You can create a file that contains the copyright |
| notice only, and insert that file everywhere where you need that |
| copyright notice. Say, you store this copyright notice in |
| <code class="inline-code">copyright_footer.html</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><hr> |
| <i> |
| Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>, |
| <br> |
| All Rights Reserved. |
| </i></pre> </div> |
| |
| |
| <p>Whenever you need that file you simply insert it with the |
| <code class="inline-code">include</code> directive:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><html> |
| <head> |
| <title>Test page</title> |
| </head> |
| <body> |
| <h1>Test page</h1> |
| <p>Blah blah... |
| <strong> <#include "/copyright_footer.html"></strong> |
| </body> |
| </html></pre> </div> |
| |
| |
| <p>and the output will be:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body"><html> |
| <head> |
| <title>Test page</title> |
| </head> |
| <body> |
| <h1>Test page</h1> |
| <p>Blah blah... |
| <strong><hr> |
| <i> |
| Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>, |
| <br> |
| All Rights Reserved. |
| </i></strong> |
| </body> |
| </html></pre> </div> |
| |
| |
| <p>If you change the <code class="inline-code">copyright_footer.html</code>, |
| then the visitor will see the new copyright notice on all |
| pages.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>A much more powerful way of reusing snippets is using |
| macros, but that's an advanced topic <a href="dgui_misc_userdefdir.html">discussed later</a>.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_6">Using directives together</h2> |
| |
| |
| <p>You can use directives as many times on a page as you want, |
| and you can nest directives into each other freely. For example, |
| here you nest <code class="inline-code">if</code> directive inside a |
| <code class="inline-code">list</code> directive:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><strong><#list animals as animal></strong> |
| <div<strong><#if animal.protected></strong><strong> </strong>class="protected"<strong></#if></strong>> |
| ${animal.name} for ${animal.price} Euros |
| </div> |
| <strong></#list></strong></pre> </div> |
| |
| |
| <p>Note that since FreeMarker does not interpret text outside FTL |
| tags, interpolations and FTL comments, above you could use the FTL |
| tags inside HTML attributes without problem.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_7">Using built-ins</h2> |
| |
| |
| <p>The so-called built-ins are like subvariables (or rather like |
| methods, if you know that Java term) that aren't coming from the |
| data-model, but added by FreeMarker to the values. In order to make |
| it clear where subvariables comes from, you have to use |
| <code class="inline-code">?</code> (question mark) instead of <code class="inline-code">.</code> |
| (dot) to access them. <a name="topic.commonlyUsedBuiltIns"></a>Examples with some of the most |
| commonly used built-ins:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">user?upper_case</code> gives the upper case |
| version of the value of <code class="inline-code">user</code> (like |
| "JOHN DOE" instead of "John |
| Doe")</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">animal.name?cap_first</code> give the |
| <code class="inline-code">animal.name</code> with its first letter converted |
| to upper case (like "Mouse" instead of |
| "mouse")</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">user?length</code> gives the number of |
| <em>characters</em> in the value of |
| <code class="inline-code">user</code> (8 for "John Doe")</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">animals?size</code> gives the number of |
| <em>items</em> in the <code class="inline-code">animals</code> |
| sequence (3 in our example data-model)</p> |
| </li> |
| |
| <li> |
| <p>If you are between <code class="inline-code"><#list animals as |
| animal></code> and the corresponding |
| <code class="inline-code"></#list></code> tag:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">animal?index</code> gives the 0-based |
| index of <code class="inline-code">animal</code> inside |
| <code class="inline-code">animals</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">animal?counter</code> is like |
| <code class="inline-code">index</code>, but gives the 1-based index</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">animal?item_parity</code> gives the |
| strings "odd" or "even", depending |
| on the current counter parity. This is commonly used for |
| coloring rows with alternating colors, like in |
| <code class="inline-code"><td |
| class="${animal?item_parity}Row"></code>.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">product.id?c</code> formats |
| <code class="inline-code">product.id</code> (let's say that's a number, the |
| technical ID of the product in our database) so that it can be |
| safely parsed by a computer process. This is important, as |
| <code class="inline-code">${product.id}</code> would format it for human |
| audience, which may contains more complicated (like localized, |
| grouped, etc.) formatting.</p> |
| </li> |
| </ul> |
| |
| <p>Some built-ins require parameters to specify the behavior |
| more, for example:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">animal.protected?string("Y", "N")</code> |
| return the string "Y" or "N" depending |
| on the boolean value of |
| <code class="inline-code">animal.protected</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">animal?item_cycle('lightRow', |
| 'darkRow')</code> is the more generic variant of |
| <code class="inline-code">item_parity</code> from earlier.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">fruits?join(", ")</code>: converts the list to |
| a string by concatenating items, and inserting the parameter |
| separator between each items (like "orange, |
| banana")</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">user?starts_with("J")</code> gives boolean |
| true of false depending on if <code class="inline-code">user</code> starts |
| with the letter "J" or not.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">animals?filter(it -> it.protected)</code> |
| gives the list of protected animals. To list protected animals |
| only, you could use <code class="inline-code"><#list animals?filter(it -> |
| it.protected) as |
| animal><em class="code-color">...</em></#list></code>.</p> |
| </li> |
| </ul> |
| |
| <p>Built-in applications can be chained, like |
| <code class="inline-code">fruits?join(", ")?upper_case</code> will first convert |
| the list a to a string, then converts it to upper case. (This is |
| just like you can chain <code class="inline-code">.</code>-s (dots) too.)</p> |
| |
| <p>You can find the <a href="ref_builtins.html">full set of |
| built-ins in the Reference</a>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_8">Dealing with missing variables</h2> |
| |
| |
| <p>The data-model often has variables that are optional (i.e., |
| sometimes missing). To spot some typical human mistakes, FreeMarker |
| doesn't tolerate references to missing variables unless you tell |
| explicitly what to do if the variable is missing. Here we will show |
| the two most typical ways of doing that.</p> |
| |
| <p><span class="marked-for-programmers">Note for programmers: A |
| non-existent variable and a variable with <code class="inline-code">null</code> |
| value is the same for FreeMarker. The "missing" term used here |
| covers both cases.</span></p> |
| |
| <p>Wherever you refer to a variable, you can specify a default |
| value for the case the variable is missing by following the variable |
| name with a <code class="inline-code">!</code> and the default value. Like in the |
| following example, when <code class="inline-code">user</code> is missing from data |
| model, the template will behave like if <code class="inline-code">user</code>'s |
| value were the string <code class="inline-code">"visitor"</code>. (When |
| <code class="inline-code">user</code> isn't missing, this template behaves exactly |
| like with <code class="inline-code">${user}</code>):</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><h1>Welcome ${user<strong>!"visitor"</strong>}!</h1></pre> </div> |
| |
| |
| <p>You can ask whether a variable isn't missing by putting |
| <code class="inline-code">??</code> after its name. Combining this with the |
| already introduced <code class="inline-code">if</code> directive you can skip the |
| whole greeting if the <code class="inline-code">user</code> variable is |
| missing:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#if <strong>user??</strong>><h1>Welcome ${user}!</h1></#if></pre> </div> |
| |
| |
| <p>Regarding variable accessing with multiple steps, like |
| <code class="inline-code">animals.python.price</code>, writing |
| <code class="inline-code">animals.python.price!0</code> is correct only if |
| <code class="inline-code">animals.python</code> is never missing and only the last |
| subvariable, <code class="inline-code">price</code>, is possibly missing (in which |
| case here we assume it's <code class="inline-code">0</code>). If |
| <code class="inline-code">animals</code> or <code class="inline-code">python</code> is missing, |
| the template processing will stop with an "undefined variable" |
| error. To prevent that, you have to write |
| <code class="inline-code">(animals.python.price)!0</code>. In that case the |
| expression will be <code class="inline-code">0</code> even if |
| <code class="inline-code">animals</code> or <code class="inline-code">python</code> is missing. |
| Same logic goes for <code class="inline-code">??</code>; |
| <code class="inline-code">animals.python.price??</code> versus |
| <code class="inline-code">(animals.python.price)??</code>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="dgui_quickstart_template_autoescaping">Escaping for HTML, XML and other markup</h2> |
| |
| |
| <p>Let's say the template generates HTML, and you insert values |
| with <code class="inline-code">${<em class="code-color">...</em>}</code> that are |
| plain text (not HTML), like company names coming from a database. |
| Characters that has special meaning in HTML must be |
| <em>escaped</em> in such values, like if |
| <code class="inline-code">name</code> is "Someone & Co." then |
| <code class="inline-code">${name}</code> should print "Someone |
| <em>&amp;</em> Co.".</p> |
| |
| <p>FreeMarker automatically escapes all values printed with |
| <code class="inline-code">${<em class="code-color">...</em>}</code> <em>if |
| it's properly configured</em> (that's the responsibility of |
| the programmers; <a href="pgui_config_outputformatsautoesc.html">see here how</a>). The |
| recommended practice is using <code class="inline-code">ftlh</code> file extension |
| to activate HTML auto-escaping, and <code class="inline-code">ftlx</code> file |
| extension to activate XML auto-escaping.</p> |
| |
| <p>You can try if auto-escaping is on like |
| <code class="inline-code">${"<"}</code> and then checking the raw output (for |
| HTML or XML escaping). If it's not, and the configuration won't be |
| adjusted, add this as the very first line of the template:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#ftl output_format="HTML"></pre> </div> |
| |
| |
| <p>(Use <code class="inline-code">"XML"</code> instead of |
| <code class="inline-code">"HTML"</code> above if you generate XML.)</p> |
| |
| <p>If the string value to print deliberately contains markup, |
| auto-escaping must be prevented like |
| <code class="inline-code">${<em class="code-color">value</em>?no_esc}</code>.</p> |
| |
| <p>You can find out much more about auto-escaping and output |
| formats <a href="dgui_misc_autoescaping.html">here...</a></p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The kind of automatic escaping described here requires at |
| least FreeMarker 2.3.24. If you have to use an earlier version, |
| use the deprecated <a href="ref_directive_escape.html"><code>escape</code> |
| directive</a> instead.</p> |
| </div> |
| |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_quickstart_datamodel.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_datamodel.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
