You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2017/03/13 10:57:47 UTC
[11/50] incubator-freemarker-site git commit: 2.3.26-nightly docs
preview
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/versions_2_3.html
----------------------------------------------------------------------
diff --git a/builds/2.3.26-nightly/versions_2_3.html b/builds/2.3.26-nightly/versions_2_3.html
new file mode 100644
index 0000000..4898aa2
--- /dev/null
+++ b/builds/2.3.26-nightly/versions_2_3.html
@@ -0,0 +1,1629 @@
+<!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 - 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">
+<meta property="og:locale" content="en_US">
+<meta property="og:url" content="http://freemarker.org/docs/versions_2_3.html">
+<link rel="canonical" href="http://freemarker.org/docs/versions_2_3.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.html"><span itemprop="name">2.3</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"];</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_1.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_2_8.html"><span>Next</span></a></div><div class="title-wrapper">
+<h1 class="content-header header-section1" id="versions_2_3" itemprop="headline">2.3</h1>
+</div></div><div class="page-menu">
+<div class="page-menu-title">Page Contents</div>
+<ul><li><a class="page-menu-link" href="#autoid_220" data-menu-target="autoid_220">Non backward-compatible changes!</a></li><li><a class="page-menu-link" href="#autoid_221" data-menu-target="autoid_221">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_222" data-menu-target="autoid_222">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_223" data-menu-target="autoid_223">Other changes</a></li><li><a class="page-menu-link" href="#autoid_224" data-menu-target="autoid_224">The history of the releases before the final version</a><ul><li><a class="page-menu-link" href="#autoid_225" data-menu-target="autoid_225">Differences between the final release and Release Candidate
+4</a></li><li><a class="page-menu-link" href="#autoid_226" data-menu-target="autoid_226">Differences between the Release Candidate 4 and Release
+Candidate 3</a></li><li><a class="page-menu-link" href="#autoid_227" data-menu-target="autoid_227">Differences between the Release Candidate 3 and Release
+Candidate 2</a></li><li><a class="page-menu-link" href="#autoid_228" data-menu-target="autoid_228">Differences between the Release Candidate 2 and Release
+Candidate 1</a></li><li><a class="page-menu-link" href="#autoid_229" data-menu-target="autoid_229">Differences between the Release Candidate 1 and Preview 16
+releases</a></li><li><a class="page-menu-link" href="#autoid_230" data-menu-target="autoid_230">Differences between the Preview 16 and Preview 15
+releases</a></li><li><a class="page-menu-link" href="#autoid_231" data-menu-target="autoid_231">Differences between the Preview 15 and Preview 14
+releases</a></li><li><a class="page-menu-link" href="#autoid_232" data-menu-target="autoid_232">Differences between the Preview 14 and Preview 13
+releases</a></li><li><a class="page-menu-link" href="#autoid_233" data-menu-target="autoid_233">Differences between the Preview 13 and Preview 12
+releases</a></li><li><a class="page-menu-link" href="#autoid_234" data-menu-target="autoid_234">Differences between the Preview 12 and Preview 11
+releases</a></li><li><a class="page-menu-link" href="#autoid_235" data-menu-target="autoid_235">Differences between the Preview 11 and Preview 10
+releases</a></li><li><a class="page-menu-link" href="#autoid_236" data-menu-target="autoid_236">Differences between the Preview 10 and Preview 9
+releases</a></li><li><a class="page-menu-link" href="#autoid_237" data-menu-target="autoid_237">Differences between the Preview 9 and Preview 8
+releases</a></li><li><a class="page-menu-link" href="#autoid_238" data-menu-target="autoid_238">Differences between the Preview 8 and Preview 7
+releases</a></li><li><a class="page-menu-link" href="#autoid_239" data-menu-target="autoid_239">Differences between the Preview 7 and Preview 6
+releases</a></li><li><a class="page-menu-link" href="#autoid_240" data-menu-target="autoid_240">Differences between the Preview 6 and Preview 5
+releases</a></li><li><a class="page-menu-link" href="#autoid_241" data-menu-target="autoid_241">Differences between the Preview 5 and Preview 4
+releases</a></li><li><a class="page-menu-link" href="#autoid_242" data-menu-target="autoid_242">Differences between the Preview 4 and Preview 3
+releases</a></li><li><a class="page-menu-link" href="#autoid_243" data-menu-target="autoid_243">Differences between the Preview 3 and Preview 2
+releases</a></li><li><a class="page-menu-link" href="#autoid_244" data-menu-target="autoid_244">Differences between the Preview 2 and Preview 1
+releases</a></li></ul></li></ul> </div><p>Date of release: 2004-June-15</p><p>FreeMarker 2.3 introduces numerous little new features and
+ quality improvements compared to the 2.2.x series. The most notable
+ improvements are the ability to define functions (methods) in
+ templates, the ability to interpolate variables in string literals,
+ the support for a variable number of macro parameters, and the more
+ intelligent default object wrapper. Although none of the improvements
+ is a drastic change, the 2.3.x series is not backward compatible with
+ the 2.2.x series (see the list below), so you may choose to use it for
+ new projects only.</p><p>Probably the most "loudly promoted" new feature is
+ the totally redesigned XML wrapper. With the new XML wrapper
+ FreeMarker targets a new application domain, which is similar to the
+ application domain of XSLT: transforming complex XML to whatever
+ textual output. Although this subproject is young, it is definitely
+ usable in practice. See the <a href="xgui.html">XML Processing
+ Guide</a> for more details.</p>
+
+
+
+
+<h2 class="content-header header-section2" id="autoid_220">Non backward-compatible changes!</h2>
+
+
+ <ul>
+ <li>
+ <p>Since interpolations (<code class="inline-code">${...}</code> and
+ <code class="inline-code">#{...}</code>) now work inside string literals, the
+ character sequence <code class="inline-code">${</code> and
+ <code class="inline-code">#{</code> in string literals are reserved for that.
+ So if you have something like <code class="inline-code"><#set x =
+ "${foo}"></code>, then you have to replace it with
+ <code class="inline-code"><#set x = r"${foo}"></code> -- beware, escapes
+ such as <code class="inline-code">\n</code> will not work in raw
+ (<code class="inline-code">r</code>) strings.</p>
+ </li>
+
+ <li>
+ <p>The default (initial) value of the
+ <code class="inline-code">strict_syntax</code> setting has been changed from
+ <code class="inline-code">false</code> to <code class="inline-code">true</code>. When
+ <code class="inline-code">strict_syntax</code> is <code class="inline-code">true</code>,
+ tags with old syntax as <code class="inline-code"><include
+ "foo.ftl"></code> will be considered as static text (so
+ they go to the output as-is, like HTML tags do), and not as FTL
+ tags. Such tags have to be rewritten to <code class="inline-code"><#include
+ "foo.ftl"></code>, since only parts that starts with
+ <code class="inline-code"><#</code>, <code class="inline-code"></#</code>,
+ <code class="inline-code"><@</code>, or <code class="inline-code"></@</code> count as
+ FTL tags. Or, to recover the old transitional behavior, where
+ both legacy and new tag syntax was recognized, you have to
+ explicitly set <code class="inline-code">strict_syntax</code> to
+ <code class="inline-code">false</code>:
+ <code class="inline-code">cfg.setStrictSyntaxMode(false)</code>. Also, for
+ individual templates you can force the old behavior by starting
+ the template with <code class="inline-code"><#ftl
+ strict_syntax=false></code>. (For more information about
+ why strict syntax is better than old syntax <a href="ref_depr_oldsyntax.html">read this...</a>)</p>
+ </li>
+
+ <li>
+ <p>Several classes were moved from the
+ <code class="inline-code">freemarker.template</code> package, to the new
+ <code class="inline-code">freemarker.core</code> package:</p>
+
+ <ul>
+ <li>
+ "Normal" classes: <code class="inline-code">ArithmeticEngine</code>,
+ <code class="inline-code">Configurable</code>,
+ <em><code class="inline-code">Environment</code></em>
+ </li>
+
+ <li>
+ Exceptions:
+ <code class="inline-code">InvalidReferenceException</code>,
+ <code class="inline-code">NonBooleanException</code>,
+ <code class="inline-code">NonNumericalException</code>,
+ <code class="inline-code">NonStringException</code>,
+ <code class="inline-code">ParseException</code>,
+ <code class="inline-code">StopException</code>
+ </li>
+
+ <li>
+ Errors: <code class="inline-code">TokenMgrError</code>
+ </li>
+ </ul>
+
+ <p>The main reason of the splitting of
+ <code class="inline-code">freemarker.template</code> package was that the
+ amount of "expert" public classes and interfaces grows too much,
+ as we introduce API-s for third-party tools, such as debugging
+ API.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">freemarker.template.TemplateMethodModel.exec</code>
+ now returns <code class="inline-code">Object</code> instead of
+ <code class="inline-code">TemplateModel</code>.</p>
+ </li>
+
+ <li>
+ <p>White-space stripping is now more aggressive as before: it
+ always removes leading and trailing white-space if the line only
+ contains FTL tags. (Earlier the white-space was not removed if
+ the tag was <code class="inline-code"><#include
+ <em class="code-color">...</em>></code> or user-defined
+ directive tag with empty directive syntax as
+ <code class="inline-code"><@myMacro/></code> (or its equivalents:
+ <code class="inline-code"><@myMacro></@myMacro></code> and
+ <code class="inline-code"><@myMacro></@></code>). Now white-space
+ is removed in these cases as well.) Also, white-space sandwiched
+ between two non-outputting elements, such as macro definitions,
+ assignments, imports, or property settings, is now ignored. More
+ information: <a href="dgui_misc_whitespace.html#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">function</code> directive is now used for
+ defining methods. You should replace <code class="inline-code">function</code>
+ with <code class="inline-code">macro</code> in your old templates. Note,
+ however, that old <code class="inline-code">function</code>-s will still work
+ if you don't use the <code class="inline-code">return</code> directive in
+ them, and you invoke them with the deprecated the
+ <code class="inline-code">call</code> directive.</p>
+ </li>
+
+ <li>
+ <p>The expressions <code class="inline-code">as</code>,
+ <code class="inline-code">in</code>, and <code class="inline-code">using</code> are now
+ keywords in the template language and cannot be used as
+ top-level variable names without square-bracket syntax. If, by
+ some chance, you have top-level variables that use one of these
+ names, you will have to rename them, or use the square-bracket
+ syntax with the <code class="inline-code">.vars</code> special variable:
+ <code class="inline-code">.vars["in"]</code>.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">?new</code> built-in, as it was
+ implemented, was a security hole. Now, it only allows you to
+ instantiate a java object that implements the
+ <code class="inline-code">freemarker.template.TemplateModel</code> interface.
+ If you want the functionality of the <code class="inline-code">?new</code>
+ built-in as it existed in prior versions, make available an
+ instance of the
+ <code class="inline-code">freemarker.template.utility.ObjectConstructor</code>
+ class to your template. (For example:
+ <code class="inline-code">myDataModel.put("objConstructor", new
+ ObjectConstructor());</code>, and then in the template you
+ can do this: <code class="inline-code"><#assign aList =
+ objConstructor("java.util.ArrayList", 100)></code>)</p>
+ </li>
+
+ <li>
+ <p>Changes to the
+ <code class="inline-code">FreemarkerServlet</code>:</p>
+
+ <ul>
+ <li>
+ <p>The <code class="inline-code">FreemarkerServlet</code> uses
+ <code class="inline-code">ObjectWrapper.DEFAULT_WRAPPER</code> by default
+ instead of <code class="inline-code">ObjectWrapper.BEANS_WRAPPER</code>.
+ What this means is that, by default, objects of type
+ <code class="inline-code">java.lang.String</code>,
+ <code class="inline-code">java.lang.Number</code>,
+ <code class="inline-code">java.util.List</code>, and
+ <code class="inline-code">java.util.Map</code> will be wrapped as
+ <code class="inline-code">TemplateModels</code> via the classes
+ <code class="inline-code">SimpleScalar</code>,
+ <code class="inline-code">SimpleNumber</code>,
+ <code class="inline-code">SimpleSequence</code>, and
+ <code class="inline-code">SimpleHash</code> respectively. Thus, the java
+ methods on those objects will not be available. The default
+ wrapper implementation in FreeMarker 2.3 automatically knows
+ how to wrap Jython objects, and also wraps
+ <code class="inline-code">org.w3c.dom.Node</code> objects into instances
+ of <code class="inline-code">freemarker.ext.dom.NodeModel</code>.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">FreemarkerServlet</code> base
+ implementation no longer deduces the locale used for
+ templates with <code class="inline-code">HttpRequest.getLocale()</code>.
+ Rather, it simply delegates to the new protected method,
+ <code class="inline-code">deduceLocale</code>. The default implementation
+ of this method simply returns the value of configuration the
+ <code class="inline-code">locale</code> setting.</p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+
+<h2 class="content-header header-section2" id="autoid_221">Changes on the FTL side</h2>
+
+
+ <ul>
+ <li>
+ <p>Interpolation in string literals. For convenience,
+ interpolations are now supported in string literals. For
+ example: <code class="inline-code"><@message�"Hello�${user}!"�/></code>
+ is the same as <code class="inline-code"><@message "Hello " + user + "!"
+ /></code></p>
+ </li>
+
+ <li>
+ <p>Raw string literals: In string literals prefixed with
+ <code class="inline-code">r</code>, interpolations and escape sequences will
+ not be interpreted as special tokens. For example:
+ <code class="inline-code">r"\n${x}"</code> will be simply interpreted as the
+ character sequence <code class="inline-code">'\'</code>,
+ <code class="inline-code">'n'</code>, <code class="inline-code">'$'</code>,
+ <code class="inline-code">'{'</code>, <code class="inline-code">'x'</code>,
+ <code class="inline-code">'}'</code>, and not as line-feed and the value of
+ the <code class="inline-code">x</code> variable.</p>
+ </li>
+
+ <li>
+ <p>Method variables can be defined in FTL, with the <a href="ref_directive_function.html#ref.directive.function"><code>function</code></a>
+ directive.</p>
+ </li>
+
+ <li>
+ <p>Support for a variable number of macro parameters. If the
+ last parameter in a macro declaration ends with
+ <code class="inline-code">...</code>, all extra parameters passed to the macro
+ will be available via that parameter. For macros called with
+ positional parameters, the parameter will be a sequence. For
+ named parameters, the parameter will be a hash. Note that it all
+ works with the new <code class="inline-code">function</code> directive as
+ well.</p>
+ </li>
+
+ <li>
+ <p>A new header parameter, <code class="inline-code">strip_text</code>,
+ that removes all top-level text from a template. This is useful
+ for "include files" to suppress newlines that
+ separate the macro definitions. See <a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code>
+ directive</a></p>
+ </li>
+
+ <li>
+ <p>New <a href="ref_specvar.html">special variable</a>:
+ <code class="inline-code">.vars</code>. This is useful to read top-level
+ variables with square bracket syntax, for example
+ <code class="inline-code">.vars["name-with-hyphens"]</code> and
+ <code class="inline-code">.vars[dynamicName]</code>.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">macro</code> and assignment directives now
+ accept arbitrary destination variable name with quoted syntax.
+ For example: <code class="inline-code"><#macro
+ "name-with-hyphens"><em class="code-color">...</em></code>
+ or <code class="inline-code"><#assign "foo�bar" = 123></code>.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">?keys</code> and
+ <code class="inline-code">?values</code> hash built-ins now return sequences.
+ In practical terms this means you can access their sizes or
+ retrieve their sub variables by index, and use all of the <a href="ref_builtins_sequence.html">sequence built-ins</a>. (Note
+ for the programmers: The <code class="inline-code">TemplateHashModelEx</code>
+ interface has not been changed. Your old code will work. See the
+ API documentation to see why.)</p>
+ </li>
+
+ <li>
+ <p>Existence built-ins (<code class="inline-code">?default</code>,
+ <code class="inline-code">?exists</code>, etc.) are now working with sequence
+ sub variables as well. Read the documentation of the
+ <code class="inline-code">default</code> built-in for more information.</p>
+ </li>
+
+ <li>
+ <p>White-space stripping is now more aggressive as before: it
+ always removes leading and trailing white-space if the line only
+ contains FTL tags. (Earlier the white-space was not removed if
+ the tag was <code class="inline-code"><#include
+ <em class="code-color">...</em>></code> or user-defined
+ directive tag with empty directive syntax as
+ <code class="inline-code"><@myMacro/></code> (or its equivalents:
+ <code class="inline-code"><@myMacro></@myMacro></code> and
+ <code class="inline-code"><@myMacro></@></code>). Now white-space
+ is removed in these cases as well.) Also, top-level white-space
+ that separates macro definitions and/or assignments is now
+ ignored. More information: <a href="dgui_misc_whitespace.html#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p>
+ </li>
+
+ <li>
+ <p>White-space stripping can be disabled for a single line
+ with the <a href="ref_directive_nt.html#ref.directive.nt"><code>nt</code></a>
+ directive (for No Trim).</p>
+ </li>
+
+ <li>
+ <p>Hashes can be concatenated using the <code class="inline-code">+</code>
+ operator. The keys in the hash on the right-hand side take
+ precedence.</p>
+ </li>
+
+ <li>
+ <p>New built-ins for Java and JavaScript string escaping:
+ <a href="ref_builtins_string.html#ref_builtin_j_string">j_string</a> and <a href="ref_builtins_string.html#ref_builtin_js_string">js_string</a></p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">replace</code> and
+ <code class="inline-code">split</code> built-ins now support case-insensitive
+ comparsion and regular expressions (J2SE 1.4+ only), and some
+ other new options. More information can be found <a href="ref_builtins_string.html#ref_builtin_string_flags">here</a>.</p>
+ </li>
+
+ <li>
+ <p>New built-in for regular expression matching (J2SE 1.4+
+ only): <a href="ref_builtins_string.html#ref_builtin_matches"><code>matches</code></a></p>
+ </li>
+
+ <li>
+ <p>New built-in, <code class="inline-code">eval</code>, to evaluate a
+ string as FTL expression. For example
+ <code class="inline-code">"1+2"?eval</code> returns the number 3.</p>
+ </li>
+
+ <li>
+ <p>New built-ins for Java and JavaScript string escaping:
+ <a href="ref_builtins_string.html#ref_builtin_j_string">j_string</a> and <a href="ref_builtins_string.html#ref_builtin_js_string">js_string</a></p>
+ </li>
+
+ <li>
+ <p>New special variables to read the value of the locale
+ setting: <code class="inline-code">locale</code>, <code class="inline-code">lang</code>. See
+ more <a href="ref_specvar.html">in the
+ reference...</a></p>
+ </li>
+
+ <li>
+ <p>New special variable to read the FreeMarker version
+ number: <code class="inline-code">version</code>. See more <a href="ref_specvar.html">in the reference...</a></p>
+ </li>
+
+ <li>
+ <p>Tree new directives, <code class="inline-code">recurse</code>,
+ <code class="inline-code">visit</code> and <code class="inline-code">fallback</code>, were
+ introduced to support declarative node-tree processing. These
+ are meant to be used typically (though not exclusively) for
+ processing XML input. Together with this, a new variable type
+ has been introduced, the node type. See the <a href="xgui_declarative.html">chapter on declarative XML
+ processing</a> for more details.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">?new</code> built-in, as it was
+ implemented, was a security hole. Now, it only allows you to
+ instantiate a java object that implements the
+ <code class="inline-code">freemarker.template.TemplateModel</code> interface.
+ <span class="marked-for-programmers">If you want the functionality of
+ the <code class="inline-code">?new</code> built-in as it existed in prior
+ versions, make available an instance of the
+ <code class="inline-code">freemarker.template.utility.ObjectConstructor</code>
+ class to your template. (For example:
+ <code class="inline-code">myDataModel.put("objConstructor", new
+ ObjectConstructor());</code>, and then in the template you
+ can do this: <code class="inline-code"><#assign aList =
+ objConstructor("java.util.ArrayList",
+ 100)></code>)</span></p>
+ </li>
+
+ <li>
+ <p>Variable names can contain <code class="inline-code">@</code> anywhere
+ (without using quote-bracket syntax). For example:
+ <code class="inline-code"><#assign x@@@ = 123></code> is valid.</p>
+ </li>
+
+ <li>
+ <p>The expressions <code class="inline-code">as</code>,
+ <code class="inline-code">in</code>, and <code class="inline-code">using</code> are now
+ keywords in the template language and cannot be used as
+ top-level variable names without square-bracket syntax (as
+ <code class="inline-code">.vars["in"]</code>).</p>
+ </li>
+
+ <li>
+ <p>New parameter to the <a href="ref_directive_ftl.html"><code>ftl</code>
+ directive</a>: <code class="inline-code">attributes</code>. The value of
+ this attribute is a hash that associates arbitrary attributes
+ (name-value pairs) to the template. The values of the attributes
+ can be of any type (string, number, sequence... etc.).
+ FreeMarker doesn't try to understand the meaning of the
+ attributes. It's up to the application that encapsulates
+ FreeMarker (as a Web application framework). Thus, the set of
+ allowed attributes and their semantic is application (Web
+ application framework) dependent.</p>
+ </li>
+
+ <li>
+ <p>Other minor quality improvements...</p>
+ </li>
+ </ul>
+
+
+
+
+
+<h2 class="content-header header-section2" id="autoid_222">Changes on the Java side</h2>
+
+
+ <ul>
+ <li>
+ <p>Smarter default object wrapping: The default object
+ wrapper is now
+ <code class="inline-code">freemarker.template.DefaultObjectWrapper</code>,
+ which falls back on wrapping arbitrary objects as beans using
+ the <code class="inline-code">freemarker.ext.beans.BeansWrapper</code>. Also,
+ it will wrap <code class="inline-code">org.w3c.dom.Node</code> objects with
+ the new DOM wrapper. Also, it is aware of Jython objects, and
+ will use <code class="inline-code">freemarker.ext.jython.JythonWrapper</code>
+ if the object passed in is a Jython object. (We count it as a
+ backward compatible change, since this new object wrapper wraps
+ differently only those objects that the old wrapper was not able
+ to wrap, so it has thrown exception.)</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">freemarker.template.TemplateMethodModel.exec</code>
+ now returns <code class="inline-code">Object</code> instead of
+ <code class="inline-code">TemplateModel</code>.</p>
+ </li>
+
+ <li>
+ <p>The default (initial) value of the
+ <code class="inline-code">strict_syntax</code> setting has been changed from
+ <code class="inline-code">false</code> to <code class="inline-code">true</code>. When
+ <code class="inline-code">strict_syntax</code> is <code class="inline-code">true</code>,
+ tags with old syntax as <code class="inline-code"><include
+ "foo.ftl"></code> will be considered as static text (so
+ they go to the output as-is, like HTML tags do), and not as FTL
+ tags. Such tags have to be rewritten to <code class="inline-code"><#include
+ "foo.ftl"></code>, since only parts that starts with
+ <code class="inline-code"><#</code>, <code class="inline-code"></#</code>,
+ <code class="inline-code"><@</code>, or <code class="inline-code"></@</code> count as
+ FTL tags. Or, to recover the old transitional behavior, where
+ both legacy and new tag syntax was recognized, you have to
+ explicitly set <code class="inline-code">strict_syntax</code> to
+ <code class="inline-code">false</code>:
+ <code class="inline-code">cfg.setStrictSyntaxMode(false)</code>. Also, for
+ individual templates you can force the old behavior by starting
+ the template with <code class="inline-code"><#ftl
+ strict_syntax=false></code>. (For more information about
+ why strict syntax is better than old syntax <a href="ref_depr_oldsyntax.html">read this...</a>)</p>
+ </li>
+
+ <li>
+ <p>New <code class="inline-code">CacheStorage</code> implementation:
+ <code class="inline-code">freemarker.cache.MruCacheStorage</code>. This cache
+ storage implements a two-level Most Recently Used cache. In the
+ first level, items are strongly referenced up to the specified
+ maximum. When the maximum is exceeded, the least recently used
+ item is moved into the second level cache, where they are softly
+ referenced, up to another specified maximum.
+ <code class="inline-code">freemarker.cache.SoftCachseStorage</code> and
+ <code class="inline-code">StrongCachseStorage</code> are deprected,
+ <code class="inline-code">MruCachseStorage</code> is used everywhere instead.
+ The default cache storage is now an
+ <code class="inline-code">MruCachseStorage</code> object with 0 strong size,
+ and infinite soft size.
+ <code class="inline-code">Configuration.setSetting</code> for
+ <code class="inline-code">cache_storage</code> now understands string values
+ as <code class="inline-code">"strong:200, soft:2000"</code>.</p>
+ </li>
+
+ <li>
+ <p>For <code class="inline-code">BeansWrapper</code> generated models, you
+ can now use the <code class="inline-code">${obj.method(args)}</code> syntax to
+ invoke methods whose return type is <code class="inline-code">void</code>.
+ <code class="inline-code">void</code> methods now return
+ <code class="inline-code">TemplateModel.NOTHING</code> as their return
+ value.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">freemarker.template.SimpleHash</code> now can
+ wrap read-only <code class="inline-code">Map</code>-s, such as the map of HTTP
+ request parameters in Servlet API.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">TemplateNodeModel</code> interface was
+ introduced to support recursive processing of trees of nodes.
+ Typically, this will be used in relation to XML.</p>
+ </li>
+
+ <li>
+ <p>New package: <code class="inline-code">freemarker.ext.dom</code>. This
+ contains the new XML wrapper, that supports the processing of
+ XML documents using the visitor pattern (i.e. with
+ <code class="inline-code"><#visit <em class="code-color">...</em>></code>
+ and similar directives), and to provide more convenient XML
+ traversing as the legacy wrapper. See the <a href="xgui.html">XML processing guide</a> for more
+ details.</p>
+ </li>
+
+ <li>
+ <p>New package: <code class="inline-code">freemarker.core</code>. Classes
+ used by mostly power-users was moved here from the
+ <code class="inline-code">freemarker.template</code> package. The main reason
+ of the splitting of <code class="inline-code">freemarker.template</code>
+ package was that the amount of "expert" public classes and
+ interfaces grows too much, as we introduce API-s for third-party
+ tools, such as debugging API.</p>
+ </li>
+
+ <li>
+ <p>New package: <code class="inline-code">freemarker.debug</code>. This
+ provides a debugging API, by which you can debug executing
+ templates through network (RMI). You have to write the front-end
+ (client), as the API is just the server side. For more
+ information please read the JavaDoc of the
+ <code class="inline-code">freemarker.debug</code> package.</p>
+ </li>
+
+ <li>
+ <p>You can query the FreeMarker version number with static
+ method <code class="inline-code">Configuration.getVersionNumber()</code>.
+ Also, the <code class="inline-code">Manifest.mf</code> included in
+ <code class="inline-code">freemarker.jar</code> now contains the FreeMarker
+ version number, furthermore, executing it with <code class="inline-code">java
+ -jar freemarker.jar</code> will print the version number to
+ the stdout.</p>
+ </li>
+
+ <li>
+ <p>Added a new protected <code class="inline-code">FreemarkerServlet</code>
+ method: <code class="inline-code">Configuration
+ getConfiguration()</code>.</p>
+ </li>
+
+ <li>
+ <p>Date support is now labeled as final. (It was experimental
+ earlier.)</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">BeansWrapper</code> has been improved to
+ prevent some security exceptions when introspecting.</p>
+ </li>
+
+ <li>
+ <p>Other minor quality improvements and extensions...</p>
+ </li>
+ </ul>
+
+
+
+
+
+<h2 class="content-header header-section2" id="autoid_223">Other changes</h2>
+
+
+ <ul>
+ <li>
+ <p>Fixes and improvements in the Manual and in the API
+ JavaDoc.</p>
+ </li>
+ </ul>
+
+
+
+
+
+<h2 class="content-header header-section2" id="autoid_224">The history of the releases before the final version</h2>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_225">Differences between the final release and Release Candidate
+ 4</h3>
+
+
+ <ul>
+ <li>
+ <p>Added a new special variable to print the FreeMarker
+ version number: <code class="inline-code">version</code>. See more <a href="ref_specvar.html">in the reference...</a></p>
+ </li>
+
+ <li>
+ <p>Minor documentation fixes and improvements.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_226">Differences between the Release Candidate 4 and Release
+ Candidate 3</h3>
+
+
+ <ul>
+ <li>
+ <p>The <code class="inline-code">BeansWrapper</code> has been improved to
+ prevent some security exceptions when introspecting.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">FreemarkerXmlTask</code> has two new
+ sub-tasks that can be used to prepare template execution with
+ Jython scripts: <code class="inline-code">prepareModel</code> and
+ <code class="inline-code">prepareEnvironment</code>. The
+ <code class="inline-code">jython</code> sub-task is now deprecated, and does
+ the same as <code class="inline-code">prepareEnvironment</code>. See the
+ Java API documentation for more details.</p>
+ </li>
+
+ <li>
+ <p>New special variable to read the FreeMarker version
+ number: <code class="inline-code">version</code>. See more <a href="ref_specvar.html">in the reference...</a></p>
+ </li>
+
+ <li>
+ <p>Bugfix: Greater-than sign doesn't confuse the
+ <code class="inline-code">eval</code> built-in anymore.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: The <code class="inline-code">BeansWrapper</code> now wrapps
+ the <code class="inline-code">null</code> return values of methods
+ appropriately.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: The <code class="inline-code">FreemarkerXmlTask</code> doesn't
+ need Jython classes anymore, unless you really use Jython
+ scripts. Several other bugfixes in the Jython related
+ features.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: If the template exception handler has ignored
+ the exception, errors occurring in interpolations inside FTL
+ tags (e.g. <code class="inline-code"><#if "foo${badVar}" !=
+ "foobar"></code>) were handled in the same way as errors
+ occuring in interpolations outside FTL tags. Thus, the
+ directive call was not skipped, and the problematic
+ interpolation was replaced with an empty string. (This was
+ inconsistent with the behavior of <code class="inline-code"><#if
+ "foo"+badVar != "foobar"></code>, which should be 100%
+ equivalent with the previous example.)</p>
+ </li>
+
+ <li>
+ <p>Bugfix: The <code class="inline-code">FileTemplateLoader</code> is now
+ more robust when it receives paths that are malformed
+ according the native file system. In the earlier version such
+ paths sometimes caused unexpected
+ <code class="inline-code">IOException</code> that aborted the searching for
+ the template in further
+ <code class="inline-code">FileTemplateLoader</code>-s when you use the
+ <code class="inline-code">MultiTemplateLoader</code>.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_227">Differences between the Release Candidate 3 and Release
+ Candidate 2</h3>
+
+
+ <ul>
+ <li>
+ <p>Bugfix: Fixing a fatal bug in the template cache that
+ was introduced with the latest cache bugfix. The template
+ cache has always reloaded the unchanged template when the
+ update delay has been elapsed, until the template has been
+ actually changed, in which case it has never reloaded the
+ template anymore.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_228">Differences between the Release Candidate 2 and Release
+ Candidate 1</h3>
+
+
+ <ul>
+ <li>
+ <p>Bugfix: The template cache didn't reload the template
+ when it was replaced with an older version.</p>
+ </li>
+
+ <li>
+ <p>API JavaDoc fix: date/time related classes/interfaces
+ were marked as experimental. They are not experimental.</p>
+ </li>
+
+ <li>
+ <p>Minor site improvements.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_229">Differences between the Release Candidate 1 and Preview 16
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p><em>Warning! Non-backward-compatible
+ change!</em> The default (initial) value of the
+ <code class="inline-code">strict_syntax</code> setting has been changed from
+ <code class="inline-code">false</code> to <code class="inline-code">true</code>. When
+ <code class="inline-code">strict_syntax</code> is <code class="inline-code">true</code>,
+ tags with old syntax as <code class="inline-code"><include
+ "foo.ftl"></code> will be considered as static text (so
+ they go to the output as-is, like HTML tags do), and not as
+ FTL tags. Such tags have to be rewritten to
+ <code class="inline-code"><#include "foo.ftl"></code>, since only
+ parts that starts with <code class="inline-code"><#</code>,
+ <code class="inline-code"></#</code>, <code class="inline-code"><@</code>, or
+ <code class="inline-code"></@</code> count as FTL tags. Or, to recover
+ the old transitional behavior, where both legacy and new tag
+ syntax was recognized, you have to explicitly set
+ <code class="inline-code">strict_syntax</code> to <code class="inline-code">false</code>:
+ <code class="inline-code">cfg.setStrictSyntaxMode(false)</code>. Also, for
+ individual templates you can force the old behavior by
+ starting the template with <code class="inline-code"><#ftl
+ strict_syntax=false></code>. (For more information about
+ why strict syntax is better than old syntax <a href="ref_depr_oldsyntax.html">read this...</a>)</p>
+ </li>
+
+ <li>
+ <p>New parameter to the <a href="ref_directive_ftl.html"><code>ftl</code>
+ directive</a>: <code class="inline-code">attributes</code>. The value of
+ this attribute is a hash that associates arbitrary attributes
+ (name-value pairs) to the template. The values of the
+ attributes can be of any type (string, number, sequence...
+ etc.). FreeMarker doesn't try to understand the meaning of the
+ attributes. It's up to the application that encapsulates
+ FreeMarker (as a Web application framework). Thus, the set of
+ allowed attributes and their semantic is application (Web
+ application framework) dependent.</p>
+ </li>
+
+ <li>
+ <p>Bugfix:
+ <code class="inline-code">freemarker.template.utility.DeepUnwrap</code>
+ unwrapped sequences to empty
+ <code class="inline-code">ArrayList</code>-s.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: If you included/imported a template with
+ <code class="inline-code">*/</code> in path (acquisition), and that template
+ in turn itself included/imported another template with
+ <code class="inline-code">*/</code> in path, it may failed.</p>
+ </li>
+
+ <li>
+ <p>New methods to the
+ <code class="inline-code">freemarker.core.Environment</code>:
+ <code class="inline-code">importLib(Template loadedTemplate, java.lang.String
+ namespace)</code>,
+ <code class="inline-code">getTemplateForImporting(...)</code>,
+ <code class="inline-code">getTemplateForInclusion(...)</code>.</p>
+ </li>
+
+ <li>
+ <p>Improvements in the
+ <code class="inline-code">java.io.IOException</code> related error messages
+ of the <code class="inline-code">include</code> and
+ <code class="inline-code">import</code> directives.</p>
+ </li>
+
+ <li>
+ <p>Minor improvements in the documentation.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_230">Differences between the Preview 16 and Preview 15
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>New package: <code class="inline-code">freemarker.debug</code>. This
+ provides a debugging API, by which you can debug executing
+ templates through network (RMI). You have to write the
+ front-end (client), as the API is just the server side. For
+ more information please read the JavaDoc of the
+ <code class="inline-code">freemarker.debug</code> package. (The debugging
+ API is present for a while, just I forgot to announce it in
+ the version history. Sorry for that.)</p>
+ </li>
+
+ <li>
+ <p>Bugfix: With the new XML wrapper,
+ <code class="inline-code">@@markup</code> and similar special keys:</p>
+
+ <ul>
+ <li>
+ <p>have returned
+ <code class="inline-code"><foo></foo></code> for empty
+ elements instead of <code class="inline-code"><foo�/></code>.
+ Other than it was needlessly verbose, it has confused
+ browsers if you generate HTML.</p>
+ </li>
+
+ <li>
+ <p>have showed the attributes that have no explicitly
+ given value in the original document, just a default value
+ coming form the DTD.</p>
+ </li>
+
+ <li>
+ <p>have forgot to put space before the system
+ identifier in the <code class="inline-code"><!DOCTYPE
+ <em class="code-color">...</em>></code>.</p>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+ <p>Bugfix: XPath with Jaxen has died with
+ <code class="inline-code">NullPointerException</code> if the context was an
+ empty node set.</p>
+ </li>
+
+ <li>
+ <p>A bit more intelligent Xalan XPath error
+ messages.</p>
+ </li>
+
+ <li>
+ <p>Revoked fallback-to-classloader logic from the template
+ cache.</p>
+ </li>
+
+ <li>
+ <p>From now on, if no XPath engine is available, and the
+ hash key in an XML query can't be interpreted without XPath,
+ an error will tell this clearly, rather than silently
+ returning undefined variable (null).</p>
+ </li>
+
+ <li>
+ <p>Bugfix: Some templates have caused the parser to
+ die.</p>
+ </li>
+
+ <li>
+ <p>Some other minor improvements here and there...</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_231">Differences between the Preview 15 and Preview 14
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>Bugfix: The new default template cache storage
+ (<code class="inline-code">MruCacheStorage</code>) has started to
+ continually fail with <code class="inline-code">NullPointerException</code>
+ from a random point of time, usually when the memory usage was
+ high in the JVM.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: In error messages, when the quoted FTL directive
+ had nested content, that was quoted as well, so the quotation
+ could be very long and expose nested lines needlessly.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_232">Differences between the Preview 14 and Preview 13
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p><code class="inline-code">freemarker.template.TemplateMethodModel.exec</code>
+ now returns <code class="inline-code">Object</code> instead of
+ <code class="inline-code">TemplateModel</code>.</p>
+ </li>
+
+ <li>
+ <p>Fixes and improvements for XPath with Jaxen (not Xalan).
+ Non-node-set XPath expressions are now working. FreeMarker
+ variables are accessible in XPath expressions with XPath
+ variable references (e.g.
+ <code class="inline-code">doc["book/chapter[title=$currentTitle]"]</code>).</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">freemarker.cache.SoftCachseStorage</code>
+ and <code class="inline-code">StrongCachseStorage</code> is deprected. The
+ more flexible <code class="inline-code">MruCachseStorage</code> is used
+ instead everywhere. The default cache storage is now an
+ <code class="inline-code">MruCachseStorage</code> object with 0 strong size,
+ and infinite soft size.
+ <code class="inline-code">Configuration.setSetting</code> for
+ <code class="inline-code">cache_storage</code> now understands string values
+ as <code class="inline-code">"strong:200, soft:2000"</code>.</p>
+ </li>
+
+ <li>
+ <p>Bugfix:
+ <code class="inline-code">freemarker.cache.MruCachseStorage</code> has died
+ with <code class="inline-code">ClassCastException</code> sometimes.</p>
+ </li>
+
+ <li>
+ <p>New built-ins for Java and JavaScript string escaping:
+ <a href="ref_builtins_string.html#ref_builtin_j_string">j_string</a> and <a href="ref_builtins_string.html#ref_builtin_js_string">js_string</a></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</code>
+ now prints more HTML-context-proof messages.</p>
+ </li>
+
+ <li>
+ <p>You can query the FreeMarker version number with static
+ method <code class="inline-code">Configuration.getVersionNumber()</code>.
+ Also, the <code class="inline-code">Manifest.mf</code> included in
+ <code class="inline-code">freemarker.jar</code> now contains the FreeMarker
+ version number, furthermore, executing it with <code class="inline-code">java
+ -jar freemarker.jar</code> will print the version number to
+ the stdout.</p>
+ </li>
+
+ <li>
+ <p>Added a new protected
+ <code class="inline-code">FreemarkerServlet</code> method:
+ <code class="inline-code">Configuration getConfiguration()</code>.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: FreeMarker has frozen on empty conditional
+ blocks in certain contexts.</p>
+ </li>
+
+ <li>
+ <p>Bugfix: Methods called twice on an object using the
+ <code class="inline-code">list</code> directive, as
+ <code class="inline-code">parent.getChildren()</code> with
+ <code class="inline-code"><#list parent.children as child>
+ ...</#list></code></p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_233">Differences between the Preview 13 and Preview 12
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>White-space stripping is now more aggressive as before:
+ it always removes leading and trailing white-space if the line
+ only contains FTL tags. (Earlier the white-space was not
+ removed if the tag was <code class="inline-code"><#include
+ <em class="code-color">...</em>></code> or user-defined
+ directive tag with empty directive syntax as
+ <code class="inline-code"><@myMacro/></code> (or its equivalents:
+ <code class="inline-code"><@myMacro></@myMacro></code> and
+ <code class="inline-code"><@myMacro></@></code>). Now
+ white-space is removed in these cases as well.) Also,
+ top-level white-space that separates macro definitions and/or
+ assignments is now ignored. More information: <a href="dgui_misc_whitespace.html#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p>
+ </li>
+
+ <li>
+ <p>White-space stripping can be disabled for a single line
+ with the <a href="ref_directive_nt.html#ref.directive.nt"><code>nt</code></a>
+ directive (for No Trim).</p>
+ </li>
+
+ <li>
+ <p>A new directive for the declarative XML processing:
+ <a href="ref_directive_visit.html#ref.directive.fallback"><code>fallback</code></a></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">freemarker.template.SimpleHash</code> now
+ can wrap read-only <code class="inline-code">Map</code>-s, such as the map
+ of HTTP request parameters in Servlet API.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_234">Differences between the Preview 12 and Preview 11
+ releases</h3>
+
+
+ <p>The only change between this and the previous preview
+ release is that Preview 11 had a bug where DOM trees would
+ <em>never</em> be garbage-collected.</p>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_235">Differences between the Preview 11 and Preview 10
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>Many XML related changes. Some of them are incompatible
+ with the previous preview releases! For a more detailed
+ explanation of how XML related features now work, see: <a href="xgui.html">XML Processing Guide</a></p>
+
+ <ul>
+ <li>
+ <p>Attention! Attribute queries such as
+ <code class="inline-code">foo.@bar</code> now return sequences
+ (similarly to child element queries and XPath queries),
+ not single nodes. Because of the rule with node sequences
+ of size 1, it is still good to write
+ <code class="inline-code">${foo.@bar}</code>, but built-ins such as
+ <code class="inline-code">?exists</code>, <code class="inline-code">?if_exists</code>
+ or <code class="inline-code">?default</code> don't work as before. For
+ example, instead of
+ <code class="inline-code">foo.@bar?default('black')</code>, you now have
+ to write <code class="inline-code">foo.@bar[0]?default('black')</code>.
+ So if you have used existence built-ins with attributes,
+ you have to find those occurrences in the templates and
+ add that <code class="inline-code">[0]</code>.</p>
+ </li>
+
+ <li>
+ <p>Attention! XML name-space handling has been totally
+ reworked and is absolutely incompatible with pre 10. Don't
+ worry about this if none of your XML input documents use
+ you use <code class="inline-code">xmlns</code> attributes. Worry,
+ though, if you have utilized the "loose
+ mode", where only the local name of elements were
+ compared, because that's now gone. Sorry...</p>
+ </li>
+
+ <li>
+ <p>Attention! Special-keys <code class="inline-code">@@</code> and
+ <code class="inline-code">@*</code> now return a sequence of attribute
+ nodes instead of the hash of them.</p>
+ </li>
+
+ <li>
+ <p>Several hash keys are now working for node sequences
+ that store multiple nodes. For example, to get the list of
+ all <code class="inline-code">para</code> elements of all
+ <code class="inline-code">chapter</code>-s, just write
+ <code class="inline-code">doc.book.chapter.para</code>. Or, to get list
+ of title attributes of all <code class="inline-code">chapter</code>-s
+ write <code class="inline-code">doc.book.chapter.@title</code>.</p>
+ </li>
+
+ <li>
+ <p>New special hash keys: <code class="inline-code">**</code>,
+ <code class="inline-code">@@start_tag</code>,
+ <code class="inline-code">@@end_tag</code>,
+ <code class="inline-code">@@attribute_markup</code>,
+ <code class="inline-code">@@text</code>,
+ <code class="inline-code">@@qname</code>.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">?parent</code> for attribute nodes now
+ returns the element node the attribute node belongs
+ to.</p>
+ </li>
+
+ <li>
+ <p>You can use Jaxen instead of Xalan for XPath
+ expressions, if you call the static
+ <code class="inline-code">freemarker.ext.dom.NodeModel.useJaxenXPathSupport()</code>
+ method once. We plan to use Jaxen automatically instead of
+ Xalan if it is available, just the Jaxen support is not
+ fully functional yet.</p>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+ <p>New special variable: <code class="inline-code">.vars</code>. This is
+ useful to read top-level variables with square bracket syntax,
+ for example <code class="inline-code">.vars["name-with-hyphens"]</code> and
+ <code class="inline-code">.vars[dynamicName]</code>.</p>
+ </li>
+
+ <li>
+ <p>New built-in, <code class="inline-code">eval</code>, to evaluate a
+ string as FTL expression. For example
+ <code class="inline-code">"1+2"?eval</code> returns the number 3.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">FreemarkerServlet</code> now uses the
+ configuration's <code class="inline-code">locale</code> setting, rather than
+ <code class="inline-code">Locale.getDefault()</code>, to set the locale of
+ the templates. Also, the signature of the
+ <code class="inline-code">deduceLocale</code> method has been
+ changed.</p>
+ </li>
+
+ <li>
+ <p>We have a new (beta status)
+ <code class="inline-code">CacheStorage</code> implementation:
+ <code class="inline-code">freemarker.cache.MruCacheStorage</code>. This
+ cache storage implements a two-level Most Recently Used cache.
+ In the first level, items are strongly referenced up to the
+ specified maximum. When the maximum is exceeded, the least
+ recently used item is moved into the second level cache, where
+ they are softly referenced, up to another specified maximum.
+ You can plug to try it with <code class="inline-code">cfg.setCacheStorage(new
+ freemarker.cache.MruCacheStorage(maxStrongSize,
+ maxSoftSize))</code>.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_236">Differences between the Preview 10 and Preview 9
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>The special key <code class="inline-code">@@xmlns</code> was removed
+ in favor of a new FTL directive for the same purpose,
+ <code class="inline-code"><#xmlns...></code>.</p>
+ </li>
+
+ <li>
+ <p>By default, the system is stricter about the use of
+ namespace prefixes. In general, you must use a prefix to
+ qualify subelements that are associated with an XML
+ nampespace. You can do this with the new
+ <code class="inline-code"><#xmlns...></code> directive, but prefixes
+ declared in the input XML doc will actually work with no
+ declaration.</p>
+ </li>
+
+ <li>
+ <p>Introduced a new special key called
+ <code class="inline-code">@@text</code> that returns all the text nodes
+ contained (recursively) in an element all concatenated
+ together.</p>
+ </li>
+
+ <li>
+ <p>Either Jaxen or Xalan can be used to provide XPath
+ functionality. Prior versions only worked with Xalan.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">FreemarkerServlet</code> uses
+ <code class="inline-code">ObjectWrapper.DEFAULT_WRAPPER</code> by default
+ instead of <code class="inline-code">ObjectWrapper.BEANS_WRAPPER</code>.
+ What this means is that, by default, objects of type
+ <code class="inline-code">java.lang.String</code>,
+ <code class="inline-code">java.lang.Number</code>,
+ <code class="inline-code">java.util.List</code>, and
+ <code class="inline-code">java.util.Map</code> will be wrapped as
+ <code class="inline-code">TemplateModels</code> via the classes
+ <code class="inline-code">SimpleScalar</code>,
+ <code class="inline-code">SimpleNumber</code>,
+ <code class="inline-code">SimpleSequence</code>, and
+ <code class="inline-code">SimpleHash</code> respectively. Thus, the java
+ methods on those objects will not be available. The default
+ wrapper implementation in FreeMarker 2.3 automatically knows
+ how to wrap Jython objects, and also wraps
+ <code class="inline-code">org.w3c.dom.Node</code> objects into instances of
+ <code class="inline-code">freemarker.ext.dom.NodeModel</code>.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">FreemarkerServlet</code> base
+ implementation no longer deduces the locale to use from the
+ HttpRequest.getLocale() hook. Rather, it simply delegates to a
+ <code class="inline-code">deduceLocale()</code> hook that is overridable in
+ subclasses. The base implementation simply uses
+ <code class="inline-code">Locale.getDefault()</code></p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_237">Differences between the Preview 9 and Preview 8
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>Fixed bugs introduced with Preview 8: XPath,
+ <code class="inline-code">@@markup</code> and
+ <code class="inline-code">@@nested_markup</code> now works with the document
+ node.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_238">Differences between the Preview 8 and Preview 7
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p><code class="inline-code">macro</code> and assignment directives now
+ accept arbitrary destination variable name with quoted syntax.
+ For example: <code class="inline-code"><#macro
+ "foo-bar"><em class="code-color">...</em></code> or
+ <code class="inline-code"><#assign "this+that" = 123></code>. This is
+ important, because XML element names can contain hyphen, and
+ it was not possible to define a handler macro for those
+ elements, till now.</p>
+ </li>
+
+ <li>
+ <p>Special key <code class="inline-code">@@content</code> was renamed to
+ <code class="inline-code">@@nested_markup</code>.</p>
+ </li>
+
+ <li>
+ <p>Fixed outdated XML related Manual parts (that were
+ outdated even in Preview 7).</p>
+ </li>
+
+ <li>
+ <p>Better parse-error messages.</p>
+ </li>
+
+ <li>
+ <p>Minor bugfixes here and there...</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_239">Differences between the Preview 7 and Preview 6
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>Caching of XPath queries should lead to significant
+ performance improvements for XML processing, at least when
+ XPath is heavily used.</p>
+ </li>
+
+ <li>
+ <p>Refinements in handling of XML namespaces in the XML
+ processing functionality. The new
+ <code class="inline-code">strict_namespace_handling</code> setting
+ introduced in 2.3pre6 was removed. A general-purpose solution
+ was arrived at that should make that configuration setting
+ unnecessary.</p>
+ </li>
+
+ <li>
+ <p>Special key <code class="inline-code">@xmlns</code> was renamed to
+ @@xmlns. Reserved namespace prefix <code class="inline-code">default</code>
+ was renamed to <code class="inline-code">@@default</code>.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">ftl</code> directive now accepts
+ non-string types.</p>
+ </li>
+
+ <li>
+ <p>New special keys were introduced for XML node wrappers
+ in the freemarker.ext.dom package. The
+ <code class="inline-code">@@markup</code> key returns the literal markup
+ that make up that element and the <code class="inline-code">@@content</code>
+ key returns all the element's markup excluding the opening and
+ closing tags.</p>
+ </li>
+
+ <li>
+ <p>Minor bugfixes here and there...</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_240">Differences between the Preview 6 and Preview 5
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>Existence built-ins (<code class="inline-code">?default</code>,
+ <code class="inline-code">?exists</code>, etc.) now work with sequence sub
+ variables as well. Read the <a href="ref_directive_switch.html#ref.directive.default">documentation of the
+ <code>default</code> built-in</a> for more
+ information.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">matches</code> built-in now returns a
+ sequence instead of a collection.</p>
+ </li>
+
+ <li>
+ <p>Refinements in handling of XML namespaces in the XML
+ processing functionality. A new setting,
+ <code class="inline-code">strict_namespace_handling</code> was introduced.
+ If this is set (it is off by default) any node-handling macro
+ used in with the visit/recurse machinery must be from a macro
+ library that declares in its ftl header that it handles the
+ namespace in question.</p>
+ </li>
+
+ <li>
+ <p>Minor bugfixes here and there...</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_241">Differences between the Preview 5 and Preview 4
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>The <code class="inline-code">replace</code> and
+ <code class="inline-code">split</code> built-ins now support
+ case-insensitive comparison and regular expressions (J2SE 1.4+
+ only), and some other new options. More information can be
+ found <a href="ref_builtins_string.html#ref_builtin_string_flags">here</a>.</p>
+ </li>
+
+ <li>
+ <p>New butilt-in for regular expression matching (J2SE 1.4+
+ only): <a href="ref_builtins_string.html#ref_builtin_matches"><code>matches</code></a></p>
+ </li>
+
+ <li>
+ <p>Minor bugfixes here and there...</p>
+ </li>
+
+ <li>
+ <p>Manual: More browser-safe HTML-s. More updated
+ content.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_242">Differences between the Preview 4 and Preview 3
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>Bugfix: with multi-type variables, <code class="inline-code">+</code>
+ operator overload for hash type had higher precedence than the
+ precedence of some older overloads.</p>
+ </li>
+
+ <li>
+ <p>The API documentation was missing from the distribution
+ <code class="inline-code">tar.gz</code>.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_243">Differences between the Preview 3 and Preview 2
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>XML processing: Many various bugfixes, especially with
+ the declarative processing.</p>
+ </li>
+
+ <li>
+ <p>XML processing: the <code class="inline-code">namespace_uri</code>
+ built-in, the <code class="inline-code">xmlnsuri</code> header parameter,
+ and the <code class="inline-code">TemplateNodeModel.getNodeNamespace</code>
+ method were renamed to <code class="inline-code">node_namespace</code> and
+ <code class="inline-code">getNodeNamespace</code> respectively.</p>
+ </li>
+
+ <li>
+ <p>XML processing: Better documentation. Especially, note:
+ <a href="xgui.html">XML Processing Guide</a></p>
+ </li>
+
+ <li>
+ <p>A new header parameter, <code class="inline-code">strip_text</code>,
+ that removes all top-level text from a template. See <a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code>
+ directive</a></p>
+ </li>
+
+ <li>
+ <p>Support for a variable number of macro parameters. If
+ the last parameter in a macro declaration ends with
+ <code class="inline-code">...</code>, all extra parameters passed to the
+ macro will be available via that parameter. For macros called
+ with positional parameters, the parameter will be a sequence.
+ For named parameters, the parameter will be a hash.</p>
+ </li>
+
+ <li>
+ <p>For <code class="inline-code">BeansWrapper</code> generated models,
+ you can now use the <code class="inline-code">${obj.method(args)}</code>
+ syntax to invoke methods whose return type is
+ <code class="inline-code">void</code>. <code class="inline-code">void</code> methods now
+ return <code class="inline-code">TemplateModel.NOTHING</code> as their
+ return value.</p>
+ </li>
+ </ul>
+
+
+
+
+
+
+
+<h3 class="content-header header-section3" id="autoid_244">Differences between the Preview 2 and Preview 1
+ releases</h3>
+
+
+ <ul>
+ <li>
+ <p>The <code class="inline-code">freemarker.ext.dom.NodeModel</code> API
+ changed slightly. The <code class="inline-code">setDocumentBuilder()</code>
+ method was changed to
+ <code class="inline-code">setDocumentBuilderFactory()</code> because the
+ older scheme was not thread-safe. The
+ <code class="inline-code">stripComments</code> and
+ <code class="inline-code">stripPIs</code> methods are renamed to The
+ <code class="inline-code">removeComments</code> and
+ <code class="inline-code">removePIs</code>, and are fixed now. A new method,
+ <code class="inline-code">simplify</code> has been added.</p>
+ </li>
+
+ <li>
+ <p>The expressions <code class="inline-code">as</code>,
+ <code class="inline-code">in</code>, and <code class="inline-code">using</code> are now
+ keywords in the template language and cannot be used as
+ top-level variable names without square-bracket syntax (as
+ <code class="inline-code">.vars["in"]</code>). If, by some chance, you have
+ top-level variables that use one of these names, you will have
+ to rename them (or use the square-bracket syntax). Sorry for
+ the inconvenience.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code">?new</code> built-in, as it was
+ implemented, was a security hole. Now, it only allows you to
+ instantiate a java object that implements the
+ <code class="inline-code">freemarker.template.TemplateModel</code>
+ interface. If you want the functionality of the
+ <code class="inline-code">?new</code> built-in as it existed in prior
+ versions, make available an instance of the new
+ <code class="inline-code">freemarker.template.utility.ObjectConstructor</code>
+ class to your template.</p>
+ </li>
+
+ <li>
+ <p>The <code class="inline-code"><#recurse></code> directive was
+ broken. It did not work with a <code class="inline-code">using</code>
+ clause. This is now fixed.</p>
+ </li>
+ </ul>
+
+ <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="versions_2_3_1.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_2_8.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>\u20132017
+<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>