http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a4004324/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 deleted file mode 100644 index 1cdb47b..0000000 --- a/builds/2.3.26-nightly/dgui_misc_userdefdir.html +++ /dev/null @@ -1,554 +0,0 @@ -<!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/a4004324/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 deleted file mode 100644 index 1f48d80..0000000 --- a/builds/2.3.26-nightly/dgui_misc_var.html +++ /dev/null @@ -1,197 +0,0 @@ -<!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/a4004324/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 deleted file mode 100644 index 6a8032a..0000000 --- a/builds/2.3.26-nightly/dgui_misc_whitespace.html +++ /dev/null @@ -1,296 +0,0 @@ -<!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/a4004324/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 deleted file mode 100644 index dacd07b..0000000 --- a/builds/2.3.26-nightly/dgui_quickstart.html +++ /dev/null @@ -1,57 +0,0 @@ -<!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>
