http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/dgui_misc_userdefdir.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_misc_userdefdir.html b/builds/2.3.26-nightly/dgui_misc_userdefdir.html new file mode 100644 index 0000000..1cdb47b --- /dev/null +++ b/builds/2.3.26-nightly/dgui_misc_userdefdir.html @@ -0,0 +1,554 @@ +<!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>Defining your own directives - 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="Defining your own directives"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_misc_userdefdir.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_misc_userdefdir.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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itempro p="itemListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="dgui_misc_userdefdir.html"><span itemprop="name">Defining your own directives</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","Miscellaneous","Defining your own directives"];</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_misc.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_var.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="dgui_misc_userdefdir" itemprop="headline">Defining your own directives</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_19" data-menu-target="autoid_19">Basics</a></li><li><a class="page-menu-link" href="#autoid_20" data-menu-target="autoid_20">Parameters</a></li><li><a class="page-menu-link" href="#autoid_21" data-menu-target="autoid_21">Nested content</a></li><li><a class="page-menu-link" href="#dgui_misc_userdefdir_loopvar" data-menu-target="dgui_misc_userdefdir_loopvar">Macros with loop variables</a></li><li><a class="page-menu-link" href="#autoid_22" data-menu-target="autoid_22">More about user-defined directives and macros</a></li></ul> </div><p>As far as template authors are concerned, user-defined + directives can be defined using the <code class="inline-code">macro</code> + directive. <span class="marked-for-programmers">Java programmers who want to + implement directives in Java Language, rather than in a template, + should use + <code class="inline-code">freemarker.template.TemplateDirectiveModel</code> (see + <a href="pgui_datamodel_directive.html">more + here...</a>).</span></p> + + + + +<h2 class="content-header header-section2" id="autoid_19">Basics</h2> + + + + + <p>A macro is a template fragment associated with a variable. You + can use that variable in your template as a user-defined directive, + so it helps in repetitive tasks. For example, this creates a macro + variable that prints a big "Hello Joe!":</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><strong><#macro greet></strong> + <font size="+2">Hello Joe!</font> +<strong></#macro></strong></pre></div> + + <p>The <code class="inline-code">macro</code> directive itself does not print + anything; it just creates the macro variable, so there will be a + variable called <code class="inline-code">greet</code>. Things between the + <code class="inline-code"><#macro greet></code> and + <code class="inline-code"></#macro></code> (called <strong>macro definition body</strong>) will be executed only + when you use the variable as directive. You use user-defined + directives by writing <code class="inline-code">@</code> instead of + <code class="inline-code">#</code> in the FTL tag. Use the variable name as the + directive name. Also, the <a href="gloss.html#gloss.endTag">end-tag</a> for user-defined directives is + mandatory. So you use <code class="inline-code">greet</code> like this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@greet></@greet></pre></div> + + <p>But since + <code class="inline-code"><<em class="code-color">anything</em>></<em class="code-color">anything</em>></code> + is equivalent with + <code class="inline-code"><<em class="code-color">anything</em>/></code> you + should use this shorter form (that is familiar for you if you know + <a href="gloss.html#gloss.XML">XML</a>):</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@greet/></pre></div> + + <p>This will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> <font size="+2">Hello Joe!</font> + </pre></div> + + <p>But macros can do much more, since the thing between + <code class="inline-code"><#macro <em class="code-color">...</em>></code> and + <code class="inline-code"></#macro></code> is a template fragment, thus it + can contain interpolations + (<code class="inline-code">${<em class="code-color">...</em>}</code>) and FTL tags + (e.g. <code class="inline-code"><#if + <em class="code-color">...</em>><em class="code-color">...</em></#if></code>).</p> + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>Programmers will say on + <code class="inline-code"><@<em class="code-color">...</em>></code> that + you <strong>call</strong> the macro.</p> + </div> + + + + + + +<h2 class="content-header header-section2" id="autoid_20">Parameters</h2> + + + <p>Let's improve the <code class="inline-code">greet</code> macro so it can use + arbitrary name, not only "Joe". For this purpose you + can use <strong>parameters</strong>. You define the + parameters after the name of the macro in the + <code class="inline-code">macro</code> directive. Here we define one parameter for + the <code class="inline-code">greet</code> macro, + <code class="inline-code">person</code>:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro greet <strong>person</strong>> + <font size="+2">Hello <strong>${person}</strong>!</font> +</#macro></pre></div> + + <p>and then you can use this macro as:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@greet <strong>person="Fred"</strong>/> and <@greet <strong>person="Batman"</strong>/></pre></div> + + <p>which is similar to HTML syntax. This will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> <font size="+2">Hello <strong>Fred</strong>!</font> + and <font size="+2">Hello <strong>Batman</strong>!</font> + </pre></div> + + <p>As you can see, the actual value of the macro parameter is + accessible in the macro definition body as a variable + (<code class="inline-code">person</code>). As with <a href="gloss.html#gloss.predefinedDirective">predefined directives</a>, + the value of a parameter (the right side of <code class="inline-code">=</code>) is + an <a href="dgui_template_exp.html">FTL expression</a>. Thus, + unlike with HTML, the quotation marks around + <code class="inline-code">"Fred"</code> and <code class="inline-code">"Batman"</code> are not + optional. <code class="inline-code"><@greet person=Fred/></code> would mean + that you use the value of variable <code class="inline-code">Fred</code> for the + <code class="inline-code">person</code> parameter, rather than the string + <code class="inline-code">"Fred"</code>. Of course parameter value need not be a + string, it can be number, boolean, hash, sequence, etc., also you + can use complex expression on the right side of <code class="inline-code">=</code> + (e.g. <code class="inline-code">someParam=(price + 50)*1.25</code>).</p> + + <p>User-defined directives can have multiple parameters. For + example, add a new parameter <code class="inline-code">color</code>:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro greet person <strong>color</strong>> + <font size="+2" color="${color}">Hello ${person}!</font> +</#macro></pre></div> + + <p>and then you can use this macro like:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@greet person="Fred" color="black"/></pre></div> + + <p>The order of parameters is not important, so this is + equivalent with the previous:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@greet color="black" person="Fred"/></pre></div> + + <p>When you call the macro, you can use only parameters that you + have defined in the <code class="inline-code">macro</code> directive (in this + case: <code class="inline-code">person</code> and <code class="inline-code">color</code>). So if + you try <code class="inline-code"><@greet person="Fred" color="black" + background="green"/></code> then you will get an error, since + you haven't mentioned parameter <code class="inline-code">background</code> in the + <code class="inline-code"><#macro + <em class="code-color">...</em>></code>.</p> + + <p>Also, you must give value for all parameters that you have + defined for the macro. So if you try <code class="inline-code"><@greet + person="Fred"/></code> then you will get an error, since you + forgot to specify the value of <code class="inline-code">color</code>. However, it + often happens that you would specify the same value for a parameter + in most cases, so you want to specify the value only when you want a + different value for it than the usual. This can be achieved if you + specify the parameter in the <code class="inline-code">macro</code> directive as + <code class="inline-code"><em class="code-color">param_name</em>=<em class="code-color">usual_value</em></code>. + For example, you want to use <code class="inline-code">"black"</code> for + <code class="inline-code">color</code> if you don't specify value for that + parameter when you use the <code class="inline-code">greet</code> + directive:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro greet person color<strong>="black"</strong>> + <font size="+2" color="${color}">Hello ${person}!</font> +</#macro></pre></div> + + <p>Now <code class="inline-code"><@greet person="Fred"/></code> is OK, + since it is equivalent with <code class="inline-code"><@greet person="Fred" + color="black"/></code>, thus the value of + <code class="inline-code">color</code> parameter is known. If you want + <code class="inline-code">"red"</code> for <code class="inline-code">color</code>, then you + write <code class="inline-code"><@greet person="Fred" color="red"/></code>, + and this value will override the usual value specified with the + <code class="inline-code">macro</code> directive, so the value of + <code class="inline-code">color</code> parameter will be + <code class="inline-code">"red"</code>.</p> + + <p>Also, it is important to realize that -- according to the + already explained <a href="dgui_template_exp.html">FTL expression + rules</a> -- <code class="inline-code">someParam=foo</code> and + <code class="inline-code">someParam="${foo}"</code> are very different. In the + fist case, you use the value of variable <code class="inline-code">foo</code> as + the value of the parameter. In the second case, you use a <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">string literal + with interpolation</a>, so the value of the parameter will be a + string -- in this case, the value of <code class="inline-code">foo</code> rendered + to text -- regardless of the type (as number, date, etc.) of + <code class="inline-code">foo</code>. Or, another example: + <code class="inline-code">someParam=3/4</code> and + <code class="inline-code">someParam="${3/4}"</code> are different. If the + directive wants a numerical value for <code class="inline-code">someParam</code>, + it will not like the second variation. Do not exchange these.</p> + + <p>A very important aspect of macro parameters is that they are + local variables. For more information about local variables please + read: <a href="dgui_misc_var.html">Defining variables in the template</a></p> + + + + + +<h2 class="content-header header-section2" id="autoid_21">Nested content</h2> + + + <p>Custom directive can have nested content, similarly as + predefined directives like <code class="inline-code"><#if + <em class="code-color">...</em>><em class="code-color">nested + content</em></#if></code> can have. For example, + this creates a macro that draws borders around its nested + content:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro border> + <table border=4 cellspacing=0 cellpadding=4><tr><td> + <strong><#nested></strong> + </tr></td></table> +</#macro></pre></div> + + <p>The <code class="inline-code"><#nested></code> directive executes the + template fragment between the start-tag and end-tags of the + directive. So if you do this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@border>The bordered text</@border></pre></div> + + <p>the output will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> <table border=4 cellspacing=0 cellpadding=4><tr><td> + The bordered text + </td></tr></table> + </pre></div> + + <p>The <code class="inline-code">nested</code> directive can be called for + multiple times, for example:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro do_thrice><strong> + <#nested> + <#nested> + <#nested></strong> +</#macro> +<@do_thrice> + Anything. +</@do_thrice></pre></div> + + <p>will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> Anything. + Anything. + Anything.</pre></div> + + <p>If you don't use the <code class="inline-code">nested</code> directive, then + the nested content will not be executed. Thus, if you accidentally + use the <code class="inline-code">greet</code> directive like this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@greet person="Joe"> + Anything. +</@greet></pre></div> + + <p>then FreeMarker will not see this as an error, and simply + prints:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"><font size="+2">Hello Joe!</font></pre></div> + + <p>and the nested content will be ignored, since the + <code class="inline-code">greet</code> macro never uses <code class="inline-code">nested</code> + directive.</p> + + <p>The nested content can be anything that is valid FTL, + including other user-defined directives. Thus this is OK:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@border> + <ul> + <@do_thrice> + <li><@greet person="Joe"/> + </@do_thrice> + </ul> +</@border></pre></div> + + <p>and will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> <table border=4 cellspacing=0 cellpadding=4><tr><td> + <ul> + <li><font size="+2">Hello Joe!</font> + + <li><font size="+2">Hello Joe!</font> + + <li><font size="+2">Hello Joe!</font> + + </ul> + + </tr></td></table></pre></div> + + <p>The <a href="dgui_misc_var.html">local variables</a> of a + macro are not visible in the nested content. Say, this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro repeat count> + <#local y = "test"> + <#list 1..count as x> + ${y} ${count}/${x}: <#nested> + </#list> +</#macro> +<@repeat count=3>${y!"?"} ${x!"?"} ${count!"?"}</@repeat></pre></div> + + <p>will print this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> test 3/1: ? ? ? + test 3/2: ? ? ? + test 3/3: ? ? ?</pre></div> + + <p>because the <code class="inline-code">y</code>, <code class="inline-code">x</code> and + <code class="inline-code">count</code> are the local (private) variables of the + macro, and are not visible from outside the macro definition. + Furthermore, a different set of local variables is used for each + macro call, so this will not cause confusion:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro test foo>${foo} (<#nested>) ${foo}</#macro> +<@test foo="A"><@test foo="B"><@test foo="C"/></@test></@test></pre></div> + + <p>and will print this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">A (B (C () C) B) A</pre></div> + + + + + +<h2 class="content-header header-section2" id="dgui_misc_userdefdir_loopvar">Macros with loop variables</h2> + + + + + <p>Predefined directives like <code class="inline-code">list</code> can use + so-called loop variables; you should read <a href="dgui_misc_var.html">Defining variables in the template</a> to understand loop variables.</p> + + <p>User-defined directives can also have loop variables. For + example, let's extend the <code class="inline-code">do_thrice</code> directive of + the earlier examples so it exposes the current repetition number as + a loop variable. As with the predefined directives (as + <code class="inline-code">list</code>) the <em>name</em> of loop + variables is given when you call the directive (as + <code class="inline-code">foo</code> in <code class="inline-code"><#list foos as + foo><em class="code-color">...</em></#list></code>), + while the <em>value</em> of the variables is set by the + directive itself.</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro do_thrice> + <#nested <strong>1</strong>> + <#nested <strong>2</strong>> + <#nested <strong>3</strong>> +</#macro> +<@do_thrice <strong>; x</strong>> <#-- user-defined directive uses ";" instead of "as" --> + ${<strong>x</strong>} Anything. +</@do_thrice></pre></div> + + <p>This will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> 1 Anything. + 2 Anything. + 3 Anything. + </pre></div> + + <p>The syntactical rule is that you pass the actual value of the + loop variable for a certain "loop" (i.e. repetition of the nested + content) as the parameter of <code class="inline-code">nested</code> directive (of + course the parameter can by arbitrary expression). The name of the + loop variable is specified in the user-defined directive open tag + (<code class="inline-code"><@...></code>) after the parameters and a + semicolon.</p> + + <p>A macro can use more the one loop variable (the order of + variables is significant):</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#macro repeat count> + <#list 1..count as x> + <#nested <strong>x, x/2, x==count</strong>> + </#list> +</#macro> +<@repeat count=4 ; <strong>c, halfc, last</strong>> + ${<strong>c</strong>}. ${<strong>halfc</strong>}<#if <strong>last</strong>> Last!</#if> +</@repeat></pre></div> + + <p>The output will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> 1. 0.5 + 2. 1 + 3. 1.5 + 4. 2 Last! + </pre></div> + + <p>It is not a problem if you specify different number of loop + variables in the user-defined directive start-tag (that is, after + the semicolon) than with the <code class="inline-code">nested</code> directive. If + you specify less loop variables after the semicolon, then simply you + will not see the last few values that the <code class="inline-code">nested</code> + directive provides, since there is no loop variable to hold those + values. So these are all OK:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><@repeat count=4 ; <strong>c, halfc, last</strong>> + ${c}. ${halfc}<#if last> Last!</#if> +</@repeat> +<@repeat count=4 ; <strong>c, halfc</strong>> + ${c}. ${halfc} +</@repeat> +<@repeat count=4> + Just repeat it... +</@repeat></pre></div> + + <p>If you specify more variables after the semicolon than with + the <code class="inline-code">nested</code> directive, then the last few loop + variables will not be created (i.e. will be undefined in the nested + content).</p> + + + + + +<h2 class="content-header header-section2" id="autoid_22">More about user-defined directives and macros</h2> + + + <p>Now you may read the relevant parts of the FreeMarker + Reference:</p> + + <ul> + <li> + <a href="ref_directive_userDefined.html#ref.directive.userDefined">user-defined + directive call</a> + </li> + + <li> + <a href="ref_directive_macro.html#ref.directive.macro"><code>macro</code> + directive</a> + </li> + </ul> + + <p>You can define methods in FTL as well, see <a href="ref_directive_function.html#ref.directive.function">the <code>function</code> + directive</a>.</p> + + <p>Also, you may interested in namespaces: <a href="dgui_misc_namespace.html">Namespaces</a>. Namespaces help you to organize and + reuse your commonly used macros.</p> + + <p>Java programmers might want to know that directives (macros + are directives) and methods (function-like things) can also be + written in Java language, by<a href="pgui_datamodel_directive.html"> implementing the + <code>TemplateDirectiveModel</code></a> or + <code class="inline-code">TemplateMethodModelEx</code> interfaces, respectively. + Then you can pull in the Java implementations into the template like + <code class="inline-code"><#assign foo = + "com.example.FooDirective"?new()></code> or + <code class="inline-code"><#assign foo = + "com.example.FooMethod"?new()></code> on the same place where + you would have <code class="inline-code"><#macro foo + <em class="code-color">...</em>></code> or + <code class="inline-code"><#function foo + <em class="code-color">...</em>></code> otherwise.</p> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_misc.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_var.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_misc_var.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_misc_var.html b/builds/2.3.26-nightly/dgui_misc_var.html new file mode 100644 index 0000000..1f48d80 --- /dev/null +++ b/builds/2.3.26-nightly/dgui_misc_var.html @@ -0,0 +1,197 @@ +<!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>Defining variables in 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="Defining variables in the template"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_misc_var.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_misc_var.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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itempro p="itemListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="dgui_misc_var.html"><span itemprop="name">Defining variables in the template</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","Miscellaneous","Defining variables in 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_misc_userdefdir.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_namespace.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="dgui_misc_var" itemprop="headline">Defining variables in the template</h1> +</div></div><p>Most of the variables that a typical template works with comes + from the data-model. But templates can also define variables + themselves, usually to hold loops variables, temporary results, + macros, etc. Such variables are outside the data-model; modifying the + data-model from templates is by design unsupported. Note that each + <a href="gloss.html#gloss.templateProcessingJob">template processing + job</a> has its own private set of these variables, which will be + thrown away when the template processing job is finished.</p><p>You access variables defined in the template the same way as you + access variables defined in the data-model root. For example, if you + create a variable called "foo" in the template, you can + print its value with <code class="inline-code">${foo}</code>. If, coincidently, + there's a variable called "foo" in the data-model too, + the variable created in the template will hide (not overwrite!) + it.</p><p>There are these kinds of variables that are defined in a + template:</p><ul> + <li> + <p><strong>"plain" + variables</strong>: They are accessible from everywhere in the + template, or from another templates that was inserted with the + <a href="ref_directive_include.html#ref.directive.include"><code>include</code> + directive</a>. You can create and replace these variables with + the <a href="ref_directive_assign.html#ref.directive.assign"><a href="ref_directive_assign.html#ref.directive.assign"><code>assign</code></a> + directive</a>, or, because macros and functions are just + variables, with the <a href="ref_directive_macro.html#ref.directive.macro"><code>macro</code> + directives</a> and <a href="ref_directive_function.html#ref.directive.function"><code>function</code> + directives</a>.</p> + </li> + + <li> + <p><strong>Local variables</strong>: They can + only be set inside a <a href="gloss.html#gloss.macroDefinitionBody">macro definition body</a> + or <a href="gloss.html#gloss.functionDefinitionBody">function + definition body</a>, and are only visible from there, not from + other macros or functions called from there. A local variable only + exists for the duration of a macro or function call. You can + create and replace local variables inside the definition body with + the <a href="ref_directive_local.html#ref.directive.local"><code>local</code> + directive</a>. <a href="ref_directive_macro.html#ref.directive.macro">Macro</a> + and <a href="ref_directive_function.html#ref.directive.function">function</a> + parameters are also local variables.</p> + </li> + + <li> + <p><strong>Loop variables</strong>: Loop + variables are created automatically by directives like <a href="ref_directive_list.html#ref.directive.list"><code>list</code></a> (like + <code class="inline-code">x</code> in <code class="inline-code"><#list xs as + x><em class="code-color">...</em></#list></code>), and + they only exist between the start-tag and end-tag of the + directive. They are only visible directly between these tags, not + from macros or functions called from there. As such, they are + quite similar to local variables, but they can't be assigned to + directly.</p> + </li> + + <li> + <p><strong>Global variables</strong>: These + should be seldom used. Global variables are shared by all + templates, even if they belong to different name spaces because of + <a href="ref_directive_import.html#ref.directive.import"><code>import</code>-ing</a>. + Thus, their visibility is similar to data-model variables. They + are set via the <a href="ref_directive_global.html#ref.directive.global"><code>global</code> + directive</a>. Global variables hide (but don't overwrite) the + data-model variables of the same name.</p> + </li> + </ul><p>Example: Create and replace variables with + <code class="inline-code">assign</code>:</p> + +<div class="code-wrapper"><pre class="code-block code-template"><#assign x = 1> <#-- create variable x --> +${x} +<#assign x = 2> <#-- replace variable x --> +${x} +<#assign x++> <#-- replace variable x --> +${x}</pre></div> + +<div class="code-wrapper"><pre class="code-block code-output">1 +2 +3</pre></div><p>In the next example we demonstrate that local variables hide + (not overwrite) "plain" variables of the same name, and + that loop variables hide (not overwrite) local and + "plain" variables of the same name:</p> + +<div class="code-wrapper"><pre class="code-block code-template"><#assign x = "plain"> +1. ${x} <#-- we see the plain var. here --> +<@test/> +6. ${x} <#-- the value of plain var. was not changed --> +<#list ["loop"] as x> + 7. ${x} <#-- now the loop var. hides the plain var. --> + <#assign x = "plain2"> <#-- replaces the plain var, not the loop var. --> + 8. ${x} <#-- it still hides the plain var. --> +</#list> +9. ${x} <#-- now the new value of plain var. becomse visible --> + +<#macro test> + 2. ${x} <#-- we still see the plain var. here --> + <#local x = "local"> + 3. ${x} <#-- now the local var. hides it --> + <#list ["loop"] as x> + 4. ${x} <#-- now the loop var. hides the local var. --> + </#list> + 5. ${x} <#-- now we see the local var. again --> +</#macro></pre></div> + +<div class="code-wrapper"><pre class="code-block code-output">1. plain + 2. plain + 3. local + 4. loop + 5. local +6. plain + 7. loop + 8. loop +9. plain2 </pre></div><p>In the next example we demonstrate that an inner loop variable + can hide (not overwrite) an outer loop variable of the same + name:</p> + +<div class="code-wrapper"><pre class="code-block code-template"><#list ["loop 1"] as x> + ${x} + <#list ["loop 2"] as x> + ${x} + <#list ["loop 3"] as x> + ${x} + </#list> + ${x} + </#list> + ${x} +</#list></pre></div> + +<div class="code-wrapper"><pre class="code-block code-output"> loop 1 + loop 2 + loop 3 + loop 2 + loop 1</pre></div><p>When a variable hides the variable from the data-model, you can + still read that variable from the data-model using <a href="dgui_template_exp.html#dgui_template_exp_var_special">special variable</a> + <code class="inline-code">globals</code>. For example, assume we have a variable + called <code class="inline-code">user</code> in the data-model with value "Big + Joe":</p> + +<div class="code-wrapper"><pre class="code-block code-template">${user} <#-- prints: Big Joe --> +<#assign user = "Joe Hider"> +${user} <#-- prints: Joe Hider --> +${.globals.user} <#-- prints: Big Joe --></pre></div><p>You could also write <code class="inline-code">.data_model.user</code> + instead, and then not even a <code class="inline-code"><#global user = + "<em class="code-color">...</em>"></code> can hide the value in + the data-model. However, global variables are often purposely set to + override the value coming from the data-model, so using + <code class="inline-code">globals</code> is a better practice usually.</p><p>For information about syntax of variables (allowed characters + and such) please read: <a href="dgui_template_exp.html">The Template/Expressions</a></p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_misc_userdefdir.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_namespace.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_misc_whitespace.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_misc_whitespace.html b/builds/2.3.26-nightly/dgui_misc_whitespace.html new file mode 100644 index 0000000..6a8032a --- /dev/null +++ b/builds/2.3.26-nightly/dgui_misc_whitespace.html @@ -0,0 +1,296 @@ +<!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>White-space handling - 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="White-space handling"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_misc_whitespace.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_misc_whitespace.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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itempro p="itemListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="dgui_misc_whitespace.html"><span itemprop="name">White-space handling</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","Miscellaneous","White-space handling"];</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_misc_autoescaping.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_alternativesyntax.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="dgui_misc_whitespace" itemprop="headline">White-space handling</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#dgui_misc_whitespace_stripping" data-menu-target="dgui_misc_whitespace_stripping">White-space stripping</a></li><li><a class="page-menu-link" href="#autoid_30" data-menu-target="autoid_30">Using compress directive</a></li></ul> </div><p>The control of the <a href="gloss.html#gloss.whiteSpace">white-space</a> in a template is a + problem that to some extent haunts every template engine in the + business.</p><p>Let see this template. I have marked the components of template + with colors: <span class="marked-text">text</span>, <span class="marked-interpolation">interpolation</span>, <span class="marked-ftl-tag">FTL tag</span>. With the <em><span class="marked-invisible-text">[BR]</span></em>-s I visualize the <a href="gloss.html#gloss.lineBreak">line breaks</a>.</p> + +<div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-ftl-tag"><#assign users = [{"name":"Joe", "hidden":false},<em><span class="marked-invisible-text">[BR]</span></em> + {"name":"James Bond", "hidden":true},<em><span class="marked-invisible-text">[BR]</span></em> + {"name":"Julia", "hidden":false}]></span><em><span class="marked-invisible-text">[BR]</span></em> +<ul><em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-ftl-tag"><#list users as user></span><em><span class="marked-invisible-text">[BR]</span></em> + <span class="marked-ftl-tag"><#if !user.hidden></span><em><span class="marked-invisible-text">[BR]</span></em> + <li><span class="marked-interpolation">${user.name}</span><em><span class="marked-invisible-text">[BR]</span></em> + <span class="marked-ftl-tag"></#if></span><em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-ftl-tag"></#list></span><em><span class="marked-invisible-text">[BR]</span></em> +</ul><em><span class="marked-invisible-text">[BR]</span></em> +<p>That's all.</span></pre></div><p>If FreeMarker were to output all <span class="marked-text">text</span> as is, the output would be:</p> + +<div class="code-wrapper"><pre class="code-block code-output"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em> +<em><span class="marked-invisible-text">[BR]</span></em> +<ul><em><span class="marked-invisible-text">[BR]</span></em> +<em><span class="marked-invisible-text">[BR]</span></em> + <em><span class="marked-invisible-text">[BR]</span></em> + <li></span>Joe<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> + <em><span class="marked-invisible-text">[BR]</span></em> +<em><span class="marked-invisible-text">[BR]</span></em> + <em><span class="marked-invisible-text">[BR]</span></em> +<em><span class="marked-invisible-text">[BR]</span></em> + <em><span class="marked-invisible-text">[BR]</span></em> + <li></span>Julia<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> + <em><span class="marked-invisible-text">[BR]</span></em> +<em><span class="marked-invisible-text">[BR]</span></em> +</ul><em><span class="marked-invisible-text">[BR]</span></em> +<p>That's all.</span></pre></div><p>You have a lot of unwanted spaces and line breaks here. + Fortunately neither HTML nor XML is typically white-space sensitive, + but this amount of superfluous white-space can be annoying, and + needlessly increases the size of produced HTML. Of course, it is even + bigger problem when outputting white-space-sensitive formats.</p><p>FreeMarker provides the following tools to cope with this + problem:</p><ul> + <li> + <p>Tools to ignore certain white-space of the template files + <span class="marked-for-programmers">(parse time white-space + removal)</span>:</p> + + <ul> + <li> + <p>White-space stripping: This feature automatically + ignores typical superfluous white-space around FTL tags. It + can be enabled or disabled on per template manner.</p> + </li> + + <li> + <p>Trimmer directives: <code class="inline-code">t</code>, + <code class="inline-code">rt</code>, <code class="inline-code">lt</code>. With these + directives you can explicitly tell FreeMarker to ignore + certain white-space. Read <a href="ref_directive_t.html#ref.directive.t">the + reference</a> for more information.</p> + </li> + + <li> + <p><a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code></a> + parameter <code class="inline-code">strip_text</code>: This removes all + top-level text from the template. It is useful for templates + that contain macro definitions only (and some other + non-outputting directives), because it removes the line-breaks + that you use between the macro definitions and between the + other top-level directives to improve the readability of the + template.</p> + </li> + </ul> + </li> + + <li> + <p>Tools that remove white-space from the output <span class="marked-for-programmers">(on-the-fly white-space + removal)</span>:</p> + + <ul> + <li> + <p><code class="inline-code">compress</code> directive.</p> + </li> + </ul> + </li> + </ul> + + + + +<h2 class="content-header header-section2" id="dgui_misc_whitespace_stripping">White-space stripping</h2> + + + + + <p>If this feature is enabled for a template, then it + automatically ignores (i.e. does not print to the output) two kind + of typical superfluous white-space:</p> + + <ul> + <li> + <p>Indentation white-space, and trailing white-space at the + end of the line (includes the line break) will be ignored in + lines that contains only FTL tags (e.g. + <code class="inline-code"><@myMacro/></code>, <code class="inline-code"><#if + <em class="code-color">...</em>></code>) and/or FTL + comments (e.g. <code class="inline-code"><#-- blah --></code>), apart + from the the ignored white-space itself. For example, if a line + contains only an <code class="inline-code"><#if + <em class="code-color">...</em>></code>, then the + indentation before the tag and the line break after the tag will + be ignored. However, if the line contains <code class="inline-code"><#if + <em class="code-color">...</em>>x</code>, then the + white-space in that line will not be ignored, because of the + <code class="inline-code">x</code>, as that is not FTL tag. Note that + according these rules, a line that contains <code class="inline-code"><#if + <em class="code-color">...</em>><#list + <em class="code-color">...</em>></code> is subject to + white-space ignoring, while a line that contains + <code class="inline-code"><#if <em class="code-color">...</em>> <#list + <em class="code-color">...</em>></code> is not, because the + white-space between the two FTL tags is embedded white-space, + not indentation or trailing white-space.</p> + </li> + + <li> + <p>White-space sandwiched between the following directives is + ignored: <code class="inline-code">macro</code>, <code class="inline-code">function</code>, + <code class="inline-code">assign</code>, <code class="inline-code">global</code>, + <code class="inline-code">local</code>, <code class="inline-code">ftl</code>, + <code class="inline-code">import</code>, but only if there is + <em>only</em> white-space and/or FTL comments + between the directives. In practice it means that you can put + empty lines between macro definitions and assignments as spacing + for better readability, without printing needless empty lines + (line breaks) to the output.</p> + </li> + </ul> + + <p>The output of the last example with white-space stripping + enabled will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em> +<ul><em><span class="marked-invisible-text">[BR]</span></em> + <li></span>Joe<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> + <li></span>Julia<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> +</ul><em><span class="marked-invisible-text">[BR]</span></em> +<p>That's all.</span></pre></div> + + <p>This is because after stripping the template becomes the + following; the ignored text is not <span class="marked-text">colored</span>:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em></span> +<span class="marked-ftl-tag"><#assign users = [{"name":"Joe", "hidden":false},<em><span class="marked-invisible-text">[BR]</span></em> + {"name":"James Bond", "hidden":true},<em><span class="marked-invisible-text">[BR]</span></em> + {"name":"Julia", "hidden":false}]></span><em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-text"><ul><em><span class="marked-invisible-text">[BR]</span></em></span> +<span class="marked-ftl-tag"><#list users as user></span><em><span class="marked-invisible-text">[BR]</span></em> + <span class="marked-ftl-tag"><#if !user.hidden></span><em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-text"> <li><span class="marked-interpolation">${user.name}</span><em><span class="marked-invisible-text">[BR]</span></em></span> + <span class="marked-ftl-tag"></#if></span><em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-ftl-tag"></#list></span><em><span class="marked-invisible-text">[BR]</span></em> +<span class="marked-text"></ul><em><span class="marked-invisible-text">[BR]</span></em> +<p>That's all.</span></pre></div> + + <p>White-space stripping can be enabled/disabled in per template + manner with the <a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code> directive</a>. + If you don't specify this with the <code class="inline-code">ftl</code> directive, + then white-space stripping will be enabled or disabled depending on + how the programmer has configured FreeMarker. The factory default is + white-space stripping enabled, and the programmers probably left it + so (<span class="marked-for-programmers">recommended</span>). <span class="marked-for-programmers">Note that enabling white-space stripping does + <em>not</em> degrade the performance of template + execution; white-space stripping is done during template + loading.</span></p> + + <p>White-space stripping can be disabled for a single line with + the <a href="ref_directive_nt.html#ref.directive.nt"><code>nt</code></a> + directive (for No Trim).</p> + + + + + +<h2 class="content-header header-section2" id="autoid_30">Using compress directive</h2> + + + + + <p>Another solution is to use the <a href="ref_directive_compress.html#ref.directive.compress"><code>compress</code> + directive</a>. As opposed to white-space stripping, this works + directly on the generated output, not on the template. That is, it + will investigate the printed output on the fly, and does not + investigate the FTL program that creates the output. It aggressively + removes indentations, empty lines and repeated spaces/tabs (for more + information read the <a href="ref_directive_compress.html#ref.directive.compress">reference</a>). So the output + of:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><strong><#compress></strong> +<#assign users = [{"name":"Joe", "hidden":false}, + {"name":"James Bond", "hidden":true}, + {"name":"Julia", "hidden":false}]> +List of users: +<#list users as user> + <#if !user.hidden> + - ${user.name} + </#if> +</#list> +That's all. +<strong></#compress></strong></pre></div> + + <p>will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">List of users: +- Joe +- Julia +That's all.</pre></div> + + <p>Note that <code class="inline-code">compress</code> is totally independent + of white-space stripping. So it is possible that the white-space of + template is stripped, and later the produced output is + <code class="inline-code">compress</code>-ed.</p> + + <p>Also, by default a user-defined directve called + <code class="inline-code">compress</code> is available in the data-model (due to + backward compatibility). This is the same as the directive, except + that you may optionally set the <code class="inline-code">single_line</code> + parameter, which will remove all intervening line breaks. If you + replace + <code class="inline-code"><#compress><em class="code-color">...</em></#compress></code> + on the last example with <code class="inline-code"><@compress + single_line=true><em class="code-color">...</em></@compress></code>, + then you get this output:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">List of users: - Joe - Julia That's all.</pre></div> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_misc_autoescaping.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc_alternativesyntax.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.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/dgui_quickstart.html b/builds/2.3.26-nightly/dgui_quickstart.html new file mode 100644 index 0000000..dacd07b --- /dev/null +++ b/builds/2.3.26-nightly/dgui_quickstart.html @@ -0,0 +1,57 @@ +<!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>Getting Started with template writing - 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="Getting Started with template writing"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/dgui_quickstart.html";> +<link rel="canonical" href="http://freemarker.org/docs/dgui_quickstart.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></ul><div class="b ookmarks" 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"];</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.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_quickstart_basics.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-chapter" id="dgui_quickstart" itemprop="headline">Getting Started</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Section Contents</div> +<ul><li><a class="page-menu-link" href="dgui_quickstart_basics.html" data-menu-target="dgui_quickstart_basics">Template + data-model = output</a></li><li><a class="page-menu-link" href="dgui_quickstart_datamodel.html" data-menu-target="dgui_quickstart_datamodel">The data-model at a glance</a></li><li><a class="page-menu-link" href="dgui_quickstart_template.html" data-menu-target="dgui_quickstart_template">The template at a glance</a></li></ul> </div><p>This chapter is a very rough introduction to FreeMarker. The + chapters after this will go over things in much greater detail. + Nonetheless, once you have read this chapter, you will be able to write + simple but useful FreeMarker templates.</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_quickstart_basics.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>
