http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/dgui_quickstart_basics.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_quickstart_basics.html b/builds/2.3.26-nightly/dgui_quickstart_basics.html new file mode 100644 index 0000000..be35670 --- /dev/null +++ b/builds/2.3.26-nightly/dgui_quickstart_basics.html @@ -0,0 +1,138 @@ +<!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>Template + data-model = output - 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="Template + data-model = output"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_quickstart_basics.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_quickstart_basics.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_basics.html"><span itemprop="name">Template + data-model = output</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Template + data-model = output"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_quickstart_datamodel.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="dgui_quickstart_basics" itemprop="headline">Template + data-model = output</h1> +</div></div><p>Let's assume that you need a HTML page on a website, similar to + this:</p> + +<div class="code-wrapper"><pre class="code-block code-output"><html> +<head> + <title>Welcome!</title> +</head> +<body> + <h1>Welcome <strong>John Doe</strong>!</h1> + <p>Our latest product: + <a href="<strong>products/greenmouse.html</strong>"><strong>green mouse</strong></a>! +</body> +</html></pre></div><p>But the user's name ("John Doe" above) depends on who the + logged-in user is, and the latest product information should come from + a database. Because this data changes, you cannot you cannot use + static HTML. Instead, you can use a <strong>template</strong> of the desired output. The template is + the same as the static HTML would be, except that it contains some + instructions to FreeMarker that makes it dynamic:</p> + +<div class="code-wrapper"><pre class="code-block code-template"><a name="example.first"></a><html> +<head> + <title>Welcome!</title> +</head> +<body> + <h1>Welcome <strong>${user}</strong>!</h1> + <p>Our latest product: + <a href="<strong>${latestProduct.url}</strong>"><strong>${latestProduct.name}</strong></a>! +</body> +</html></pre></div><p>The template is stored on the Web server, usually just like the + static HTML page would be. But whenever someone visits this page, + FreeMarker will step in and transform the template on-the-fly to plain + HTML by replacing the + <code class="inline-code">${<em class="code-color">...</em>}</code>-s with up-to-date + content, and send the result to the visitor's Web browser. So the + visitor's Web browser will receive something like the first example + HTML (i.e., plain HTML without FreeMarker instructions), and it will + not perceive that FreeMarker is used on the server. (Of course, the + template file stored on the Web server is not changed by this; the + substitutions only appear in the Web server's response.)</p><p>Note that the template doesn't contain the programming logic to + find out who the current visitor is, or to query the database to get + the latest product. The data to be displayed is prepared outside + FreeMarker, usually by parts written in some "real" + programming language like Java. The template author needn't know how + these values were calculated. In fact, the way these values are + calculated can be completely changed while the templates can remain + exactly the same, and also, the look of the page can be completely + changed without touching anything but the template. This separation of + presentation logic and business logic can be especially useful when + the template authors (designers) and the programmers are different + individuals, but also helps managing application complexity if they + are the same person. Keeping templates focused on presentation issues + (visual design, layout and formatting) is a key for using template + engines like FreeMarker efficiently.</p><p>The totality of data that was prepared for the template + is called the <strong>data-model</strong>. As far as + the template author is concerned, the data-model is a tree-like + structure (like folders and files on your hard disk), which, in this + case, could be visualized as:</p> + +<div class="code-wrapper"><pre class="code-block code-data-model">(root) + | + +- <strong>user</strong> = "Big Joe" + | + +- <strong>latestProduct</strong> + | + +- <strong>url</strong> = "products/greenmouse.html" + | + +- <strong>name</strong> = "green mouse"</pre></div> <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>The above is just a visualization; the data-model is not in a + textual format, it's from Java objects. For the Java programmers, + the root is perhaps a Java object with <code class="inline-code">getUser()</code> + and <code class="inline-code">getLatestProduct()</code> methods, or maybe a Java + <code class="inline-code">Map</code> with <code class="inline-code">"user"</code> and + <code class="inline-code">"latestProducts"</code> keys. Similarly, + <code class="inline-code">latestProduct</code> is perhaps a Java Object with + <code class="inline-code">getUrl()</code> and <code class="inline-code">getName()</code> + methods.</p> + </div> +<p>Earlier, you have picked values from this data-model, with the + <code class="inline-code">user</code> and <code class="inline-code">latestProduct.name</code> + expressions. If we go on with the analogy that the data model is like + a file system, then "(root)" and + <code class="inline-code">latestProduct</code> correspond to directories (folders), + and <code class="inline-code">user</code>, <code class="inline-code">url</code> and + <code class="inline-code">name</code> are files in those directories.</p><p>To recapitulate, a template and a data-model is needed for + FreeMarker to generate the output (like the HTML shown first):</p><p><span class="marked-template">Template</span> + <span class="marked-data-model">data-model</span> = <span class="marked-output">output</span></p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_quickstart.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_quickstart_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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html>
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/dgui_quickstart_datamodel.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_quickstart_datamodel.html b/builds/2.3.26-nightly/dgui_quickstart_datamodel.html new file mode 100644 index 0000000..5f5b57e --- /dev/null +++ b/builds/2.3.26-nightly/dgui_quickstart_datamodel.html @@ -0,0 +1,199 @@ +<!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 data-model 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 data-model at a glance"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_quickstart_datamodel.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_quickstart_datamodel.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_datamodel.html"><span itemprop="name">The data-model at a glance</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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 data-model at a glance"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_basics.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_quickstart_template.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="dgui_quickstart_datamodel" itemprop="headline">The data-model at a glance</h1> +</div></div><p>As you have seen, the data-model is basically a tree. This tree + can be arbitrarily complicated and deep, for example:</p> + +<div class="code-wrapper"><pre class="code-block code-data-model"><a name="example.qStart.dataModelWithHashes"></a>(root) + | + +- animals + | | + | +- mouse + | | | + | | +- size = "small" + | | | + | | +- price = 50 + | | + | +- elephant + | | | + | | +- size = "large" + | | | + | | +- price = 5000 + | | + | +- python + | | + | +- size = "medium" + | | + | +- price = 4999 + | + +- message = "It is a test" + | + +- misc + | + +- foo = "Something"</pre></div><p>The variables that act like directories (the root, + <code class="inline-code">animals</code>, <code class="inline-code">mouse</code>, + <code class="inline-code">elephant</code>, <code class="inline-code">python</code>, + <code class="inline-code">misc</code>) are called <strong>hashes</strong>. Hashes store other variables (the so + called <a name="topic.dataModel.subVar"></a><em>sub + variables</em>) by a lookup name (e.g., "animals", + "mouse" or "price").</p><p>The variables that store a single value + (<code class="inline-code">size</code>, <code class="inline-code">price</code>, + <code class="inline-code">message</code> and <code class="inline-code">foo</code>) are called + <strong>scalars</strong>.</p><p><a name="topic.qStart.accessVariables"></a>When you want to + use a subvariable in a template, you specify its path from the root, + and separate the steps with dots. To access the + <code class="inline-code">price</code> of a <code class="inline-code">mouse</code>, you start from + the root and go into <code class="inline-code">animals</code>, and then go into + <code class="inline-code">mouse</code> then go into <code class="inline-code">price</code>. So you + write <code class="inline-code">animals.mouse.price</code>.</p><p>Another important kind of variables are <strong>sequences</strong>. They store subvariables like hashes, + but here subvariables doesn't have a name, they are just items in a + list. For example, in this data-model, <code class="inline-code">animals</code> and + <code class="inline-code">misc.fruits</code> are sequences:</p> + +<div class="code-wrapper"><pre class="code-block code-data-model"><a name="example.qStart.dataModelWithSequences"></a>(root) + | + +- animals + | | + | +- (1st) + | | | + | | +- name = "mouse" + | | | + | | +- size = "small" + | | | + | | +- price = 50 + | | + | +- (2nd) + | | | + | | +- name = "elephant" + | | | + | | +- size = "large" + | | | + | | +- price = 5000 + | | + | +- (3rd) + | | + | +- name = "python" + | | + | +- size = "medium" + | | + | +- price = 4999 + | + +- misc + | + +- fruits + | + +- (1st) = "orange" + | + +- (2nd) = "banana"</pre></div><p>To access a subvariable of a sequence you use a numerical index + in square brackets. Indexes start from 0 (it's a programmer tradition + to start with 0), thus the index of the 1st item is 0, the index of + the 2nd item is 1, and so on. So to get the name of the first animal + you write <code class="inline-code">animals[0].name</code>. To get the second item + in <code class="inline-code">misc.fruits</code> (the string + <code class="inline-code">"banana"</code>) you write + <code class="inline-code">misc.fruits[1]</code>. (In practice, you usually just walk + through sequences in order, not caring about the index, but that will + be <a href="dgui_quickstart_template.html#topic.tutorial.list">shown later</a>.)</p><p>Scalars can be further divided into these categories:</p><ul> + <li> + <p>String: Text, that is, an arbitrary sequence of characters + such as ''m'', ''o'', ''u'', ''s'', ''e'' above. For example the + <code class="inline-code">name</code>-s and <code class="inline-code">size</code>-s are + strings above.</p> + </li> + + <li> + <p>Number: It's a numerical value, like the + <code class="inline-code">price</code>-s above. The string + <code class="inline-code">"50"</code> and the number <code class="inline-code">50</code> are + two totally different things in FreeMarker. The former is just a + sequence of two characters (which happens to be readable as a + number for humans), while the latter is a numerical value that you + can use in arithmetical calculations.</p> + </li> + + <li> + <p>Date-like: Either a date-time (stores a date with time of + the day), or a date (no time of day), or a time (time of day, no + date).</p> + </li> + + <li> + <p>Boolean: A true/false (yes/no, on/off, etc.) thing. Like + animals could have a <code class="inline-code">protected</code> subvariable, + which store if the animal is protected or not.</p> + </li> + </ul><p>Summary:</p><ul> + <li> + <p>The data-model can be visualized as a tree.</p> + </li> + + <li> + <p>Scalars store a single value. The value can be a string or a + number or a date-time/date/time or a boolean.</p> + </li> + + <li> + <p>Hashes are containers that store other variables and + associate them with a unique lookup name.</p> + </li> + + <li> + <p>Sequences are containers that store other variables in an + ordered sequence. The stored variables can be retrieved via their + numerical index, starting from 0.</p> + </li> + </ul> <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>There are other, more advanced value types that we don't cover + here, such as methods and directives.</p> + </div> +<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_quickstart_basics.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_quickstart_template.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/dgui_quickstart_template.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_quickstart_template.html b/builds/2.3.26-nightly/dgui_quickstart_template.html new file mode 100644 index 0000000..9626066 --- /dev/null +++ b/builds/2.3.26-nightly/dgui_quickstart_template.html @@ -0,0 +1,707 @@ +<!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="http://freemarker.org/docs/dgui_quickstart_template.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_quickstart_template.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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 class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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 whateve r 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="http://freemarker-online.kenshoo.com/";>http://freemarker-online.kenshoo.com/</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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-output"><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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><p>Fruits: <#list misc.fruits as fruit>${fruit}<strong><#sep>, </strong></#list></pre></div> + + + +<div class="code-wrapper"><pre class="code-block code-output"><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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-output"><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-wrapper"><pre class="code-block code-template"><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> + </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> + </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-wrapper"><pre class="code-block code-template"><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-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-template"><#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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/dgui_template.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_template.html b/builds/2.3.26-nightly/dgui_template.html new file mode 100644 index 0000000..16c53e0 --- /dev/null +++ b/builds/2.3.26-nightly/dgui_template.html @@ -0,0 +1,60 @@ +<!doctype html> +<!-- Generated by FreeMarker/Docgen from DocBook --> +<html lang="en" class="page-type-chapter"> +<head prefix="og: http://ogp.me/ns#";> +<meta charset="utf-8"> +<title>The Template - 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"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_template.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_template.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_template.html"><span itemprop="name">The Template</span></a></li></ul><div class="bookma rks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","The Template"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_datamodel_types.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_template_overallstructure.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-chapter" id="dgui_template" itemprop="headline">The Template</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Section Contents</div> +<ul><li><a class="page-menu-link" href="dgui_template_overallstructure.html" data-menu-target="dgui_template_overallstructure">Overall structure</a></li><li><a class="page-menu-link" href="dgui_template_directives.html" data-menu-target="dgui_template_directives">Directives</a></li><li><a class="page-menu-link" href="dgui_template_exp.html" data-menu-target="dgui_template_exp">Expressions</a></li><li><a class="page-menu-link" href="dgui_template_valueinsertion.html" data-menu-target="dgui_template_valueinsertion">Interpolations</a></li></ul> </div> <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>It is assumed that you have already read the <a href="dgui_quickstart.html">Getting Started</a> and the <a href="dgui_datamodel.html">Values, Types</a> + chapter.</p> + </div> +<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_datamodel_types.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_template_overallstructure.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html>
