2.3.25 (incubating at Apache)

Page Contents

Release date: 2016-06-26

This is a stable, final release. The "incubating" suffix is required by the Apache Software Foundation until the project becomes a fully accepted (graduated) Apache project.

Changes on the FTL side

  • Extended the list directive to support listing hashes (such as Map-s), like <#list map as k, v>${k}: ${v}</#list>, where k and v are the key and value in the key-value pairs of the hash.

Changes on the Java side

  • Added the TemplateModelHashEx2 interface that extends TemplateModelHashEx with a method for listing the content of the key-value pairs of the hash. (This is utilized by the new hash listing capability of the list directive, but it's not required by it if all keys are strings.)

  • Lazy imports: With the new boolean settings, lazy_imports and lazy_auto_imports, you can make imports (as in <#import "lib/utils.ftl" as u>) and/or auto-imports to be lazy. When the import is lazy, the namespace variable (u in this example) will be created immediately, just like before, but the imported template will be loaded and processed only when (and if ever) the content of the imported namespace is accessed. The main application of this is with auto-imports, where you don't want the overhead of importing templates that aren't actually used in a template. (Also, a new Environment.importLib method overload was added, where you can specify if you want a lazy or an eager import.) These new settings can be set on Configuration, Template (TemplateConfiguration) and Environment level.

  • It's now possible to set the auto_import and auto_include settings on a per template basis (like templates with a certain name pattern has different auto-imports). This is now possible as these settings were moved from the Configuration level down to the more generic Configurable level, and so are inherited by TemplateConfiguration and Environment too.

  • New Configuration (and TemplateConfiguration) setting, tab_size. This only influences how the column number reported in error messages is calculated (and the column number available with other API-s). It doesn't influence the output of the templates. Defaults to 8.

  • Added new setting to DefaultObjectWrapper (and to DefaultObjectWrapperBuilder): iterableSupport. This fixes the issue when you couldn't use #list (or ?has_next, etc.) on a value that only implements Java 5 java.lang.Iterable (not to be confused with Iterator), but not Collection. This is not enabled by default as it's not compatible with some existing templates, most often because they have used someIterable.iterator() in the template as a workaround. When this is enabled, the Iterable object won't be seen as a generic Java object by FreeMarker anymore, and thus just like with Collection-s, its API won't be exposed to the templates (except through ?api, of course).

  • Added Configurable.getCustomNumberFormatsWithoutFallback and Configurable.getCustomDateFormatsWithoutFallback methods to make it easier for custom code to investigate the custom formal setting Map hierarchy.

  • Bug fixed (FREEMARKER-18): If you had a JSP custom tag and an EL function defined in the same TLD with the same name, the EL function has overwritten the custom tag. This is a bug introduced in 2.3.23, when EL function support was added. JSP allows a custom tag and an EL function in the same TLD to have the same name. In such case now we combine the two into a single value that is both callable as an user defined directive (<@my.foo...>) and as a function (my.f(...)).

  • Bug fixed (FREEMARKER-19): The column numbers calculated by the parser has assumed tab size 1 since 2.3.25 (an unwanted side effect of updating JavaCC), while before it has assumed tab size 8. The default was restored to 8. This bug has affected the column numbers in error messages. It also broke the output of some rarely used AIP-s, namely Template.getSource(beginCol, beginLine, endCol, endLine), TemplateObject.getSource() and through that TemplateObject.toString(), if the first or last line has contain tab characters.

  • Bug fixed: There was a regression with 2.3.24, where Configuration.setAutoImports() haven't removed auto-imports added earlier. (Though it's unlikely that an application uses that method and also adds auto-imports earlier.)

  • Bug fixed: TemplateConfiguration.apply(Template) didn't merge the customDateFormats and customNumberFormats Map-s when they were set both in the Template and in the applied TemplateConfiguration, instead it just kept the value in the Template (just like with atomic setting values). Note that it was unlikely to run into this bug, as usually you (or FreeMarker) create a single merged TemplateConfiguration with TemplateConfiguration.merge(TemplateConfiguration) and then apply it on a fresh template.

  • Removed FindBugs @SuppressFBWarnings annotations from the binary (freemarker.jar), as they have caused warnings like this when compiling dependant project with Gradle: "warning: Cannot find annotation method 'value()' in type 'SuppressFBWarnings'"

  • The Maven source artifact now contains the JavaCC generated java files and FTL.jj.