| <!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.32 - 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.32"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/versions_2_3_32.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/versions_2_3_32.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://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?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.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="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.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="search-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"> <div class="breadcrumbs"> |
| <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="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="versions_2_3_32.html"><span itemprop="name">2.3.32</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><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.32"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="app_versions.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_31.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="versions_2_3_32" itemprop="headline">2.3.32</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_150" data-menu-target="autoid_150">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_151" data-menu-target="autoid_151">Changes on the Java side</a></li></ul> </div><p>Release date: 2023-01-12</p> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_150">Changes on the FTL side</h2> |
| |
| |
| <ul> |
| <li> |
| <p>Improved outputting values for computer/parser consumption |
| (such as for generating JSON, JavaScript values, values encoded |
| into URL-s):</p> |
| |
| <ul> |
| <li> |
| <p>Added new configuration setting, <a href="gloss.html#gloss.c_format"><code>c_format</code></a> |
| (also settable via the <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code> |
| directive</a>). This specifies what syntax to use when |
| formatting values for computer consumption/parser, like |
| <code class="inline-code">"JSON"</code>. Most prominently, this affects |
| the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code> |
| built-in</a>, hence the name. See valid setting values, |
| and their meaning here: <a href="dgui_misc_computer_vs_human_format.html">Template Author's Guide/Miscellaneous/Formatting for humans, or for computers</a>.</p> |
| |
| <p>If you set the <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set"><code>incompatible_improvements</code> |
| setting</a> to 2.3.32, the default of |
| <code class="inline-code">c_format</code> changes from |
| <code class="inline-code">"legacy"</code> to <code class="inline-code">"JavaScript or |
| JSON"</code>, which is a format that most targets can |
| parse (because we just format simple values, not lists and |
| maps). With lower |
| <code class="inline-code">incompatible_improvements</code>, the default |
| value is <code class="inline-code">"legacy"</code> that emulates the old |
| behavior of <code class="inline-code">?c</code> (where you can lose |
| numerical precision, etc.), so it's recommended to set it to |
| something else.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"><a href="ref_builtins_number.html#ref_builtin_c">?c</a></code> now formats |
| string values to string literals (with quotation marks and |
| escaping), according the language specified in the <a href="gloss.html#gloss.c_format"><code>c_format</code> |
| setting</a>, such as <code class="inline-code">JSON</code>, |
| <code class="inline-code">Java</code>, etc. Earlier, <code class="inline-code">?c</code> |
| only allowed numbers, and booleans.</p> |
| |
| <p>To generate JSON, you can now write a piece of |
| template like this:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">"fullName": ${user.fullName?c},</pre> </div> |
| |
| |
| <p>Then the output will be like:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">"fullName": "John Doe",</pre> </div> |
| |
| |
| <p>Note that the quotation marks were added by |
| <code class="inline-code">?c</code>, and weren't typed into the |
| template.</p> |
| </li> |
| |
| <li> |
| <p>Added <a href="ref_builtins_number.html#ref_builtin_cn">?cn</a>, which |
| is like <code class="inline-code"><a href="ref_builtins_number.html#ref_builtin_c">?c</a></code>, except if the |
| value is <code class="inline-code">null</code>/missing, it will output a |
| <code class="inline-code">null</code> literal, according the language |
| specified in the new <a href="gloss.html#gloss.c_format"><code>c_format</code> |
| setting</a>.</p> |
| |
| <p>Let's say, in the previous example |
| <code class="inline-code">user.fullName</code> is expected to be |
| <code class="inline-code">null</code> sometimes. Then you can just use |
| <code class="inline-code">?cn</code> instead if |
| <code class="inline-code">?c</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">"fullName": ${user.fullName?cn},</pre> </div> |
| |
| |
| <p>If said variable is <code class="inline-code">null</code>, the |
| output will be like this (otherwise it will be a quoted |
| string like earlier):</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">"fullName": null,</pre> </div> |
| |
| |
| <p>Note that with this approach you don't complicate the |
| template anymore to avoid printing quotation marks. Of |
| course, <code class="inline-code">?cn</code> works on numerical and |
| boolean values as well (and of course those won't be quoted, |
| only strings).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">c_format</code>-s other than |
| <code class="inline-code">"legacy"</code> use slightly different number |
| formatting than <code class="inline-code">?c</code> did in earlier |
| versions. The change affects some non-whole numbers, and |
| whole numbers with over 100 digits. The goal of this change |
| is to make the formatting lossless, and also to avoiding |
| huge output with exponents of high magnitude. See details at |
| the documentation of the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code> |
| built-in</a>.</p> |
| |
| <p>Setting the <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set"><code>incompatible_improvements</code> |
| setting</a> to 2.3.32 will change the default of |
| <code class="inline-code">c_format</code> for <code class="inline-code">"legacy"</code> |
| to <code class="inline-code">"JavaScript or JSON"</code>, and therefore |
| changes number formatting too.</p> |
| |
| <p>Of course, all this only affects number formatting |
| done with <code class="inline-code">?c</code>, <code class="inline-code">?cn</code>, and |
| with <code class="inline-code">"c"</code> (or |
| <code class="inline-code">"computer"</code>) |
| <code class="inline-code">number_format</code>, and not number formatting |
| in general.</p> |
| </li> |
| |
| <li> |
| <p>For consistency, when setting the |
| <code class="inline-code">number_format</code> setting (also when |
| formatting with |
| <code class="inline-code">?string(<em class="code-color">format</em>)</code>), |
| now <code class="inline-code">"c"</code> can be used instead of |
| "computer". Both has the same effect on |
| formatting, but <code class="inline-code">"c"</code> is preferred from now |
| on.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/FREEMARKER-208">FREEMARKER-208</a>: |
| Added <a href="ref_builtins_string.html#ref_builtin_c_lower_case"><code>?c_lower_case</code></a>, |
| and <a href="ref_builtins_string.html#ref_builtin_c_upper_case"><code>?c_upper_case</code></a>, |
| which are the non-localized (computer language) variants of |
| <code class="inline-code">?lower_case</code>, and |
| <code class="inline-code">?upper_case</code>. The primary problem people run |
| into with the localized versions is that with Turkish locale the |
| letter <code class="inline-code">i</code>, and <code class="inline-code">I</code> has |
| different conversions than in most languages, which causes |
| problem if the conversion was for computer consumption (for |
| technical purposes), and not for humans.</p> |
| </li> |
| |
| <li> |
| <p>In <code class="inline-code">freemarker.ext.xml</code>, which is the |
| old, long deprecated XML wrapper, that almost nobody uses |
| anymore (the commonly used one is |
| <code class="inline-code">freemarker.ext.dom</code>), the |
| <code class="inline-code">_registerNamespace</code> key now works, doing what |
| the documentation always stated. Before this fix it just behaved |
| as if it was the name of an element you are looking for.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_151">Changes on the Java side</h2> |
| |
| |
| <ul> |
| <li> |
| <p>Added <code class="inline-code">Configurable.setCFormat(CFormat)</code>, |
| with the usual accompanying setting API methods/constants. See |
| the <code class="inline-code">c_format</code>-, and the |
| <code class="inline-code">?c</code>-related changes earlier in the FTL |
| section.</p> |
| </li> |
| |
| <li> |
| <p>Added |
| <code class="inline-code">Environment.getCTemplateNumberFormat()</code> that |
| returns a |
| <code class="inline-code">freemarker.core.TemplateNumberFormat</code>, and |
| deprecated <code class="inline-code">getCNumberFormat()</code> that returns a |
| <code class="inline-code">java.text.NumberFormat</code>. The behavior defined |
| in the <code class="inline-code">CFormat</code> (see earlier) is only |
| reflected exactly by the return value of the new method. The |
| deprecated method returns a format that's a best effort |
| approximation.</p> |
| </li> |
| |
| <li> |
| <p>Added |
| <code class="inline-code">freemarker.core.MarkupOutputFormat.outputForeign(MO2 |
| mo, Writer out)</code> method, which for a |
| <code class="inline-code">MarkupOutputFormat</code> where |
| <code class="inline-code">isOutputFormatMixingAllowed()</code> returns |
| <code class="inline-code">true</code>, allows full control over how to print a |
| different markup into it. This can check what other markup is |
| allowed, and do conversion if necessary. (<a href="https://github.com/apache/freemarker/pull/83">GitHub |
| PR 83</a>)</p> |
| </li> |
| |
| <li> |
| <p>Fixed performance bug with XML processing |
| (<code class="inline-code">freemarker.ext.dom</code>) when converting an XML |
| element that contains lots of text nodes (instead of a single |
| big text node) to a string. (<a href="https://github.com/apache/freemarker/pull/82">GitHub |
| PR 82</a>)</p> |
| </li> |
| |
| <li> |
| <p>Improved <code class="inline-code">StringUtil.jsStringEnc</code> and |
| <code class="inline-code">javaSctringEnc</code> to support quoting. Also |
| <code class="inline-code">jsStringEnc</code> now have a mode that targets both |
| JavaScript and JSON, and doesn't give up apostrophe |
| escaping.</p> |
| </li> |
| |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/FREEMARKER-198">FREEMARKER-198</a>: |
| Fixed possible deadlock when the |
| <code class="inline-code">Configuration</code>, and |
| <code class="inline-code">DefaultObjectWrapper</code> class |
| <em>static</em> initialization is triggered in |
| different threads around the same time. (In the very unlikely |
| case your application can run into this, this will hang the code |
| that initializes FreeMarker before it has processed any |
| templates, and it can't happen anymore if any template |
| processing managed to start.)</p> |
| </li> |
| |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/FREEMARKER-190">FREEMARKER-190</a>: |
| Updated dom4j version used during FreeMarker project compilation |
| from 1.3 to 2.1.3. Users can still use FreeMarker with dom4j 1.3 |
| (mostly just luck, but it works). FreeMarker's dom4j support is |
| long deprecated anyway, and almost nobody uses it anyway. We |
| were forced to do this change because old dom4j versions have |
| security vulnerabilities, and although FreeMarker is not |
| affected by them (like we do not pull in dom4j as dependency |
| into the projects of our users), we were flagged as vulnerable |
| at certain places for merely supporting 1.3.</p> |
| </li> |
| |
| <li> |
| <p>Slightly improved |
| <code class="inline-code">DefaultMemberAccessPolicy-rules</code> (used by |
| default), and <code class="inline-code">unsafeMethods.properties</code> (long |
| deprecated, not used by default). Note that no matter how much |
| we tweak these, they will never provide proper security if you |
| have untrusted templates! See <a href="app_faq.html#faq_template_uploading_security">this in the |
| FAQ</a>!</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_31.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="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.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><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/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: |
| <time itemprop="dateModified" datetime="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <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> |
