You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2018/03/24 14:46:21 UTC
incubator-freemarker-site git commit: Release preview Manual: More
clear description of the square bracket syntaxes.
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 <dd...@apache.org>
Authored: Sat Mar 24 15:45:36 2018 +0100
Committer: ddekany <dd...@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">