| <!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.1 - 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="FreeMarker Manual"> |
| <meta property="og:title" content="2.1"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="http://example.com/versions_2_1.html"> |
| <link rel="canonical" href="http://example.com/versions_2_1.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338517553"> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="http://example.com/"> |
| <meta itemprop="name" content="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://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo"> |
| </a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></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">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">Versions</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="versions_2_1.html"><span itemprop="name">2.1</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper no-toc"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| </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_1_1.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_01.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="versions_2_1" itemprop="headline">2.1</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_225" data-menu-target="autoid_225">Changes in FTL (FreeMarker Template Language)</a></li><li><a class="page-menu-link" href="#autoid_226" data-menu-target="autoid_226">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_227" data-menu-target="autoid_227">Other changes</a></li><li><a class="page-menu-link" href="#autoid_228" data-menu-target="autoid_228">Differences between the RC1 and final release</a></li></ul> </div><p>Date of release: 2002-10-17</p><p>Templates and the Java API are <em>not</em> fully |
| compatible with 2.0 releases. You will need to revisit existing code |
| and templates, or use 2.1 for new projects only. Sorry for this |
| inconvenience; FreeMarker has undergone some revolutionary changes |
| since the 1.x series. We hope things will soon be sufficiently mature |
| for us to offer (almost) backward-compatible releases. Note that there |
| is a backward-compatibility flag that can be set via |
| <code class="inline-code">Configuration.setClassicCompatible(true)</code> that |
| causes the new FreeMarker to emulate most of FreeMarker 1.x's |
| quirks.</p> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_225">Changes in FTL (FreeMarker Template Language)</h2> |
| |
| |
| <ul> |
| <li> |
| <p>More strict, reveals accidental mistakes in the templates, |
| prevents showing incorrect information when something went |
| wrong:</p> |
| |
| <ul> |
| <li> |
| <p>An attempt to access an undefined variable causes an |
| error and aborts template processing (by default at least; |
| see later). In earlier versions undefined variables were |
| silently treated as empty (zero-length) strings. However, |
| you can handle undefined variables in the template with some |
| new built-ins. For example, |
| <code class="inline-code">${foo?if_exists}</code> is equivalent with the |
| <code class="inline-code">${foo}</code> of earlier versions. Another way |
| of looking at this is that null values no longer exist from |
| the viewpoint of a template designer. Anything referenced |
| must be a defined variable.</p> |
| |
| <p>Note however that the programmer can configure |
| FreeMarker so that it ignores certain errors (say, undefined |
| variables), and continues template processing by skipping |
| the problematic part. This ``loose'' policy should be used |
| only for sites that don't show critical information.</p> |
| </li> |
| |
| <li> |
| <p>New variable type: <a href="gloss.html#gloss.boolean">boolean</a>. Conditions in |
| <code class="inline-code">if</code>/<code class="inline-code">elseif</code> and operands |
| of logical operators (<code class="inline-code">&&</code>, |
| <code class="inline-code">||</code>, <code class="inline-code">!</code>) must be |
| booleans. Empty strings are no longer treated as a logical |
| false.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Local and global variables. More info: <a href="dgui_misc_var.html">Template Author's Guide/Miscellaneous/Defining variables in the template</a></p> |
| |
| <ul> |
| <li> |
| <p>Local variables for macros. You can create/replace |
| local variables in macro definition bodies with the <a href="ref_directive_local.html#ref.directive.local"><code>local</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>You can create/replace global (non-local) variables |
| with the <a href="ref_directive_global.html#ref.directive.global"><code>global</code> |
| directive</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>The <a href="ref_directive_include.html#ref.directive.include"><code>include</code></a> |
| directive now by default treats the passed filename as being |
| relative to the including template's path. To specify absolute |
| template paths, you now have to prepend them with a |
| slash.</p> |
| </li> |
| |
| <li> |
| <p>The <a href="ref_directive_include.html#ref.directive.include"><code>include</code></a> |
| directive can now use the <em>acquisition |
| algorithm</em> (familiar from the Zope system) to look up |
| the template to include. Basically, if a template is not found |
| where it is looked up first, it is looked up in parent |
| directories. This is however not a default behavior, rather it |
| is triggered by a new syntactic element.</p> |
| </li> |
| |
| <li> |
| <p>Strict syntax mode: Allows you to generate arbitrary SGML |
| (XML) without worrying about clashes with FreeMarker directives. |
| For more information read: <a href="ref_depr_oldsyntax.html">Reference/Deprecated FTL constructs/Old FTL syntax</a></p> |
| </li> |
| |
| <li> |
| <p>Terse comments: you can use <code class="inline-code"><#-- |
| <em class="code-color">...</em> --></code> instead of |
| <code class="inline-code"><comment><em class="code-color">...</em></comment></code></p> |
| </li> |
| |
| <li> |
| <p>Directive that you can use to change the locale (and other |
| settings) inside the template: <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code></a></p> |
| </li> |
| |
| <li> |
| <p>Directive to explicitly flush the output buffer: <a href="ref_directive_flush.html#ref.directive.flush"><code>flush</code></a></p> |
| </li> |
| |
| <li> |
| <p>The top-level (root) hash is available via the variable |
| <code class="inline-code">root</code>, which is now a reserved name.</p> |
| </li> |
| |
| <li> |
| <p>The misnamed <code class="inline-code">function</code> directive has |
| been renamed to <code class="inline-code">macro</code>.</p> |
| </li> |
| |
| <li> |
| <p>String literals support various new <a href="dgui_template_exp.html#topic.escapeSequence">escape sequences</a>, |
| including UNICODE escapes |
| (<code class="inline-code">\x<em class="code-color">CODE</em></code>)</p> |
| </li> |
| |
| <li> |
| <p>The <a href="ref_directive_compress.html#ref.directive.compress"><code>compress</code></a> |
| directive is now more conservative in removing line |
| breaks.</p> |
| </li> |
| |
| <li> |
| <p>Built-in to capitalize the first word: <a href="ref_builtins_string.html#ref_builtin_cap_first"><code>cap_first</code></a></p> |
| </li> |
| |
| <li> |
| <p>Built-in to generate on-the-fly templates: <a href="ref_builtins_expert.html#ref_builtin_interpret"><code>interpret</code></a></p> |
| </li> |
| |
| <li> |
| <p><a href="ref_directive_stop.html#ref.directive.stop"><code>stop</code></a> |
| directive has an optional parameter to describe the reason of |
| termination</p> |
| </li> |
| |
| <li> |
| <p>Better error messages.</p> |
| </li> |
| |
| <li> |
| <p>New variable type: date. <em>Date support is |
| experimental. It can change substantially in the future. Keep |
| this in mind if you use it.</em></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_226">Changes on the Java side</h2> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">ObjectWrapper</code>: You can put |
| non-<code class="inline-code">TemplateModel</code> objects directly into |
| hashes, sequences and collections, and they will be |
| automatically wrapped with the appropriate |
| <code class="inline-code">TemplateModel</code> implementation. The API of |
| objects that are exposed to templates |
| (<code class="inline-code">Simple<em class="code-color">XXX</em></code>) has |
| been changed according to this, for example in |
| <code class="inline-code">SimpleHash</code> the old <code class="inline-code">put(String key, |
| TemplateModel value)</code> is now <code class="inline-code">put(String key, |
| Object object)</code>. Also, you can pass any kind of object |
| as data-model to <code class="inline-code">Template.process</code>. The |
| alternative reflection based <code class="inline-code">ObjectWrapper</code> |
| can expose the members of any Java object automatically for the |
| designer. More information: <a href="pgui_datamodel_objectWrapper.html">Object wrapping</a>, |
| <a href="pgui_misc_beanwrapper.html">Bean wrapper</a>, <a href="pgui_misc_jythonwrapper.html">Jython wrapper</a>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">Configuration</code> object was introduced |
| as a central point to hold all your FreeMarker-related global |
| settings, as well as commonly used variables that you want to |
| have available from any template. Also it encapsulates the |
| template cache and can be used to load templates. For more |
| information read <a href="pgui_config.html">Programmer's Guide/The Configuration</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateLoader</code>: pluggable template |
| loader, separates caching from template loading</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateNumberModel</code>-s do not control |
| their formatting anymore. They just store the data (i.e. a |
| number). Number formatting is done by the FreeMarker core based |
| on the <code class="inline-code">locale</code> and |
| <code class="inline-code">number_format</code> settings. This logic applies to |
| the new experimental date type as well.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateBooleanModel</code> introduced: Only |
| objects that implements this interface can be used as a boolean |
| in true/false conditions. More info: <a href="pgui_datamodel_scalar.html">Programmer's Guide/The Data Model/Scalars</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateDateModel</code> introduced: objects |
| that implements this interface are recognized as dates and can |
| be locale-sensitively formatted. <em>Date support is |
| experimental in FreeMarker 2.1. It can change substantially in |
| the future. Keep this in mind if you use it.</em></p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">TemplateModelRoot</code> interface was |
| deprecated. As of FreeMarker 2.1, you can simply use any |
| instance of <code class="inline-code">TemplateHashModel</code> instead. This |
| actually is due to a significant architectural change. Variables |
| set or defined in a template are stored in a separate |
| <code class="inline-code">Environment</code> object that only exists while the |
| template is being rendered. Thus, the template doesn't modify |
| the root hash.</p> |
| </li> |
| |
| <li> |
| <p>Changes to transformations</p> |
| |
| <ul> |
| <li> |
| <p>Completely rewritten |
| <code class="inline-code">TemplateTransformModel</code> interface. More |
| flexible, and does not impose output holding. More |
| information: <a href="pgui_datamodel_directive.html">Programmer's Guide/The Data Model/Directives</a></p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">transform</code> directive now takes |
| an optional set of key/value pairs. <code class="inline-code"><transform |
| myTransform; |
| <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>></code>. More |
| information: <a href="ref_depr_transform.html#ref.directive.transform"><code>transform</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>The transforms that ship with the FreeMarker core are |
| now available by default to all templates - i.e. |
| <code class="inline-code"><transform html_escape></code> will invoke |
| the |
| <code class="inline-code">freemarker.template.utility.HtmlEscape</code> |
| transform. More information: <a href="pgui_config_sharedvariables.html">Programmer's Guide/The Configuration/Shared variables</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>User-defined <code class="inline-code">TemplateModel</code> objects now |
| can access the runtime environment (read and set variables, get |
| the current locale, etc.) using an |
| <code class="inline-code">Environment</code> instance, which can be obtained |
| by the static |
| <code class="inline-code">Environment.getCurrentEnvironment()</code> method. |
| As a result, <code class="inline-code">TemplateScalarModel.getAsString</code> |
| has been changed: it has no locale parameter.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateExceptionHandler</code>-s make it |
| possible to define your own rules on what to do when a runtime |
| error occurs (e.g. accessing a non existing variable) during |
| template processing. For example, you can abort template |
| processing (recommended for most sites), or skip the problematic |
| statement and continue template processing (similar to old |
| behavior). DebugMode has been removed, use |
| <code class="inline-code">TemplateExceptionHandler.DEBUG_HANDLER</code> or |
| <code class="inline-code">HTML_DEBUG_HANDLER</code> instead.</p> |
| </li> |
| |
| <li> |
| <p>Logging: FreeMarker logs certain events (runtime errors |
| for example). For more information read <a href="pgui_misc_logging.html">Programmer's Guide/Miscellaneous/Logging</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">SimpleIterator</code> was removed, but we |
| provide a <code class="inline-code">TemplateCollectionModel</code> |
| implementation: <code class="inline-code">SimpleCollection</code>.</p> |
| </li> |
| |
| <li> |
| <p>Arithmetic engine is pluggable |
| (<code class="inline-code">Configuration.setArithmeticEngine</code>). The core |
| distribution comes with two engines: |
| <code class="inline-code">ArithmeticEngine.BIGDECIMAL_ENGINE</code> (the |
| default) that converts all numbers to |
| <code class="inline-code">BigDecimal</code> and then operates on them, and |
| <code class="inline-code">ArithmeticEngine.CONSERVATIVE_ENGINE</code> that |
| uses (more-or-less) the widening conversions of Java language, |
| instead of converting everything to |
| <code class="inline-code">BigDecimal</code>.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">freemarker.ext.beans</code> |
| package: The JavaBeans adapter layer has suffered several major |
| changes. First, <code class="inline-code">BeansWrapper</code> is no longer a |
| static utility class - you can now create instances of it, and |
| every instance can have its own instance caching policy and |
| security settings. These security settings are also new - you |
| can now create JavaBeans wrappers that hide methods that are |
| considered unsafe or inappropriate in a templating environment. |
| By default, you can no longer call methods like |
| <code class="inline-code">System.exit()</code> from the template (although you |
| can manually turn off these safeguards). The |
| <code class="inline-code">StaticModel</code> and |
| <code class="inline-code">StaticModels</code> classes are gone; their |
| functionality is now replaced with the |
| <code class="inline-code">BeansWrapper.getStaticModels()</code> method.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.ext.jython</code> package: |
| FreeMarker can now directly use Jython objects as data-models |
| using the <a href="pgui_misc_jythonwrapper.html">Jython |
| wrapper</a>.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">freemarker.ext.jdom</code> package: |
| The package now uses the <em>Jaxen</em> package |
| instead of its predecessor, the |
| <em>werken.xpath</em> package to evaluate XPath |
| expressions. Since <em>Jaxen</em> is a successor to |
| <em>werken.xpath</em>, this can be considered to be |
| an upgrade. As a consequence, namespace prefixes are now |
| recognized in XPath expressions and the overall XPath |
| conformance is better.</p> |
| </li> |
| |
| <li> |
| <p>Better error reporting: If the processing of a template is |
| aborted by a <code class="inline-code">TemplateException</code> being thrown, |
| or using a <code class="inline-code"><#stop></code> directive, |
| FreeMarker will now output an execution trace with line and |
| column numbers relative to the template source.</p> |
| </li> |
| |
| <li> |
| <p>The output is written to a simple |
| <code class="inline-code">Writer</code>; no more |
| <code class="inline-code">PrintWriter</code>. This redesign causes FreeMarker |
| to no longer swallow <code class="inline-code">IOException</code>s during |
| template processing.</p> |
| </li> |
| |
| <li> |
| <p>Various API cleanups, primarily the removing of |
| superfluous constructor and method overloads.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_227">Other changes</h2> |
| |
| |
| <ul> |
| <li> |
| <p>Documentation has been rewritten from scratch</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_228">Differences between the RC1 and final release</h2> |
| |
| |
| <ul> |
| <li> |
| <p>Added the support for date models and locale-sensitive |
| date formatting. <em>Date support is experimental in |
| FreeMarker 2.1. It can change substantially in the future. Keep |
| this in mind if you use it.</em></p> |
| </li> |
| |
| <li> |
| <p>Added the <code class="inline-code">default</code> built-in which makes |
| it possible to specify default values for undefined |
| expressions.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">SimpleIterator</code> has been removed, |
| <code class="inline-code">SimpleCollection</code> has been introduced</p> |
| </li> |
| |
| <li> |
| <p>Arithmetic engine is pluggable. The core now contains two |
| arithmetic engines: |
| <code class="inline-code">ArithmeticEngine.BIGDECIMAL_ENGINE</code> and |
| <code class="inline-code">ArithmeticEngine.CONSERVATIVE_ENGINE</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">BeansWrapper</code> supports a new exposure |
| level: <code class="inline-code">EXPOSE_NOTHING</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Constants</code> interface was removed. |
| <code class="inline-code"><em class="code-color">...</em>_WRAPPER</code> |
| constants have been moved from <code class="inline-code">Constants</code> to |
| <code class="inline-code">ObjectWrapper</code>, |
| <code class="inline-code">EMPTY_STRING</code> constant was moved to |
| <code class="inline-code">TemplateScalarModel</code>, |
| <code class="inline-code">NOTHING</code> constant was moved to |
| <code class="inline-code">TemplateModel</code>, <code class="inline-code">TRUE</code> and |
| <code class="inline-code">FALSE</code> constants were moved to |
| <code class="inline-code">TemplateBooleanModel</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">JAVABEANS_WRAPPER</code> was renamed to |
| <code class="inline-code">BEANS_WRAPPER</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Configuration.get</code> and |
| <code class="inline-code">put</code>, <code class="inline-code">putAll</code> were renamed |
| to <code class="inline-code">getSharedVariable</code> and |
| <code class="inline-code">setSharedVariable</code>, |
| <code class="inline-code">setAllSharedVariables</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Configuration.getClassicCompatibility</code>, |
| <code class="inline-code">setClassicCompatibility</code> were renamed to |
| <code class="inline-code">isClassicCompatible</code>, |
| <code class="inline-code">setClassicCompatible</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Template.process</code> method overloads with |
| <code class="inline-code">useReflection</code> parameter was removed. But now |
| we have <code class="inline-code">setObjectWrapper</code> method in the |
| <code class="inline-code">Configuration</code>, so you can set the preferred |
| root-object wrapper there.</p> |
| </li> |
| |
| <li> |
| <p>Some superfluous method overloads were removed; these |
| changes are backward compatible with RC1</p> |
| </li> |
| |
| <li> |
| <p>Various minor JavaDoc and Manual improvements</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">include</code> directive has |
| calculated the base path of relative paths wrongly</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: We have accidentally used a J2SE 1.3 class, but |
| FreeMarker 2.1 must able to run on J2SE 1.2</p> |
| </li> |
| </ul> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="versions_2_1_1.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_01.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2020-07-09T23:48:37Z" title="Thursday, July 9, 2020 11:48:37 PM GMT">2020-07-09 23:48:37 GMT</time> </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2020 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p> |
| </div></div></div></body> |
| </html> |