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
listdirective to support listing hashes (such asMap-s), like<#list map as k, v>${k}: ${v}</#list>, wherekandvare the key and value in the key-value pairs of the hash.
Changes on the Java side
-
Added the
TemplateModelHashEx2interface that extendsTemplateModelHashExwith a method for listing the content of the key-value pairs of the hash. (This is utilized by the new hash listing capability of thelistdirective, but it's not required by it if all keys are strings.) -
Lazy imports: With the new boolean settings,
lazy_importsandlazy_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 (uin 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 newEnvironment.importLibmethod overload was added, where you can specify if you want a lazy or an eager import.) These new settings can be set onConfiguration,Template(TemplateConfiguration) andEnvironmentlevel. -
It's now possible to set the
auto_importandauto_includesettings 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 theConfigurationlevel down to the more genericConfigurablelevel, and so are inherited byTemplateConfigurationandEnvironmenttoo. -
New
Configuration(andTemplateConfiguration) 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 toDefaultObjectWrapperBuilder):iterableSupport. This fixes the issue when you couldn't use#list(or?has_next, etc.) on a value that only implements Java 5java.lang.Iterable(not to be confused withIterator), but notCollection. This is not enabled by default as it's not compatible with some existing templates, most often because they have usedsomeIterable.iterator()in the template as a workaround. When this is enabled, theIterableobject won't be seen as a generic Java object by FreeMarker anymore, and thus just like withCollection-s, its API won't be exposed to the templates (except through?api, of course). -
Added
Configurable.getCustomNumberFormatsWithoutFallbackandConfigurable.getCustomDateFormatsWithoutFallbackmethods to make it easier for custom code to investigate the custom formal settingMaphierarchy. -
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 thatTemplateObject.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 thecustomDateFormatsandcustomNumberFormatsMap-s when they were set both in theTemplateand in the appliedTemplateConfiguration, instead it just kept the value in theTemplate(just like with atomic setting values). Note that it was unlikely to run into this bug, as usually you (or FreeMarker) create a single mergedTemplateConfigurationwithTemplateConfiguration.merge(TemplateConfiguration)and then apply it on a fresh template. -
Removed FindBugs
@SuppressFBWarningsannotations 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.
