2.3.25 (incubating at Apache) - Apache FreeMarker Manual

Unsupported web browser - Use a modern browser to view this website!

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# 2.3.25 (incubating at Apache)

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`.

Previous Next