Repository: incubator-freemarker-site Updated Branches: refs/heads/asf-site b8b70b722 -> ad3a793e6
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/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 d489244..9d744ed 100644 --- a/builds/fm2.3.28/dgui_misc_alternativesyntax.html +++ b/builds/fm2.3.28/dgui_misc_alternativesyntax.html @@ -54,40 +54,64 @@ under the License. </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_whitespace.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui.html"><span>Next</span></a></div><div class="title-wrapper"> <h1 class="content-header header-section1" id="dgui_misc_alternativesyntax" itemprop="headline">Alternative (square bracket) syntax</h1> -</div></div> <div class="callout note"> +</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> + + + + +<h2 class="content-header header-section2" id="dgui_misc_alternativesyntax_tag">Square bracket tag syntax</h2> + + + <div class="callout note"> <strong class="callout-label">Note:</strong> - <p>This feature exists since FreeMarker 2.3.4.</p> - </div> -<p>FreeMarker supports an alternative syntax, where - <code class="inline-code">[</code> and <code class="inline-code">]</code> is used instead of - <code class="inline-code"><</code> and <code class="inline-code">></code> in FreeMarker - directives and comments, for example:</p><ul> - <li> - Calling predefined directive: <code class="inline-code">[#list animals as - animal]<em class="code-color">...</em>[/#list]</code> - </li> - - <li> - Calling user-defined directive: <code class="inline-code">[@myMacro - /]</code> - </li> - - <li> - Comment: <code class="inline-code">[#-- the comment --]</code> - </li> - </ul><p>To use the alternative syntax instead of the default one, start - the template with the <a href="ref_directive_ftl.html"><code>ftl</code> directive</a> - using the alternative syntax. If you don't know what is the - <code class="inline-code">ftl</code> directive, just start the template with - <code class="inline-code">[#ftl]</code>, and remember that it should be the very - first thing in the file (except that <a href="gloss.html#gloss.whiteSpace">white-space</a> can precede it). For - example, this is how the last example of the <a href="dgui_quickstart_template.html">Getting Started</a> looks with - the alternative syntax (assuming it's a complete template, not just a - fragment):</p> - -<div class="code-wrapper"><pre class="code-block code-template"><strong>[#ftl]</strong> -<p>We have these animals: + <p>This feature exists since FreeMarker 2.3.4.</p> + </div> + + + <p>FreeMarker supports an alternative tag syntax, where + <code class="inline-code">[</code> and <code class="inline-code">]</code> is used instead of + <code class="inline-code"><</code> and <code class="inline-code">></code> in FreeMarker + directives and comments, for example:</p> + + <ul> + <li> + Calling predefined directive: <code class="inline-code">[#list animals as + animal]<em class="code-color">...</em>[/#list]</code> + </li> + + <li> + Calling user-defined directive: <code class="inline-code">[@myMacro + /]</code> + </li> + + <li> + Comment: <code class="inline-code">[#-- the comment --]</code> + </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 + <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> + (see later).</p> + + <p>For example, this is how the last example of the <a href="dgui_quickstart_template.html">Getting Started</a> looks with + the alternative syntax:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><p>We have these animals: <table border=1> <tr><th>Name<th>Price <strong>[#list animals as animal]</strong> @@ -98,30 +122,88 @@ under the License. <strong>[#if animal.size == "large"]</strong></b><strong>[/#if]</strong> <td>${animal.price} Euros <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 alternative syntax, or the whole template uses the - default syntax. If the template uses alternative syntax, 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 default syntax, things like <code class="inline-code">[#if - <em class="code-color">...</em>]</code> count as static text, not as - 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 alternative (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 - <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 - 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><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> +</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>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 + <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 + 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> + + + + + +<h2 class="content-header header-section2" id="dgui_misc_alternativesyntax_interpolation">Square bracket interpolation syntax</h2> + + + <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>) 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 + <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> + + + +<div class="code-wrapper"><pre class="code-block code-template"><p>We have these animals: +<table border=1> + <tr><th>Name<th>Price + [#list animals as animal] + <tr> + <td> + [#if animal.size == "large"]<b>[/#if] + <strong>[=animal.name]</strong> + [#if animal.size == "large"]</b>[/#if] + <td><strong>[=animal.price]</strong> Euros + [/#list] +</table></pre></div> + + <p>When square bracket interpolation syntax is used, + <code class="inline-code">${<em class="code-color">expression</em>}</code> and + <code class="inline-code">#{<em class="code-color">expression</em>}</code> in the + template will be just static text, which is printed as is. This is + mostly useful if you generate output that should contain those + (especially + <code class="inline-code">${<em class="code-color">expression</em>}</code> is + frequent), such as when generating JSP files.</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"> Last generated: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/dgui_template_exp.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/dgui_template_exp.html b/builds/fm2.3.28/dgui_template_exp.html index 68e0e6a..a1bfc3d 100644 --- a/builds/fm2.3.28/dgui_template_exp.html +++ b/builds/fm2.3.28/dgui_template_exp.html @@ -402,6 +402,16 @@ this is a backslash: \</pre></div> <tr> + <td><code class="inline-code">\=</code></td> + + + <td>Equals character: <code class="inline-code">=</code> (Supported since + FreeMarker 2.3.28.)</td> + + </tr> + + + <tr> <td><code class="inline-code">\\</code></td> @@ -506,14 +516,19 @@ this is a backslash: \</pre></div> digit, you must use all 4 digits or else FreeMarker will misunderstand you.</p> - <p>Note that the character sequence <code class="inline-code">${</code> (and - <code class="inline-code">#{</code>) has special meaning. It's used to insert - the value of expressions (typically: the value of variables, as in - <code class="inline-code">"Hello ${user}!"</code>). This will be explained <a href="#dgui_template_exp_stringop_interpolation">later</a>. + <p>Note that the character sequence <code class="inline-code">${</code> and + <code class="inline-code">#{</code> (and rarely <code class="inline-code">[=</code> instead, + depending on <a href="dgui_misc_alternativesyntax.html">the + configured syntax</a>) has special meaning. They are used to + insert the value of expressions (typically: the value of + variables, as in <code class="inline-code">"Hello ${user}!"</code>). This will + be explained <a href="#dgui_template_exp_stringop_interpolation">later</a>. If you want to print <code class="inline-code">${</code> or - <code class="inline-code">#{</code>, you should either use raw string literals - as explained below, or escape the <code class="inline-code">{</code> like in - <code class="inline-code">"foo $\{bar}"</code>.</p> + <code class="inline-code">#{</code> (or <code class="inline-code">[=</code>), you should + either use raw string literals as explained below, or escape the + <code class="inline-code">{</code> like in <code class="inline-code">"foo $\{bar}"</code> (or + the <code class="inline-code">=</code> like in <code class="inline-code">"foo + [\=bar]"</code>).</p> @@ -990,6 +1005,17 @@ baz sections</a> (so it goes through the same <em>locale sensitive</em> number and date/time formatting).</p> + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>It's possible to configure FreeMarker's interpolation + syntax to use + <code class="inline-code">[=<em class="code-color">...</em>]</code> instead; + <a href="dgui_misc_alternativesyntax.html#dgui_misc_alternativesyntax_interpolation">see + here</a>.</p> + </div> + + <p>Example (assume that user is "Big Joe"):</p> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/dgui_template_valueinsertion.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/dgui_template_valueinsertion.html b/builds/fm2.3.28/dgui_template_valueinsertion.html index 29a08d8..3af74ad 100644 --- a/builds/fm2.3.28/dgui_template_valueinsertion.html +++ b/builds/fm2.3.28/dgui_template_valueinsertion.html @@ -69,6 +69,16 @@ under the License. <code class="inline-code"><em class="code-color">expression</em></code> can be all kind of expression (e.g. <code class="inline-code">${100 + x}</code>).</p> + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>FreeMarker can be configured to use + <code class="inline-code">[=<em class="code-color">expression</em>]</code> syntax + instead. <a href="dgui_misc_alternativesyntax.html">See more + about alternative syntaxes...</a></p> + </div> + + <p>The interpolation is used to insert the value of the <code class="inline-code"><em class="code-color">expression</em></code> converted to text (to string). Interpolations can be used only on two places: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/pgui_config_incompatible_improvements.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/pgui_config_incompatible_improvements.html b/builds/fm2.3.28/pgui_config_incompatible_improvements.html index 5db1cc5..01d0cc3 100644 --- a/builds/fm2.3.28/pgui_config_incompatible_improvements.html +++ b/builds/fm2.3.28/pgui_config_incompatible_improvements.html @@ -70,16 +70,20 @@ under the License. implemented. Usually, it's a bad idea to left it on its default, which is 2.3.0 (maximum backward compatibility).</p> - <p>In new projects you should set this to the FreeMarker version - that you are actually using. In older projects it's also usually - better to keep this high, however you better check the changes - activated (find them in <a href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-">the + <p>In new projects you should set this to the fixed FreeMarker + version (like <code class="inline-code">Configuration.VERSION_2_3_28</code>) that + you are actually using when starting the project. In older projects + it's also usually better to keep this high , however you should + check the changes activated (find them in <a href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-">the API JavaDoc of the <code>Configuration(Version)</code> - constructor</a>), at least if not only the 3rd version number + constructor</a>), especially if not only the 3rd version number (the micro version) of "incompatible improvements" setting is increased. Generally, as far as you only increase the - last version number of this setting, the changes are low - risk.</p> + last (3rd) version number of this setting, the changes are low risk, + and whether you can afford that risk depends on the concrete + application. Never use a dynamic value like + <code class="inline-code">Configuration.getVersion()</code> though, as that way + upgrading FreeMarker can break your application!</p> <p>Bug fixes and improvements that are fully backward compatible, also those that are important security fixes, are enabled regardless @@ -112,7 +116,7 @@ under the License. -<div class="code-wrapper"><pre class="code-block code-unspecified">... = new Configuration(Configuration.VERSION_2_3_27)</pre></div> +<div class="code-wrapper"><pre class="code-block code-unspecified">... = new Configuration(Configuration.VERSION_2_3_28)</pre></div> </li> <li> @@ -121,7 +125,7 @@ under the License. -<div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_27)</pre></div> +<div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_28)</pre></div> </li> <li> @@ -131,7 +135,7 @@ under the License. -<div class="code-wrapper"><pre class="code-block code-unspecified">incompatible_improvements=2.3.27</pre></div> +<div class="code-wrapper"><pre class="code-block code-unspecified">incompatible_improvements=2.3.28</pre></div> </li> <li> @@ -144,7 +148,7 @@ under the License. <div class="code-wrapper"><pre class="code-block code-unspecified"><init-param> <param-name>incompatible_improvements</param-name> - <param-value>2.3.27</param-value> + <param-value>2.3.28</param-value> </init-param></pre></div> </li> </ul> @@ -175,6 +179,20 @@ under the License. <code class="inline-code">DefaultObjectWrapper</code> (for <code class="inline-code">BeansWrapper</code> it's the same, only with different class name of course).</p> + + <div class="callout warning"> + <strong class="callout-label">Warning!</strong> + + <p>Do not ever use + <code class="inline-code">Configuration.getVersion()</code> to set the + "incompatible improvements" setting. Always use a + fixed value, like <code class="inline-code">Configuration.VERSION_2_3_28</code>. + Otherwise your application can break as you upgrade FreeMarker. + The whole point of "incompatible improvements" is to + protect you from that, while you still always get the + fixes/improvements that are backward compatible.</p> + </div> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_config_custom_formats.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc.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"> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/ref_builtins_alphaidx.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_builtins_alphaidx.html b/builds/fm2.3.28/ref_builtins_alphaidx.html index a01a72d..48d2f1e 100644 --- a/builds/fm2.3.28/ref_builtins_alphaidx.html +++ b/builds/fm2.3.28/ref_builtins_alphaidx.html @@ -331,6 +331,14 @@ under the License. </li> <li> + <a href="ref_builtins_sequence.html#ref_builtin_min_max">max</a> + </li> + + <li> + <a href="ref_builtins_sequence.html#ref_builtin_min_max">min</a> + </li> + + <li> <a href="ref_builtins_expert.html#ref_builtin_namespace">namespace</a> </li> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/ref_builtins_number.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_builtins_number.html b/builds/fm2.3.28/ref_builtins_number.html index cf570b1..5e8f8d0 100644 --- a/builds/fm2.3.28/ref_builtins_number.html +++ b/builds/fm2.3.28/ref_builtins_number.html @@ -523,6 +523,16 @@ German people write: 12.345.678,00</pre></div> + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>You need at least FreeMarker 2.3.24 for these to work. + Before that, extended Java decimal format parts are just + silently ignored by + <code class="inline-code">java.text.DecimalFormat</code>.</p> + </div> + + <p>FreeMarker extends the Java decimal format patterns with extra options. These options are name-value pairs, specified after two semicolons (<code class="inline-code">;;</code>) at the end of the format @@ -540,6 +550,17 @@ Extended decimal format: ${10002.5?string[",000<strong>;; roundingMode=half <div class="code-wrapper"><pre class="code-block code-output">Standard decimal format: 10,002 Extended decimal format: 10<strong>_</strong>00<strong>3</strong></pre></div> + <div class="callout warning"> + <strong class="callout-label">Warning!</strong> + + <p>A very easy mistake to make is just using a single + semicolon instead of two. It won't even result in an error, as + <code class="inline-code">java.text.DecimalFormat</code> thinks you have just + specified some weird format for negative numbers. So remember to + use two semicolons.</p> + </div> + + <p>Above, in the extended decimal format, we have specified half-up rounding mode and group separator <code class="inline-code">"_"</code>. The table of all options follows (note that these are defined by http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/ref_builtins_sequence.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_builtins_sequence.html b/builds/fm2.3.28/ref_builtins_sequence.html index c64f0bf..0ddc347 100644 --- a/builds/fm2.3.28/ref_builtins_sequence.html +++ b/builds/fm2.3.28/ref_builtins_sequence.html @@ -56,7 +56,7 @@ under the License. <h1 class="content-header header-section1" id="ref_builtins_sequence" itemprop="headline">Built-ins for sequences</h1> </div></div><div class="page-menu"> <div class="page-menu-title">Page Contents</div> -<ul><li><a class="page-menu-link" href="#ref_builtin_chunk" data-menu-target="ref_builtin_chunk">chunk</a></li><li><a class="page-menu-link" href="#ref_builtin_first" data-menu-target="ref_builtin_first">first</a></li><li><a class="page-menu-link" href="#ref_builtin_join" data-menu-target="ref_builtin_join">join</a></li><li><a class="page-menu-link" href="#ref_builtin_last" data-menu-target="ref_builtin_last">last</a></li><li><a class="page-menu-link" href="#ref_builtin_reverse" data-menu-target="ref_builtin_reverse">reverse</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_contains" data-menu-target="ref_builtin_seq_contains">seq_contains</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_index_of" data-menu-target="ref_builtin_seq_index_of">seq_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_last_index_of" data-menu-target="ref_builtin_seq_last_index_of">seq_last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_size" data -menu-target="ref_builtin_size">size</a></li><li><a class="page-menu-link" href="#ref_builtin_sort" data-menu-target="ref_builtin_sort">sort</a></li><li><a class="page-menu-link" href="#ref_builtin_sort_by" data-menu-target="ref_builtin_sort_by">sort_by</a></li></ul> </div> +<ul><li><a class="page-menu-link" href="#ref_builtin_chunk" data-menu-target="ref_builtin_chunk">chunk</a></li><li><a class="page-menu-link" href="#ref_builtin_first" data-menu-target="ref_builtin_first">first</a></li><li><a class="page-menu-link" href="#ref_builtin_join" data-menu-target="ref_builtin_join">join</a></li><li><a class="page-menu-link" href="#ref_builtin_last" data-menu-target="ref_builtin_last">last</a></li><li><a class="page-menu-link" href="#ref_builtin_min_max" data-menu-target="ref_builtin_min_max">min, max</a></li><li><a class="page-menu-link" href="#ref_builtin_reverse" data-menu-target="ref_builtin_reverse">reverse</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_contains" data-menu-target="ref_builtin_seq_contains">seq_contains</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_index_of" data-menu-target="ref_builtin_seq_index_of">seq_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_last_index_of" data-menu-target="re f_builtin_seq_last_index_of">seq_last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_size" data-menu-target="ref_builtin_size">size</a></li><li><a class="page-menu-link" href="#ref_builtin_sort" data-menu-target="ref_builtin_sort">sort</a></li><li><a class="page-menu-link" href="#ref_builtin_sort_by" data-menu-target="ref_builtin_sort_by">sort_by</a></li></ul> </div> @@ -237,6 +237,43 @@ red, green, blue. +<h2 class="content-header header-section2" id="ref_builtin_min_max">min, max</h2> + + + + + + + <p>Returns the smaller (<code class="inline-code">min</code>) or greatest + (<code class="inline-code">max</code>) item of the sequence (or collection). The + items must be either all numbers, or all date/time values of the + same kind (date-only, time-only, date-time), or else a comparison + error will occur. These are the same restrictions as for the <a href="dgui_template_exp.html#dgui_template_exp_comparison"><code><</code> and + <code>></code> operators</a>.</p> + + <p>Missing items (i.e., Java <code class="inline-code">null</code>-s) will be + silently ignored. If the sequence is empty or it only contains + missing (Java <code class="inline-code">null</code>) items, the result itself will + be missing.</p> + + <p>Example:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template">${[1, 2, 3]?min} +${[1, 2, 3]?max} +${[]?min!'-'}</pre></div> + + + +<div class="code-wrapper"><pre class="code-block code-output">1 +3 +-</pre></div> + + + + + <h2 class="content-header header-section2" id="ref_builtin_reverse">reverse</h2> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/ref_builtins_string.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_builtins_string.html b/builds/fm2.3.28/ref_builtins_string.html index e58a6bb..11d95cf 100644 --- a/builds/fm2.3.28/ref_builtins_string.html +++ b/builds/fm2.3.28/ref_builtins_string.html @@ -1532,6 +1532,10 @@ foobar</pre></div> <code class="inline-code">?split(",", "r")</code> in the last example the last <code class="inline-code">""</code> would be missing from the output.</p> + <p>If the 1st parameter is an empty string, the string will be + split to characters (since FreeMarker 2.3.28 - earlier this has only + worked with the <code class="inline-code">r</code> flag).</p> + <div class="callout note"> <strong class="callout-label">Note:</strong> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/ref_depr_numerical_interpolation.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_depr_numerical_interpolation.html b/builds/fm2.3.28/ref_depr_numerical_interpolation.html index 3bcfc10..d2254b1 100644 --- a/builds/fm2.3.28/ref_depr_numerical_interpolation.html +++ b/builds/fm2.3.28/ref_depr_numerical_interpolation.html @@ -60,7 +60,16 @@ under the License. setting</a> and <a href="ref_builtins_number.html#ref_builtin_string_for_number">the <code>string</code> built-in</a> instead. For formatting for computer audience (i.e., no localized formatting) use the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code> built-in</a> (like - <code class="inline-code"><em class="code-color">number</em>?c</code>).</p> + <code class="inline-code"><em class="code-color">number</em>?c</code>).</p><p>While by default + <code class="inline-code">#{<em class="code-color">...</em>}</code> is interpreted, + that can be disabled by setting the + <code class="inline-code">interpolation_syntax</code> configuration setting + (<code class="inline-code">Configuration.setInterpolationSyntax</code> in the Java + API) to <code class="inline-code">dollar</code>. Then + <code class="inline-code">#{<em class="code-color">...</em>}</code> will be just + static text, and only + <code class="inline-code">${<em class="code-color">...</em>}</code> will operate as + interpolation.</p> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/toc.js ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/toc.js b/builds/fm2.3.28/toc.js index ec2cb9c..5db79a7 100644 --- a/builds/fm2.3.28/toc.js +++ b/builds/fm2.3.28/toc.js @@ -823,6 +823,21 @@ var toc = { "url": "dgui_misc_alternativesyntax.html", "isFile": true, "children": [ +{ +"title": "Square bracket tag syntax", +"url": "dgui_misc_alternativesyntax.html#dgui_misc_alternativesyntax_tag", +"isFile": false, +"children": [ +] +} +, +{ +"title": "Square bracket interpolation syntax", +"url": "dgui_misc_alternativesyntax.html#dgui_misc_alternativesyntax_interpolation", +"isFile": false, +"children": [ +] +} ] } ] @@ -2110,6 +2125,14 @@ var toc = { } , { +"title": "min, max", +"url": "ref_builtins_sequence.html#ref_builtin_min_max", +"isFile": false, +"children": [ +] +} +, +{ "title": "reverse", "url": "ref_builtins_sequence.html#ref_builtin_reverse", "isFile": false, http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/versions_2_3_28.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/versions_2_3_28.html b/builds/fm2.3.28/versions_2_3_28.html index 9bd6530..65b79c8 100644 --- a/builds/fm2.3.28/versions_2_3_28.html +++ b/builds/fm2.3.28/versions_2_3_28.html @@ -96,6 +96,44 @@ under the License. </li> <li> + <p>Added new built-ins: <code class="inline-code">sequence?min</code> and + <code class="inline-code">sequence?max</code> (<a href="https://issues.apache.org/jira/browse/FREEMARKER-86">FREEMARKER-86</a>), + which return the smallest and greatest item from a list of + numbers or date/time/date-times. <a href="ref_builtins_sequence.html#ref_builtin_min_max">See more here...</a></p> + </li> + + <li> + <p>The template language can now be configured to use + <code class="inline-code">[=<em class="code-color">expression</em>]</code> + 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>, + which is very useful if you have a lot of + <code class="inline-code">${<em class="code-color">...</em>}</code> or + <code class="inline-code">#{<em class="code-color">...</em>}</code> in the text + that you are generating, and so they should be static text. See + <a href="dgui_misc_alternativesyntax.html#dgui_misc_alternativesyntax_interpolation">more + about the square bracket interpolation syntax here.</a> The + template language can also be configured to only use + <code class="inline-code">${<em class="code-color">expression</em>}</code>, and + treat + <code class="inline-code">#{<em class="code-color">expression</em>}</code> as + static text. (See the <code class="inline-code">interpolation_syntax</code> + configuration setting, or the + <code class="inline-code">Configuration.setInterpolationSyntax(int)</code> + method.)</p> + </li> + + <li> + <p>In string literals, <code class="inline-code">\=</code> is now a valid + escape sequence, resulting in a <code class="inline-code">=</code>. This is + useful when you are using the new + <code class="inline-code">[=<em class="code-color">exp</em>]</code> + interpolation syntax, which can be escaped in a string literal + like <code class="inline-code">"Literal [\=x]"</code>.</p> + </li> + + <li> <p>Bug fixed (<a href="https://issues.apache.org/jira/browse/FREEMARKER-83">FREEMARKER-83</a>); this fix is only active when <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set"><code>incomplatible_improvements</code></a> is set to 2.3.28 (or higher). When calling a macro or function @@ -108,6 +146,15 @@ under the License. evaluated in the context of the called macro or function.)</p> </li> + + <li> + <p>Bug fixed: When + <code class="inline-code"><em class="code-color">string</em>?split(<em class="code-color">separator</em>)</code> + is called with <code class="inline-code">""</code> as the argument, the string + will be split to characters now. Earlier it has thrown an + <code class="inline-code">IllegalArgumentException</code> (unless the + <code class="inline-code">r</code> flag was specified).</p> + </li> </ul> @@ -119,6 +166,69 @@ under the License. <ul> <li> + <p>Added new <code class="inline-code">ParserConfiguration</code> (such as + <code class="inline-code">Configuration</code> and + <code class="inline-code">TemplateConfiguration</code>) setting, + <code class="inline-code">interpolation_syntax</code>. It has 3 possible + values:</p> + + <ul> + <li> + <p><code class="inline-code">legacy</code> (the default): + Interpolations look like + <code class="inline-code">${<em class="code-color">...</em>}</code> or + <code class="inline-code">#{<em class="code-color">...</em>}</code>. Note + that <code class="inline-code">#{<em class="code-color">...</em>}</code> is + deprecated for a long time now.</p> + </li> + + <li> + <p><code class="inline-code">dollar</code>: Interpolations look like + <code class="inline-code">${<em class="code-color">...</em>}</code>. With + this syntax, + <code class="inline-code">#{<em class="code-color">...</em>}</code> will be + just static text.</p> + </li> + + <li> + <p><code class="inline-code">square_bracket</code>: Interpolations look + like <code class="inline-code">[=<em class="code-color">...</em>]</code>. + With this syntax + <code class="inline-code">${<em class="code-color">...</em>}</code> and + <code class="inline-code">#{<em class="code-color">...</em>}</code> will be + just static text. So it's useful if you generate output in a + format where those (typically + <code class="inline-code">${<em class="code-color">...</em>}</code>) are + already used, such as to generate JSP pages, or to generate + FreeMarker templates that use the default syntax.</p> + </li> + </ul> + </li> + + <li> + <p>When specifying the <code class="inline-code">output_format</code> + configuration settings with + <code class="inline-code">String</code>-<code class="inline-code">String</code> key-value + pairs (like with <code class="inline-code">Configuration.setSetting(String, + String)</code> or in a <code class="inline-code">.properties</code> file), + it's now possible to specify the standard output formats by name + rather than by class name (like + <code class="inline-code">output_format=HTML</code>). (Custom formats still + has to be referred by class name, as FreeMarker can't discover + what their names are, since it's not aware of the custom + classes.)</p> + </li> + + <li> + <p>Added a new + <code class="inline-code">Configuration.removeTemplateFromCache</code> + overload that has a <code class="inline-code">Object + customLookupCondition</code> parameter. This is useful to + manually evacuate a template from the cache that was get via a + non-<code class="inline-code">null</code> custom lookup condition.</p> + </li> + + <li> <p>Added new property to <code class="inline-code">BeansWrapper.MethodAppearanceDecision</code>: <code class="inline-code">replaceExistingProperty</code>. This is useful when @@ -189,6 +299,24 @@ under the License. </li> <li> + <p>The default arithmetic engine + (<code class="inline-code">ArithmeticEngine.BIGDECIMAL_ENGINE</code>) can now + compare infinite (both positive and negative) to any other + standard type. Earlier, since <code class="inline-code">BigDecimal</code> + can't represent infinite, it was only working in certain special + cases. Also did some performance optimizations to slightly + decrease the impact and number of conversions to + <code class="inline-code">BigDecimal</code>.</p> + </li> + + <li> + <p>Avoided possible performance bottleneck when executing + templates on many threads, caused be that + <code class="inline-code">java.beans.PropertyDescriptor.getReadMethod()</code> + is synchronized (<a href="https://issues.apache.org/jira/browse/FREEMARKER-80">FREEMARKER-80</a>).</p> + </li> + + <li> <p>Added <code class="inline-code">TemplateModelUtils.getKeyValuePairIterator(TemplateHashModelEx)</code> static utility class, which can be used to get a @@ -208,6 +336,43 @@ under the License. it unwraps into a <code class="inline-code">LinkedHashMap</code> instead of into a plain <code class="inline-code">HashMap</code>.</p> </li> + + <li> + <p><code class="inline-code">freemarker.ext.beans.HashAdapter.size()</code> + was overridden for better performance.</p> + </li> + + <li> + <p>When the <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set"><code>incompatible_improvements</code> + setting</a> is set to 2.3.28 (or greater), fixed legacy + parser glitch where a tag can be closed with an illegal + <code class="inline-code">]</code> (when it's not part of an expression) + despite that the tag syntax is set to angle brackets. For + example <code class="inline-code"><#if x]</code> worked just like + <code class="inline-code"><#if x></code>. Note that it doesn't affect + the legal usage of <code class="inline-code">]</code>, like <code class="inline-code"><#if + x[0]></code> works correctly without this fix as + well.</p> + </li> + + <li> + <p>Fixed parser bug that disallowed using + <code class="inline-code">></code> at the top-level inside an interpolation + (<code class="inline-code">${...}</code>). It had the same reason why + <code class="inline-code"><#if x > y></code> doesn't work as naively + expected, but there's no real ambiguity in <code class="inline-code">${x > + y}</code>, so now it's allowed. Note that <code class="inline-code">${(x > + y)?c}</code> and <code class="inline-code">${(x > y)?string('y', + 'n')}</code>, which are how booleans are commonly printed, + have always worked, as the <code class="inline-code">></code> operation is + not on the top-level inside the interpolation.</p> + </li> + + <li> + <p>Fixed incorrect listing of valid + <code class="inline-code">roundingMode</code>-s in <a href="ref_builtins_number.html#topic.extendedJavaDecimalFormat">extended Java decimal + format</a> parsing error message</p> + </li> </ul> <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="app_versions.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_27.html"><span>Next</span></a></div></div></div></div> </div> </div> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/ad3a793e/builds/fm2.3.28/xgui_preface.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/xgui_preface.html b/builds/fm2.3.28/xgui_preface.html index b0f8f77..0e72910 100644 --- a/builds/fm2.3.28/xgui_preface.html +++ b/builds/fm2.3.28/xgui_preface.html @@ -85,4 +85,4 @@ Last generated: © <span itemprop="copyrightYear">1999</span>â2018 <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> </div></div></div></body> -</html> \ No newline at end of file +</html>