http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/versions_2_3_23.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/versions_2_3_23.html b/builds/2.3.26-nightly/versions_2_3_23.html new file mode 100644 index 0000000..53bbb7d --- /dev/null +++ b/builds/2.3.26-nightly/versions_2_3_23.html @@ -0,0 +1,423 @@ +<!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>2.3.23 - 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="2.3.23"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/versions_2_3_23.html";> +<link rel="canonical" href="http://freemarker.org/docs/versions_2_3_23.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="app.html"><span itemprop="name">Appendixes</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="app_versions.html"><span itemprop="name">Version history</span></a></li><li class="step-3" itemprop="itemListEl ement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="versions_2_3_23.html"><span itemprop="name">2.3.23</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","Appendixes","Version history","2.3.23"];</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="versions_2_3_24.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_22.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="versions_2_3_23" itemprop="headline">2.3.23</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_164" data-menu-target="autoid_164">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_165" data-menu-target="autoid_165">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_166" data-menu-target="autoid_166">Other changes</a></li><li><a class="page-menu-link" href="#autoid_167" data-menu-target="autoid_167">Notes</a></li></ul> </div><p>Date of release: 2015-07-05</p> + + + + +<h2 class="content-header header-section2" id="autoid_164">Changes on the FTL side</h2> + + + <ul> + <li> + <p>Listing (<code class="inline-code">#list</code>) has received some + specialized convenience features that target typical tasks + people do again and again in templates.</p> + + <ul> + <li> + <p>New <code class="inline-code">list</code> directive child + directives. There are <code class="inline-code">else</code> and + <code class="inline-code">items</code> to deal with special cases with + 0-length lists, and <code class="inline-code">sep</code> for inserting + separators between items. For more details, see the <a href="ref_directive_list.html"><code>list</code> + directive in the Reference</a>.</p> + </li> + + <li> + <p><a href="ref_builtins_loop_var.html">New built-ins + that act on loop variables</a>: + <code class="inline-code"><em class="code-color">var</em>?index</code> + (deprecates + <code class="inline-code"><em class="code-color">var</em>_index</code>), + <code class="inline-code"><em class="code-color">var</em>?counter</code> + (1-based index), + <code class="inline-code"><em class="code-color">var</em>?has_next</code> + (deprecates + <code class="inline-code"><em class="code-color">var</em>_has_next</code>), + <code class="inline-code"><em class="code-color">var</em>?is_first</code>, + <code class="inline-code"><em class="code-color">var</em>?is_last</code>, + <code class="inline-code"><em class="code-color">var</em>?item_parity</code> + (returns <code class="inline-code">"odd"</code> or + <code class="inline-code">"even"</code>), + <code class="inline-code"><em class="code-color">var</em>?item_parity_cap</code>, + <code class="inline-code"><em class="code-color">var</em>?item_cycle</code><code class="inline-code">(<em class="code-color">...</em>)</code>, + etc.</p> + </li> + </ul> + </li> + + <li> + <p>Added convenience assignment operators, which can be used + in assignment directives (<code class="inline-code">#assign</code>, + <code class="inline-code">#global</code> and <code class="inline-code">#local</code> + currently) only:</p> + + <ul> + <li> + <p><code class="inline-code">++</code> and <code class="inline-code">--</code>: For + example, <code class="inline-code"><#assign counter++></code> is + equivalent to <code class="inline-code"><#assign counter = counter + + 1></code>.</p> + </li> + + <li> + <p><code class="inline-code">+=</code>, <code class="inline-code">-=</code>, + <code class="inline-code">*=</code>, <code class="inline-code">/=</code> and + <code class="inline-code">%=</code>: For example, <code class="inline-code"><#assign + counter += 2></code> is equivalent to + <code class="inline-code"><#assign counter = counter + + 2></code>.</p> + </li> + </ul> + </li> + + <li> + <p>Added the <code class="inline-code">then</code> built-in, which can be + used like a ternary operator: + <code class="inline-code"><em class="code-color">someBoolean</em>?then(<em class="code-color">whenTrue</em>, + <em class="code-color">whenFalse</em>)</code>. Just like with + the ternary operator of most other languages, only one of the + parameter expressions will be evaluated. <a href="ref_builtins_boolean.html#ref_builtin_then">More details...</a></p> + </li> + + <li> + <p>Added the <code class="inline-code">switch</code> built-in, which can be + used like an in-line (expression) switch-case-default statement: + <code class="inline-code"><em class="code-color">someValue</em>?switch(<em class="code-color">case1</em>, + <em class="code-color">result1</em>, + <em class="code-color">case2</em>, + <em class="code-color">result2</em>, ... + <em class="code-color">caseN</em>, + <em class="code-color">resultN</em>, + <em class="code-color">defaultResult</em>)</code>, where + <code class="inline-code"><em class="code-color">defaultResult</em></code> can + be omitted (then it will be error if none of the cases matches). + <a href="ref_builtins_type_independent.html#ref_builtin_switch">More details...</a></p> + </li> + + <li> + <p>Added camel case support for the identifiers that are part + of the template language (user defined names aren't affected). + For example, now + <code class="inline-code"><#noEscape>${x?upperCase}</#noEscape></code> + or <code class="inline-code"><#setting numberFormat="0.0"></code> or + <code class="inline-code"><#ftl stripText=true></code> are valid. + However, within the same template, FreeMarker will require you + to use the same naming convention consistently for all + identifiers that are part of the template language. It's also + possible to enforce the same naming convention on all templates + from Java via + <code class="inline-code">Configuration.setNamingConvention(int)</code>. It's + certain that camel case will be the recommended convention + starting from some future version, because the Java API-s users + call from templates use that too.</p> + </li> + + <li> + <p>Added new <a href="ref_specvar.html">special + variables</a>, <code class="inline-code">.current_template_name</code> and + <code class="inline-code">.main_template_name</code>. These deprecate + <code class="inline-code">.template_name</code>, which was always broken when + it comes to macro calls. The new + <code class="inline-code">.current_template_name</code> always returns the + name of the template that contains the reference to the special + variable, and <code class="inline-code">.main_template_name</code> always + returns the name of the topmost template.</p> + </li> + + <li> + <p>Smaller error message improvements. Like, added tip in the + error message for the frequent issue when + <code class="inline-code"><em class="code-color">someMap</em>[<em class="code-color">someNumber</em>]</code> + complains that + <code class="inline-code"><em class="code-color">someMap</em></code> is not a + sequence nor is coercible to string.</p> + </li> + + <li> + <p>Bug fixed, activated with setting + <code class="inline-code">incompatible_improvements</code> to 2.3.23: There's + a long existing parse-time rule that says that + <code class="inline-code">#break</code>, in the FTL source code itself, must + occur nested inside a breakable directive, such as + <code class="inline-code">#list</code> or <code class="inline-code">#switch</code>. This + check could be circumvented with <code class="inline-code">#macro</code> or + <code class="inline-code">#function</code>, like this: <code class="inline-code"><#list 1..1 + as x><#macro + callMeLater><#break></#macro></#list><@callMeLater + /></code>. After activating this fix, this will be caught + as parse time error.</p> + </li> + </ul> + + + + + +<h2 class="content-header header-section2" id="autoid_165">Changes on the Java side</h2> + + + <ul> + <li> + <p>Added + <code class="inline-code">Configuration.setNamingConvention(int)</code>. By + default FreeMarker will auto-detect the naming convention + (legacy VS camel case) used for the identifiers that are part of + the template language, for each template independently. This + setting lets you enforce a naming convention instead.</p> + </li> + + <li> + <p><code class="inline-code">Configuration</code> (and in fact any + <code class="inline-code">Configurable</code>) setting names now can be + written with camel case as well. For example, if you are + configuring FreeMarker from properties file, you can have + <code class="inline-code">defaultEncoding=utf-8</code> instead of + <code class="inline-code">default_encoding=utf-8</code>. You can use the two + naming conventions (camel case, and tradition snake case) mixed, + and <code class="inline-code">Configuration.setNamingConvention(int)</code> + does not influence this behavior.</p> + </li> + + <li> + <p>Added + <code class="inline-code">Configuration.setTemplateUpdateDelayMilliseconds(long)</code> + and + <code class="inline-code">Configuration.getTemplateUpdateDelayMilliseconds()</code>. + This deprecates <code class="inline-code">setTemplateUpdateDelay(int)</code>, + which uses seconds resolution, hence going against Java + conventions and often leading to misunderstandings. (Also that + couldn't have a getter pair.)</p> + </li> + + <li> + <p>The <code class="inline-code">template_update_delay</code> setting, when + specified as a string (as inside + <code class="inline-code">java.util.Properties</code>), supports time units, + like in <code class="inline-code">template_update_delay=500 ms</code>.</p> + </li> + + <li> + <p>Added <code class="inline-code">Environment.getCurrentTemplate()</code> + method, which return the currently executed template (as opposed + to the main template).</p> + </li> + + <li> + <p>Added + <code class="inline-code">WebappTemplateLoader.setAttemptFileAccess(boolean)</code>, + which can be used to disable the legacy trick where we try to + load templates through direct file access, so that template + updating works without restarting. Disabling URL connection + caches + (<code class="inline-code">someURLBasedTemplateLoader.setURLConnectionUsesCaches(false)</code>, + which is also the default since + <code class="inline-code">incompatible_improvements</code> 2.3.21) probably + solves that on modern Servlet containers.</p> + </li> + + <li> + <p>In the <code class="inline-code">FreemarkerServlet</code> + <code class="inline-code">TemplatePath</code> init-param, paths (like + <code class="inline-code">/templates</code>) can have a + <code class="inline-code">?settings(<em class="code-color">...</em>)</code> + postfix, with which you can set the JavaBean properties of the + resulting <code class="inline-code">TemplateLoader</code>. For example: + <code class="inline-code"><param-value>/templates?settings(attemptFileAccess=false, + URLConnectionUsesCaches=false)</param-value></code></p> + </li> + + <li> + <p>Added + <code class="inline-code">FileTemplateLoader.setEmulateCaseSensitiveFileSystem(boolean)</code>. + This is handy when you are developing on Windows but will deploy + to a platform with case sensitive file system. The default is + <code class="inline-code">false</code>, and <code class="inline-code">true</code> is only + meant for development, not for production installations. The + default can be overridden by setting the + <code class="inline-code">org.freemarker.emulateCaseSensitiveFileSystem</code> + system property to <code class="inline-code">true</code>.</p> + </li> + + <li> + <p>Bug fixed [<a href="https://sourceforge.net/p/freemarker/bugs/424";>424</a>]: + <code class="inline-code">WebappTemplateLoader</code> didn't find templates + that are stored in + <code class="inline-code">WEB-INF/lib/*.jar/META-INF/resources</code>. Files + under that directory are visible as + <code class="inline-code">ServletContext</code> resources since Servlet 3.0, + yet <code class="inline-code">WebappTemplateLoader</code> has usually failed + to see them because of some internal tricks.</p> + </li> + + <li> + <p>Bug fixed: If a template "file" was + successfully opened for reading, but then there was an + <code class="inline-code">IOException</code> during reading its content, the + parser (JavaCC) acted like if the template "file" + was ended there, and the exception was suppressed. It's actually + a JavaCC quirk that affects many other JavaCC-based languages + too, but now FreeMarker has added a workaround in the + <code class="inline-code">Template</code> constructor, and so now an exception + will be thrown as expected.</p> + </li> + + <li> + <p>Bug fixed: + <code class="inline-code">InvalidReferenceException.FAST_INSTANCE</code> could + accidentally store reference to an + <code class="inline-code">Environment</code> instance, which hence was never + garbage collected.</p> + </li> + + <li> + <p>Bug fixed [<a href="https://sourceforge.net/p/freemarker/bugs/426/";>426</a>]: + When setting <code class="inline-code">incompatible_improvements</code> to + 2.3.22, the special variable reference + <code class="inline-code">.template_name</code> in templates always returns + the name of the main (topmost) template, due to an oversight in + 2.3.22. Setting <code class="inline-code">incompatible_improvements</code> to + 2.3.23 restores the old, backward compatible behavior. (Note + that the old behavior that we emulate is itself broken, as it + doesn't work well with macro calls; you should use + <code class="inline-code">.current_template_name</code> or + <code class="inline-code">.main_template_name</code> instead.)</p> + </li> + + <li> + <p>Bug fixed [<a href="https://sourceforge.net/p/freemarker/bugs/53/";>53</a>]: + Template parsing was abnormally slow for templates with very + high number AST (abstract syntax tree) nodes on the same + hierarchy level.</p> + </li> + + <li> + <p>Bug fixed: When the template was concurrently replaced on + the backing store during its first loading was still ongoing, + the older version of the template could get into the cache with + the time stamp of the new version, hence it wasn't reloaded + after the configured update delay.</p> + </li> + + <li> + <p>Bug fixed: The <code class="inline-code">log_template_exceptions</code> + setting (added in 2.3.22) couldn't be set through the + <code class="inline-code">Configurable.setSetting(String, String)</code> + API.</p> + </li> + + <li> + <p>Bug fixed: + <code class="inline-code">StringUtil.FTLStringLiteralEnc</code> has escaped + <code class="inline-code">$</code> (hence generating an illegal escape) and + haven't escaped <code class="inline-code">{</code> after <code class="inline-code">$</code> + and <code class="inline-code">#</code>. While this function is only used for + generating error messages by FreeMarker, it's a public methods + so anyone could use it.</p> + </li> + + <li> + <p>Bugs fixed: Various canonical form glitches (they only + affect error messages as far as FreeMarker is concerned).</p> + </li> + </ul> + + + + + +<h2 class="content-header header-section2" id="autoid_166">Other changes</h2> + + + <ul> + <li> + <p>Modernized Manual and site design with improved + functionality (always visible navigation tree, search inside the + Manual, etc.), thanks to Evangelia Dendramis. (Also now the Site + uses the same format and HTML generator as the Manual.)</p> + </li> + + <li> + <p>Many smaller Manual and site content + updates/improvements.</p> + </li> + </ul> + + + + + +<h2 class="content-header header-section2" id="autoid_167">Notes</h2> + + + <p>Changes compared to 2.3.23 RC1:</p> + + <ul> + <li> + <p><code class="inline-code">.current_name_name</code> and + <code class="inline-code">.main_template_name</code> is now missing + (<code class="inline-code">null</code>) instead of <code class="inline-code">""</code> if + the template has no name</p> + </li> + + <li> + <p>Some minor error message improvements</p> + </li> + + <li> + <p>Documentation refinements</p> + </li> + </ul> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="versions_2_3_24.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_22.html"><span>Next</span></a></div></div></div></div> </div> + </div> +<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker";>Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/"; rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> +Last generated: +<time itemprop="dateModified" datetime="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html>
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/versions_2_3_24.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/versions_2_3_24.html b/builds/2.3.26-nightly/versions_2_3_24.html new file mode 100644 index 0000000..da73713 --- /dev/null +++ b/builds/2.3.26-nightly/versions_2_3_24.html @@ -0,0 +1,925 @@ +<!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>2.3.24 (incubating at Apache) - 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="2.3.24 (incubating at Apache)"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/versions_2_3_24.html";> +<link rel="canonical" href="http://freemarker.org/docs/versions_2_3_24.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="app.html"><span itemprop="name">Appendixes</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="app_versions.html"><span itemprop="name">Version history</span></a></li><li class="step-3" itemprop="itemListEl ement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="versions_2_3_24.html"><span itemprop="name">2.3.24 (incubating at Apache)</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","Appendixes","Version history","2.3.24 (incubating at Apache)"];</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="versions_2_3_25.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_23.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="versions_2_3_24" itemprop="headline">2.3.24 (incubating at Apache)</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_160" data-menu-target="autoid_160">Legal changes</a></li><li><a class="page-menu-link" href="#autoid_161" data-menu-target="autoid_161">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_162" data-menu-target="autoid_162">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_163" data-menu-target="autoid_163">Changes compared to 2.3.24 Release Candidate 1</a></li></ul> </div><p>Release date: 2016-03-28</p><p><strong>This is a stable, final + release.</strong> The "incubating" suffix is required + by the Apache Software Foundation until the project becomes a fully + accepted (graduated) Apache project. See disclaimer below.</p> + + + + +<h2 class="content-header header-section2" id="autoid_160">Legal changes</h2> + + + <p>The owner of FreeMarker is now the Apache Software Foundation. + The license is still Apache License Version 2.0, just like earlier, + but the owner is different. The official full product name has + changed to Apache FreeMarker.</p> + + <p><strong>Disclaimer:</strong><em> Apache + FreeMarker is an effort undergoing incubation at The Apache Software + Foundation (ASF), sponsored by the <a href="http://incubator.apache.org";>Apache Incubator</a>. + Incubation is required of all newly accepted projects until a + further review indicates that the infrastructure, communications, + and decision making process have stabilized in a manner consistent + with other successful ASF projects. While incubation status is not + necessarily a reflection of the completeness or stability of the + code, it does indicate that the project has yet to be fully endorsed + by the ASF.</em></p> + + + + + +<h2 class="content-header header-section2" id="autoid_161">Changes on the FTL side</h2> + + + <ul> + <li> + <p>The most important new feature of this release is the + <a href="dgui_misc_autoescaping.html">auto-escaping and output + formats mechanism</a>, which deprecates escaping with the + <a href="ref_directive_escape.html"><code>escape</code> + directive</a>. These are the changes related to this new + mechanism (see earlier link for a guide):</p> + + <ul> + <li> + <p>New <code class="inline-code">ftl</code> header options, + <code class="inline-code">ouput_format</code> and + <code class="inline-code">auto_esc</code> to override the + <code class="inline-code">output_format</code> and + <code class="inline-code">auto_escaping</code> settings of the template, + like <code class="inline-code"><#ftl + output_format='HTML'</code><code class="inline-code"> + auto_esc=false></code>.</p> + </li> + + <li> + <p>New built-in: <a href="ref_builtins_string.html#ref_builtin_no_esc"><code>no_esc</code></a>. + Used to prevent auto-escaping, like + <code class="inline-code">${descriptionInHtml?no_esc}</code>. This doesn't + work with <code class="inline-code"><#escape + <em class="code-color">...</em>></code>, only with the + new auto-escaping mechanism.</p> + </li> + + <li> + <p>New FTL type, "markup output". This is + somewhat similar to string, but values of this type aren't + auto-escaped by the new escaping mechanism, because they are + known to already hold markup. (For example, + <code class="inline-code">?esc</code> and <code class="inline-code">?no_esc</code> + returns a value of this type, hence their results are + protected from double-escaping problems.)</p> + </li> + + <li> + <p>New built-in: <a href="ref_builtins_string.html#ref_builtin_esc"><code>esc</code></a>. + Used for escaping with the current output format when + auto-escaping is disabled.</p> + </li> + + <li> + <p>New built-in: <code class="inline-code">markup_string</code>. This + returns the markup of a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output + value</a> as string.</p> + </li> + + <li> + <p>New built-in: <code class="inline-code">is_markup_output</code>, + returns <code class="inline-code">true</code> if the value is of type + "markup output".</p> + </li> + + <li> + <p>New directive: <code class="inline-code">outputformat</code>, used + to change the output format for a section of a template, + like <code class="inline-code"><#outputformat + "XML"><em class="code-color">...</em></#outputformat></code></p> + </li> + + <li> + <p>New directives: <code class="inline-code">noautoesc</code> and + <code class="inline-code">autoesc</code>, used to turn auto-escaping off + and on for a section of a template, like + <code class="inline-code"><#noautoesc><em class="code-color">...</em></#noautoesc></code>.</p> + </li> + + <li> + <p>New built-in variable, + <code class="inline-code">.output_format</code>, returns the current + output format at the place of invocation.</p> + </li> + + <li> + <p>New built-in variable, <code class="inline-code">.auto_esc</code>, + returns the boolean that tells if auto-escaping is active at + the place of invocation.</p> + </li> + + <li> + <p>Block assignments, like <code class="inline-code"><#assign + <em class="code-color">captured</em>><em class="code-color">...</em></#assign></code>, + when the current <code class="inline-code">output_format</code> is some + kind of markup (like HTML), will store the captured output + not with string type, but with "markup output" + type. Thus + <code class="inline-code">${<em class="code-color">captured</em>}</code> + will not get unwanted escaping.</p> + </li> + + <li> + <p>The <code class="inline-code">+</code> operator (concatenation) + works with the new "markup output" type as + well. Like <code class="inline-code">someMarkup + somePlainText</code> + will result in markup where <code class="inline-code">somePlainText</code> + is escaped automatically before it's appended to the + markup.</p> + </li> + + <li> + <p>The <code class="inline-code">has_content</code> built-in now + supports "markup output" values, considering 0 + length markup as empty.</p> + </li> + </ul> + </li> + + <li> + <p>You can now define custom number and date/time/datetime + formatters. These are defined by the programmers (and thus can + implement any kind of exotic formatting rules) when configuring + FreeMarker, and can be referred with strings starting with + <code class="inline-code">"@"</code>, like in <code class="inline-code"><#setting + number_format='@foo'></code>, or + <code class="inline-code">${n?string.@foo_params}</code>, + <code class="inline-code"><#setting number_format='@foo params'></code>, + or <code class="inline-code">${n?string.@foo}</code>, + <code class="inline-code">${n?string.@foo_params}</code>. For backward + compatibility, the initial <code class="inline-code">@</code> only has this + special meaning if either you have any custom formats or <a href="pgui_config_incompatible_improvements.html">the + <code>incompatible_improvements</code> setting</a> is + at lest 2.3.24.</p> + </li> + + <li> + <p>Everywhere where Java <code class="inline-code">DecimalFormat</code> + patterns are used (like in <code class="inline-code">?string('0.##')</code> or + <code class="inline-code"><#setting number_format="0.##"></code>), now + it's possible to specify options like rounding mode or the + symbols used, with a FreeMarker-specific <a href="ref_builtins_number.html#topic.extendedJavaDecimalFormat">extension to the + <code>DecimalFormat</code> pattern syntax</a>.</p> + </li> + + <li> + <p>Added new special variable: + <code class="inline-code">.incompatible_improvements</code>, which returns the + <a href="pgui_config_incompatible_improvements.html"><code>incompatbile_improvements</code> + setting</a> of the current FreeMarker configuration, as a + string.</p> + </li> + + <li> + <p><code class="inline-code">?date</code>, <code class="inline-code">?time</code> and + <code class="inline-code">?datetime</code> now can be called as 0 argument + method, like <code class="inline-code">?date()</code>, etc., which returns the + exact object that <code class="inline-code">TemplateDateFormat.parse</code> + returns, instead of the tricky multi-type object that just using + <code class="inline-code">?date</code> returns. Because custom + <code class="inline-code">TemplateDateFormat</code> implementations may return + custom <code class="inline-code">TemplateDateModel</code> implementations, + keeping the exact class can be important in some + applications.</p> + </li> + + <li> + <p><code class="inline-code"><@</code> and <code class="inline-code"></@</code> is + now allowed in string literals that contain + <code class="inline-code">${<em class="code-color">exp</em>}</code>, and will + be part of the literal as is. Earlier it was a syntactical + error.</p> + </li> + + <li> + <p>Bug fixed: With + <code class="inline-code">incompatible_improvements</code> set to 2.3.24 + (<a href="pgui_datamodel_objectWrapper.html#topic.defaultObjectWrapperIcI">see how + here...</a>), + <code class="inline-code"><em class="code-color">m</em>?is_sequence</code> + doesn't return <code class="inline-code">true</code> for Java methods wrapped + by <code class="inline-code">BeansWrapper</code> and its subclasses (most + notably <code class="inline-code">DefaultObjectWrapper</code>) anymore, as + they only implement the + <code class="inline-code">[<em class="code-color">index</em>]</code> operator, + but not <code class="inline-code">?size</code>, which causes + <code class="inline-code"><#list <em class="code-color">...</em>></code> + to fail, among others.</p> + </li> + </ul> + + + + + +<h2 class="content-header header-section2" id="autoid_162">Changes on the Java side</h2> + + + <ul> + <li> + <p><em>Attention!</em> FreeMarker + now requires at least Java 1.5 (aka. Java 5). 2.3.24 has only + required Java 1.4. (Reason: Without this, new public API-s + couldn't use generics, which affect negatively the majority of + users, while old installations that are still using 1.4 are + unlikely to update FreeMarker anyway.)</p> + </li> + + <li> + <p><em>Attention!</em> FreeMarker's + JSP support (if it's used) now requires at least JSP 2.0. + Earlier it only required JSP 1.1. (Reason: The + <code class="inline-code">jsp-api</code> dependency for JSP 1.x, which was + needed for building, can't be legally present in the Maven + Central Repository, nor be provided by freemarker.org.)</p> + </li> + + <li> + <p>Added new configuration setting: + <code class="inline-code">template_configurations</code>. This allows + overriding the settings coming from the shared + <code class="inline-code">Configuration</code> object for individual + templates, based on template name patterns. <a href="pgui_config_templateconfigurations.html">See more + here...</a></p> + </li> + + <li> + <p>Related to the <a href="dgui_misc_autoescaping.html">new + auto-escaping mechanism</a>:</p> + + <ul> + <li> + <p>As FTL has now a new type, "markup + output", there's also a corresponding new model + interface, <code class="inline-code">TemplateMarkupOutputModel</code>. + This also means that you can prevent the auto-escaping of + values coming from the data-model by returning a + <code class="inline-code">TemplateMarkupOutputModel</code> instead of a + <code class="inline-code">String</code>. Like the template author can just + write <code class="inline-code">${messages.foo}</code>, and it will be + auto-escaped or not depending on if the message is known to + be markup or not.</p> + </li> + + <li> + <p>Added new configuration setting: + <code class="inline-code">recognize_standard_file_extensions</code>. When + <code class="inline-code">true</code>, templates whose source name ends + with <code class="inline-code">".ftlh"</code> will get + <code class="inline-code">HTML</code> <code class="inline-code">output_format</code>, + and those whose name ends with <code class="inline-code">".ftlx"</code> + get <code class="inline-code">XML</code> <code class="inline-code">output_format</code>, + in both cases with auto-escaping on. If <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set">the + <code>incompatible_improvements</code> setting</a> + is set to 2.3.24 (or higher) then this setting defaults to + <code class="inline-code">true</code>. Otherwise it's default is + <code class="inline-code">false</code>, but enabling it is highly + recommended.</p> + </li> + + <li> + <p>Added new configuration setting: + <code class="inline-code">output_format</code>. This specifies the <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_outputformat">output + format</a> object to use (such as + <code class="inline-code">HTMLOutputFormat.INSTANCE</code>, + <code class="inline-code">XMLOutputFormat.INSTANCE</code>, etc.) that + governs auto-escaping. The output format can be different + for different templates, using the + <code class="inline-code">template_configurations</code> setting (<a href="pgui_config_outputformatsautoesc.html">see here + how...</a>).</p> + </li> + + <li> + <p>Added new configuration setting: + <code class="inline-code">registered_custom_output_formats</code>. With + this you can add new <code class="inline-code">OutputFormat</code>-s that + templates can refer to by name (like in <code class="inline-code"><#ftl + output_format="foo"></code>).</p> + </li> + + <li> + <p>Added new configuration setting: + <code class="inline-code">auto_escaping_policy</code>. This decides when + auto-escaping should be enabled depending on the current + output format.</p> + </li> + </ul> + </li> + + <li> + <p>Changes related to the custom number and + date/time/datetime formating feature:</p> + + <ul> + <li> + <p>Added new classes for implementing custom formatters: + <code class="inline-code">freemarker.core.TemplateNumberFormat</code>, + <code class="inline-code">TemplateNumberFormatFactory</code>, + <code class="inline-code">TemplateDateFormat</code>, + <code class="inline-code">TemplateDateFormatFactory</code>, also the + exceptions these can throw. These allow implementing any + kind of formatting rule that's doable in Java (i.e., they + aren't restricted to any <code class="inline-code">java.text</code> + formatters). Furthermore these formatters get the + <code class="inline-code">TemplateModel</code> instead of a the bare + <code class="inline-code">java.lang.Number</code> or + <code class="inline-code">java.util.Date</code>, which lets you use the + extra application-specific meta information that you may + pack into the <code class="inline-code">TemplateModel</code>-s, such as + physical unit, preferred precision, and so on.</p> + </li> + + <li> + <p>Added <code class="inline-code">custom_number_formats</code> and + <code class="inline-code">custom_date_formats</code> settings + (<code class="inline-code">Configurable.setCustomNumberFormats(Map<String, + TemplateNumberFormatFactory>)</code> and + <code class="inline-code">Configurable.setCustomDateFormats(Map<String, + TemplateDateFormatFactory>)</code>) with which you can + register your own formats. These formats can be referred + from everywhere where you can use a string to define a + format, with a format string like <code class="inline-code">"@foo"</code> + or <code class="inline-code">"@foo params"</code>, where + <code class="inline-code">"foo"</code> is the key in the + <code class="inline-code">Map<String, ...></code> parameter of the + earlier shown methods, and the parameters (if any) are + interpreted by the + <code class="inline-code">Template<em class="code-color">Xxx</em>FormatFactory</code> + implementation that you provide. Like, you can issue + <code class="inline-code">cfg.setNumberFormat("@foo params")</code>, or + <code class="inline-code"><#setting number_format='@foo + params'></code>, or + <code class="inline-code">${n?string.@foo_params}</code>, similarly as you + can issue <code class="inline-code">cfg.setNumberFormat("0.##")</code>, + etc. For backward compatibility, the initial + <code class="inline-code">@</code> only has this special meaning if either + you have any custom formats or <a href="pgui_config_incompatible_improvements.html">the + <code>incompatible_improvements</code> setting</a> + is at least 2.3.24. Note that the + <code class="inline-code">custom_number_formats</code> and + <code class="inline-code">custom_date_formats</code> settings can be set + per-template (via the new + <code class="inline-code">template_configurations</code> settings) or + per-<code class="inline-code">Environment</code> too, thus + <code class="inline-code">@foo</code> can mean something different in + different templates.</p> + </li> + + <li> + <p>Added new <code class="inline-code">Environment</code> methods + returning <code class="inline-code">TemplateNumberFormat</code> and + <code class="inline-code">TemplateDateFormat</code> objects. See the + <code class="inline-code">getTemplateNumberFormat(<em class="code-color">...</em>)</code> + and + <code class="inline-code">getTemplateDateFormat(<em class="code-color">...</em>)</code> + variations in the API.</p> + </li> + + <li> + <p>Added + <code class="inline-code">freemarker.core.AliasTemplateNumberFormatFactory</code> + and <code class="inline-code">AliasTemplateDateFormatFactory</code>, which + can be used to create custom formats that are aliases to + other formats. For example, instead of writing + <code class="inline-code">${n?string["0.00"]}</code> again and again, you + can define the custom format <code class="inline-code">"price"</code> as + the alias to the format string <code class="inline-code">"0.00"</code> in + the configuration, and then use + <code class="inline-code">${n?string.@price}</code>. Thus, you can control + at a central place how prices look. Furthermore, the alias + can chose a different target format string depending on the + current locale; this is especially useful for dates, where + conventions can significantly differ in different + countries.</p> + </li> + + <li> + <p>It's now possible to have HTML or other markup in + number and date/time/datetime formatting results, like + <code class="inline-code">1.23*10<sup>6</sup></code>, which + won't be accidentally auto-escaped, as FreeMarker knows that + it's already HTML. This is done by returning a + <code class="inline-code">TemplateMarkupOutputModel</code> instead of a + <code class="inline-code">String</code>; see the new auto-escaping + mechanism earlier. Note that no out-of-the-box format + utilizes this (at the moment), but you could write such + custom format.</p> + </li> + + <li> + <p>The internal format object caching architecture has + been reworked, so that it can handle custom formats too. + This reworking also fixes some bottlenecks under highly + concurrent load, and some (otherwise unlikely) memory leak + possibilities.</p> + </li> + </ul> + </li> + + <li> + <p>In the <code class="inline-code">number_format</code> configuration + setting, when it holds a Java <code class="inline-code">DecimalFormat</code> + pattern (like <code class="inline-code">"0.##"</code>), it's now possible to + specify options like rounding mode or the symbols used, with a + FreeMarker-specific <a href="ref_builtins_number.html#topic.extendedJavaDecimalFormat">extension to the + pattern syntax</a>.</p> + </li> + + <li> + <p>New <code class="inline-code">FreemarkerServlet</code> init-params (see + <a href="http://freemarker.org/docs/api/freemarker/ext/servlet/FreemarkerServlet.html";>the + <code>FreemarkerSerlvet</code> API documentation</a> + for details):</p> + + <ul> + <li> + <p><code class="inline-code">OverrideResponseContentType</code>: + Specifies when should we override the + <code class="inline-code">contentType</code> that's already set (i.e., + non-<code class="inline-code">null</code>) in the + <code class="inline-code">HttpServletResponse</code>. Earlier, we have + always set it, and that's still the default behavior. But + now that this init-param exists, you can change that + behavior, so that the <code class="inline-code">contentType</code> you + have specified before forwarding to + <code class="inline-code">FreemarkerServlet</code> matters.</p> + </li> + + <li> + <p><code class="inline-code">OverrideResponseLocale</code>: Specifies + if we should override the <code class="inline-code">locale</code> that's + already set (i.e., non-<code class="inline-code">null</code>) in the + <code class="inline-code">HttpServletResponse</code>. Earlier, we have + always set it, but now this behavior can be changed so that + we only set it if it wasn't already set.</p> + </li> + + <li> + <p><code class="inline-code">ResponseCharacterEncoding</code>: + Deprecates the old (and quirky) logic of specifying the + output charset, which is putting it into the + <code class="inline-code">ContentType</code> init-param after the MIME + type, otherwise falling back to the template file charset. + The possible values are <code class="inline-code">legacy</code> (the + default for backward compatibility), + <code class="inline-code">fromTemplate</code> (which is + <code class="inline-code">legacy</code> without quirks, and is aware of + the <code class="inline-code">outputEncoding</code> setting), + <code class="inline-code">doNotSet</code> (keeps what the caller has + already set in the <code class="inline-code">ServletRespone</code>) and + <code class="inline-code">force</code> followed by a charset name (forces + a specific output charset).</p> + </li> + </ul> + </li> + + <li> + <p>Added + <code class="inline-code">freemarker.cache.ByteArrayTemplateLoader</code>, + which is similar to <code class="inline-code">StringTemplateLoader</code>, but + stores the templates as <code class="inline-code">byte[]</code>-s instead of + as <code class="inline-code">String</code>-s.</p> + </li> + + <li> + <p>Upgraded JavaCC (used during build to generate the FTL + parser) from 3.2 to 6.1.2.</p> + </li> + + <li> + <p>Added <code class="inline-code">Configurable.getSettingNames(boolean + camelCase)</code>, which returns the set of valid setting + names. This can be useful for auto-completion and such.</p> + </li> + + <li> + <p>Fixes and improvements in the "object + builder" mini-language used for configuring FreeMarker + from <code class="inline-code">java.util.Properties</code> or other + string-only sources (not used in templates). This is + <em>not to be confused with the template language + syntax</em>, which has nothing to do with the + "object builder" syntax we are writing about here. + The improvements are:</p> + + <ul> + <li> + <p>Bug fixed: For nested builder expressions, the + top-level result class restriction were applied + accidentally.</p> + </li> + + <li> + <p>When resolving an expression like + <code class="inline-code">com.example.Foo()</code>, if there's a builder + class (<code class="inline-code">com.example.FooBuilder</code>), the + non-builder class (<code class="inline-code">com.example.Foo</code>) need + not exist anymore. After all, + <code class="inline-code">FooBuilder.build()</code> instantiates from any + class it wants to anyway.</p> + </li> + + <li> + <p><code class="inline-code">TimeZone</code> objects can be created + like <code class="inline-code">TimeZone("UTC")</code>, despite that + there's no a such constructor.</p> + </li> + + <li> + <p>Added support for creating lists with <code class="inline-code">[ + <em class="code-color">item1</em>, + <em class="code-color">item2</em>, + <em class="code-color">...</em> + <em class="code-color">itemN</em> ]</code> syntax.</p> + </li> + + <li> + <p>Added support for creating maps with <code class="inline-code">{ + <em class="code-color">key1</em>: + <em class="code-color">value1</em>, + <em class="code-color">key2</em>: + <em class="code-color">value2</em>, + <em class="code-color">...</em> + <em class="code-color">keyN</em>: + <em class="code-color">valueN</em> }</code> syntax.</p> + </li> + + <li> + <p>A number without decimal point will now be parsed to + <code class="inline-code">Integer</code>, <code class="inline-code">Long</code>, or + <code class="inline-code">BigInteger</code>, depending on the size of the + number. Earlier all numbers were parsed to + <code class="inline-code">BigDecimal</code>-s, but that had little + importance before lists and maps were added, as the number + was converted to the constructor or setter parameter type + anyway.</p> + </li> + + <li> + <p>Number literals can have Java type suffixes + (<code class="inline-code">f</code>, <code class="inline-code">d</code>, + <code class="inline-code">l</code>), plus <code class="inline-code">bd</code> for + <code class="inline-code">BigDecimal</code> and <code class="inline-code">bi</code> for + <code class="inline-code">BigInteger</code>.</p> + </li> + + <li> + <p>Public static fields can be referred, like + <code class="inline-code">com.example.MyClass.MY_CONSTANT</code> or + <code class="inline-code">Configuration.AUTO_DETECT_TAG_SYNTAX</code>.</p> + </li> + </ul> + </li> + + <li> + <p>Decreased the stack usage of template execution, which can + have importance if you have very very deeply nested + templates.</p> + </li> + + <li> + <p>Added + <code class="inline-code">MultiTemplateLoader.setSticky(boolean)</code> and + <code class="inline-code">MultiTemplateLoader.isSticky()</code>, with which + you can disable the default behavior, where once a template was + found in a child <code class="inline-code">TemplateLoader</code>, it will be + searched there first next time (typically, when the template + update delay is expired). With the <code class="inline-code">sticky</code> + property set to <code class="inline-code">false</code>, the child + <code class="inline-code">TemplateLoader</code>-s will be always searched in + the order as they were added to the + <code class="inline-code">MultiTemplateLoader</code>.</p> + </li> + + <li> + <p>Added + <code class="inline-code">StringTemplateLoader.removeTemplate(String)</code> + method.</p> + </li> + + <li> + <p>Bug fixed, only with + <code class="inline-code">incompatible_improvements</code> set to 2.3.24 + (<a href="pgui_datamodel_objectWrapper.html#topic.defaultObjectWrapperIcI">see how + here...</a>): Expressions inside interpolations that were + inside <em>string literal expressions</em> (not + <code class="inline-code">${<em class="code-color">...</em>}</code>-s in + general), like in <code class="inline-code"><#assign s="Hello + ${name}!"></code>, always used + <code class="inline-code">incompatibleImprovements</code> 0 (2.3.0 in effect). + This means that expressions inside string literals had missed + the <code class="inline-code">?html</code>, + <code class="inline-code">?iso_<em class="code-color">...</em></code>, + <code class="inline-code">?is_enumerable</code>, <code class="inline-code">?c</code>, etc. + fixes/improvements.</p> + </li> + + <li> + <p>Bug fixed [<a href="https://sourceforge.net/p/freemarker/bugs/439/";>439</a>]: + <code class="inline-code">FileTemplateLoader</code> with + <code class="inline-code">emulateCaseSensitiveFileSystem</code> set to + <code class="inline-code">true</code> (used for development) wasn't properly + synchronized, leading to random + <code class="inline-code">NullPointerException</code>-s or other + misbehavior.</p> + </li> + + <li> + <p>Bug fixed: It wasn't well defined when a Java + <code class="inline-code">Iterator</code> counts as empty. Depending on what + <code class="inline-code">ObjectWrapper</code> you are using, one of these + fixes apply:</p> + + <ul> + <li> + <p><code class="inline-code">DefaultObjectWrapper</code> (fix is always + active): Operations on the <code class="inline-code">Iterator</code> that + only check if it's empty without reading an element from it, + such as <code class="inline-code">?has_content</code>, won't cause a later + iteration (or further emptiness check) to fail anymore. + Earlier, in certain situations, the second operation has + failed saying that the iterator "can be listed only + once".</p> + </li> + + <li> + <p><code class="inline-code">BeansWrapper</code> (when it's not + extended by <code class="inline-code">DefaultObjectWrapper</code>), if + it's <code class="inline-code">incompatibleImprovements</code> property is + set to 2.3.24 (or higher): <code class="inline-code">Iterator</code>-s + were always said to be non-empty when using + <code class="inline-code">?has_content</code> and such (i.e., operators + that check emptiness without reading any elements). Now an + <code class="inline-code">Iterator</code> counts as empty exactly if it + has no elements left. (Note that this bug has never affected + basic functionality, like <code class="inline-code"><#list + ...></code>.)</p> + </li> + </ul> + </li> + + <li> + <p>Bug fixed: The (rarely used) cause exception of + <code class="inline-code">ParseException</code>-s wasn't set</p> + </li> + + <li> + <p>Bug fixed: When the + <code class="inline-code">incomaptible_improvements</code> setting of an + existing <code class="inline-code">Configuration</code> was changed, the + template cache sometimes wasn't recreated, hence old templates + could survive.</p> + </li> + + <li> + <p>Bug fixed, with + <code class="inline-code">incompatible_improvements</code> set to 2.3.24 + (<a href="pgui_datamodel_objectWrapper.html#topic.defaultObjectWrapperIcI">see how + here...</a>): The <code class="inline-code">#import</code> directive meant + to copy the library variable into a global variable if it's + executed in the main namespace, but that haven't happened when + the imported template was already imported earlier in another + namespace.</p> + </li> + + <li> + <p>Fixes in the XML processing feature + (<code class="inline-code">freemarker.ext.dom</code>):</p> + + <ul> + <li> + <p>Bug fixed: XPath queries that has only contained + characters that are valid in XML element names and has also + contained <code class="inline-code">::</code> (which is valid in names in + namespace-unware documents), like + <code class="inline-code">e['following-sibling::foo']</code>, were + interpreted as literal element names (giving 0 hits) rather + than as XPath expressions. Note that there were no such + problem with <code class="inline-code">e['following-sibling::*']</code> + for example, as it's not a valid XML element name according + the XML specification. This fix can actually break + applications that has processed namespace unaware XML that + use <code class="inline-code">::</code> as part of element or attribute + names, but such an application is highly unlikely, unlike + running into the fixed problem. (Unfortunately, using + <code class="inline-code">incompatible_improvements</code> wasn't + technically possible here.)</p> + </li> + + <li> + <p>Bug fixed: The <code class="inline-code">@@qname</code> of elements + that belong to the XML namespace declared as the default via + <code class="inline-code"><#ftl ns_prefixes={'D':'...', ... + }></code> no longer starts with <code class="inline-code">D:</code>, + instead they just start with no name space prefix.</p> + </li> + + <li> + <p>Bug fixed: In the markup returned by the + <code class="inline-code">@@markup</code> key, when there were multiple + namespaces for which there was no prefix associated with via + <code class="inline-code"><#ftl + ns_prefixes=<em class="code-color">...</em>></code>, + all those namespaces were assigned to the same + auto-generated <code class="inline-code">xmlns</code> prefix (usually + "a"). Now they will get "a", + "b", "c", etc. prefixes.</p> + </li> + </ul> + </li> + + <li> + <p>JSP TLD loading now quotes the location of + <code class="inline-code">jar</code>-s (and other <code class="inline-code">zip</code>-s) + which can't be loaded due to zip format errors in the error + message.</p> + </li> + + <li> + <p>Added an overload to + <code class="inline-code">Configuration.getSupportedBuiltInNames</code> and + <code class="inline-code">Configuration.getSupportedBuiltInDirectiveNames</code> + that has a <code class="inline-code">namingConvention</code> parameter. This + is useful for tooling as since 2.3.23 we support both camel case + naming convention (like + <code class="inline-code"><em class="code-color">s</em>?upperCase</code>) and + the legacy one (like + <code class="inline-code"><em class="code-color">s</em>?upper_case</code>). + Furthermore the old 0 argument overload will now utilize + <code class="inline-code">Configuration.getNamingConvention()</code> to only + return the relevant names if it's not + <code class="inline-code">AUTO_DETECT_NAMING_CONVENTION</code>.</p> + </li> + + <li> + <p>Internal reworking to simplify the AST (the + <code class="inline-code">TemplateElement</code> structure). The related + technically public API was marked as internal for a good while. + For those who still use that API, the visible change is that + <code class="inline-code">TemplateElement</code>-s now almost never has a + <code class="inline-code">MixedContent</code> parent, instead, the parent is + directly whatever element the child element indeed belongs under + when you look at the source code (like the enclosing + <code class="inline-code">#list</code> for example, while earlier you often + had to go through a <code class="inline-code">MixedContent</code> first whose + parent was the <code class="inline-code">#list</code>). Note that when you + have moved downwards, i.e., towards the child elements, these + <code class="inline-code">MixedContent</code> parents weren't visible and were + silently skipped, so the tree traversal API was inconsistent. + Now it's consistent.</p> + </li> + + <li> + <p>Due to the above change again, the return type of + <code class="inline-code">freemarker.core.DebugBreak.accept()</code> and + <code class="inline-code">freemarker.core.TextBlock.accept()</code> has + changed from <code class="inline-code">void</code> to + <code class="inline-code">TemplateElement[]</code>. This again is highly + unlikely to affect anyone, and these meant to be internal API-s + anyway, but as these two <code class="inline-code">accept</code> methods has + wider than package visibility for historical reasons, we mention + this change.</p> + </li> + + <li> + <p>The non-public AST API of + <code class="inline-code">freemarker.core.StringLiteral</code>-s has been + changed. In principle it doesn't mater as it isn't a public API, + but some might used these regardless to introspect templates. + Earlier it had an "embedded template" parameter + inside, now it has 0 (for purely static string literals), one or + more "value part"-s, which are + <code class="inline-code">String</code>-s and + <code class="inline-code">Interpolation</code>-s.</p> + </li> + + <li> + <p>Internal code cleanup: Mostly for consistent source code + formatting, also many parser construction/setup cleanup</p> + </li> + + <li> + <p>Source code changes to conform to Apache source release + policy, such as adding copyright headers and getting rid of test + <code class="inline-code">jar</code>-s committed into the source code. Eclipse + project files were also removed, instead the + <code class="inline-code">README</code> describes how to set up the + project.</p> + </li> + + <li> + <p>Build script and distribution artifact changes to conform + to Apache release policy, most notably it produces separate + source and binary releases.</p> + </li> + </ul> + + + + + +<h2 class="content-header header-section2" id="autoid_163">Changes compared to 2.3.24 Release Candidate 1</h2> + + + <ul> + <li> + <p>Added + <code class="inline-code">MultiTemplateLoader.setSticky(boolean)</code> and + <code class="inline-code">MultiTemplateLoader.isSticky()</code>, with which + you can disable the default behavior, where once a template was + found in a child <code class="inline-code">TemplateLoader</code>, it will be + searched there first next time (typically, when the template + update delay is expired). With the <code class="inline-code">sticky</code> + property set to <code class="inline-code">false</code>, the child + <code class="inline-code">TemplateLoader</code>-s will be always searched in + the order as they were added to the + <code class="inline-code">MultiTemplateLoader</code>.</p> + </li> + + <li> + <p>Added + <code class="inline-code">StringTemplateLoader.removeTemplate(String)</code> + method.</p> + </li> + + <li> + <p>Source code changes to conform to Apache release policy + and recommendations:</p> + + <ul> + <li> + <p>No more binary test <code class="inline-code">jar</code>-s committed + into the source code (instead, they are generated + on-the-fly)</p> + </li> + + <li> + <p>Eclipse project files were removed, instead, the + <code class="inline-code">README</code> describes how to set up the + project.</p> + </li> + </ul> + </li> + </ul> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="versions_2_3_25.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_23.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>
