Repository: incubator-freemarker-site Updated Branches: refs/heads/asf-site 1d3015292 -> a24e40d55
Release preview Manual: More clear description of the square bracket syntaxes. Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/commit/a24e40d5 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/tree/a24e40d5 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/diff/a24e40d5 Branch: refs/heads/asf-site Commit: a24e40d55105139cc9937566790938ec6bef127c Parents: 1d30152 Author: ddekany <ddek...@apache.org> Authored: Sat Mar 24 15:45:36 2018 +0100 Committer: ddekany <ddek...@apache.org> Committed: Sat Mar 24 15:45:36 2018 +0100 ---------------------------------------------------------------------- .../fm2.3.28/dgui_misc_alternativesyntax.html | 128 +++++++++++++------ 1 file changed, 88 insertions(+), 40 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a24e40d5/builds/fm2.3.28/dgui_misc_alternativesyntax.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/dgui_misc_alternativesyntax.html b/builds/fm2.3.28/dgui_misc_alternativesyntax.html index 9d744ed..e274f83 100644 --- a/builds/fm2.3.28/dgui_misc_alternativesyntax.html +++ b/builds/fm2.3.28/dgui_misc_alternativesyntax.html @@ -56,14 +56,30 @@ under the License. <h1 class="content-header header-section1" id="dgui_misc_alternativesyntax" itemprop="headline">Alternative (square bracket) syntax</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_alternativesyntax_tag" data-menu-target="dgui_misc_alternativesyntax_tag">Square bracket tag syntax</a></li><li><a class="page-menu-link" href="#dgui_misc_alternativesyntax_interpolation" data-menu-target="dgui_misc_alternativesyntax_interpolation">Square bracket interpolation syntax</a></li></ul> </div><p>Both FreeMarker tags (such as <code class="inline-code"><#if x></code>) - and FreeMarker interpolations (such as <code class="inline-code">${x}</code>) can be - set <em>independently</em> to use so called square bracket - syntax (<code class="inline-code">[#if x]</code>, and <code class="inline-code">[=x]</code>, - respectively). This is mostly useful to prevent clashes with the - generated content (such as when generating JSP files), or to work - around cases where some other tool is confused by the default - symbols.</p> +<ul><li><a class="page-menu-link" href="#dgui_misc_alternativesyntax_tag" data-menu-target="dgui_misc_alternativesyntax_tag">Square bracket tag syntax</a></li><li><a class="page-menu-link" href="#dgui_misc_alternativesyntax_interpolation" data-menu-target="dgui_misc_alternativesyntax_interpolation">Square bracket interpolation syntax</a></li></ul> </div><p>Sometimes the generated content uses symbols that clashes with + the default FreeMarker syntax (typically, + <code class="inline-code">${<em class="code-color">...</em>}</code>-s that FreeMarker + should print as is, without interpretation), or you use some tool that + is confused by the default FreeMarker syntax (typically by + <code class="inline-code"><</code> and <code class="inline-code">></code>). While usually + there are tricks to work those cases around (like you can use + <code class="inline-code">${'$'}{x}</code> to print <code class="inline-code">${x}</code> as is) , + they are often too inconvenient. Thus, the interpolation syntax can be + configured to be like <code class="inline-code">[=x]</code> instead of + <code class="inline-code">${x}</code>. Also, independently of that, the FreeMarker + tag syntax can be configured to use <code class="inline-code">[]</code>, like in + <code class="inline-code">[#if x]<em class="code-color">...</em>[/#if]</code>. + </p> <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>While both the "tag syntax" and + "interpolation syntax" can be configured to use square + brackets, they are totally independent configuration settings. Thus, + the overall syntax can be like <code class="inline-code">[#if x]${y}[/#if]</code>, + or like <code class="inline-code"><#if x>[=y]</#if></code> as + well.</p> + </div> + @@ -74,6 +90,15 @@ under the License. <div class="callout note"> <strong class="callout-label">Note:</strong> + <p>This section is about the <em>tag</em> syntax, + not the <a href="#dgui_misc_alternativesyntax_interpolation"><em>interpolation</em> + syntax</a>. Don't confuse the two, they are independent.</p> + </div> + + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + <p>This feature exists since FreeMarker 2.3.4.</p> </div> @@ -99,8 +124,8 @@ under the License. </li> </ul> - <p>To use the alternative tag syntax instead of the default one, - the programmers should configure FreeMarker so <span class="marked-for-programmers">(see + <p>To use square tag syntax instead of the default one, the + programmers should configure FreeMarker so <span class="marked-for-programmers">(see <code class="inline-code">Configuraton.setTagSyntax</code>, or the <code class="inline-code">tag_syntax</code> setting)</span>. However, the tag syntax can also be enforced in the template, with the <a href="ref_directive_ftl.html"><code>ftl</code> directive</a> @@ -124,33 +149,31 @@ under the License. <strong>[/#list]</strong> </table></pre></div> - <p>The alternative (square bracket) and the default (angle - bracket) syntax are mutually exclusive within a template. That is, - either the whole template uses square bracket tag syntax, or the - whole template uses the angle bracket tag syntax. If the template - uses square bracket tag syntax, then things like <code class="inline-code"><#if - <em class="code-color">...</em>></code> are count as static - text, not as FTL tags. Similarly, if the template uses the angle - brackets tag syntax, things like <code class="inline-code">[#if - <em class="code-color">...</em>]</code> count as static text, not - as FTL tags.</p> + <p>The square bracket and the default (angle bracket) syntax are + mutually exclusive within a template; they can't be mixed. If the + template uses square bracket tag syntax, then things like + <code class="inline-code"><#if <em class="code-color">...</em>></code> will + be just static text, not FTL tags. Similarly, if the template uses + the angle brackets tag syntax, things like <code class="inline-code">[#if + <em class="code-color">...</em>]</code> are static text, not FTL + tags.</p> <p>If you start the file with <code class="inline-code">[#ftl <em class="code-color">...</em>]</code> (where the <code class="inline-code"><em class="code-color">...</em></code> stands for the optional parameters; of course <code class="inline-code">[#ftl]</code> works too) - the file will surely use the square bracket syntax. If you start the - file with <code class="inline-code"><#ftl - <em class="code-color">...</em>></code> the file will surely - use the normal (angle bracket) syntax. If there is no + the file will use square bracket <em>tag</em> syntax + regardless of the configuration settings (but that does + <em>not</em> change the interpolation syntax to + <code class="inline-code">[=...]</code>). Similarly, if you start the file with + <code class="inline-code"><#ftl <em class="code-color">...</em>></code> the + file will use the normal (angle bracket) tag syntax. If there is no <code class="inline-code">ftl</code> directive in the file, then the programmer - decides what the syntax will be by configuring FreeMarker <span class="marked-for-programmers">(programmers see - <code class="inline-code">Configuration.setTagSyntax(int)</code> in the API + decides what the tag <em>syntax</em> will be by + configuring FreeMarker <span class="marked-for-programmers">(programmers + see <code class="inline-code">Configuration.setTagSyntax(int)</code> in the API javadocs)</span>. Most probably the programmers use the factory - default however. The factory default in 2.3.x is using the normal - syntax. The factory default in 2.4.x will be auto-detection, which - means that the first FreeMarker tag determines the syntax (it can be - anything, not just <code class="inline-code">ftl</code>).</p> + default.</p> @@ -162,27 +185,42 @@ under the License. <div class="callout note"> <strong class="callout-label">Note:</strong> + <p>This section is about the <em>interpolation</em> + syntax, not the <a href="#dgui_misc_alternativesyntax_tag"><em>tag</em> + syntax</a>. Don't confuse the two, they are independent.</p> + </div> + + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + <p>This feature exists since FreeMarker 2.3.28</p> </div> <p>In this case instead of - <code class="inline-code">${<em class="code-color">expression</em>}</code> (and + <code class="inline-code">${<em class="code-color">expression</em>}</code> (and the + deprecated <code class="inline-code">#{<em class="code-color">expression</em>}</code>) you write <code class="inline-code">[=<em class="code-color">expression</em>]</code>. - This syntax is usually activated by the programmers from the - configuration <span class="marked-for-programmers">(see + This syntax is activated by the programmers from the configuration + <span class="marked-for-programmers">(see <code class="inline-code">Configuration.setInterpolationSyntax</code> in the Java - API)</span>. It can be used both together with, and without the - square bracket <em>tag</em> syntax (see that in the - <a href="#dgui_misc_alternativesyntax_tag">previous - section</a>), although it's more likely to be used together with - it. Assuming both interpolation and tag syntax was set to square - bracket, the earlier example template will look like this:</p> + API)</span>; unlike the tag syntax, it can't be specified inside + the template. It can be used both together with, and without the + <a href="#dgui_misc_alternativesyntax_tag">square bracket + <em>tag</em> syntax</a>, as they are technically + unrelated, but it's probably more aesthetic to use square bracket + tag syntax when you use square bracket interpolation syntax:</p> -<div class="code-wrapper"><pre class="code-block code-template"><p>We have these animals: +<div class="code-wrapper"><pre class="code-block code-template">[#-- + Note: + This example uses both interpolation_syntax=squareBracket and tag_syntax=squareBracket, + but you can also use interpolation_syntax=squareBracket and tag_syntax=angleBracket. +--] +<p>We have these animals: <table border=1> <tr><th>Name<th>Price [#list animals as animal] @@ -203,6 +241,16 @@ under the License. (especially <code class="inline-code">${<em class="code-color">expression</em>}</code> is frequent), such as when generating JSP files.</p> + + <p>There's also a third tag syntax, "dollar", where + only the interpolation syntax is + <code class="inline-code">${<em class="code-color">expression</em>}</code>, and the + deprecated + <code class="inline-code">#{<em class="code-color">expression</em>}</code> is just + static text. (The one where + <code class="inline-code">#{<em class="code-color">expression</em>}</code> is still + an interpolation is called the "legacy" interpolation + syntax, and is the default for backward compatibility.)</p> <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_misc_whitespace.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui.html"><span>Next</span></a></div></div></div></div> </div> </div> <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/";>What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="https://freemarker.apache.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://try.freemarker.org/";>Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><u l><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="https://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="https://freemarker.apache.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="https://stackoverflow.com/questions/ask?tags=freemarker";>Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/"; rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated">
