FreeMarker Changelog

What's new in FreeMarker 2.3.20

• Changes on the FTL side:
• Error message quality improvements:
• Many error messages are now more helpful, especially for users who are not experienced with FreeMarker. For example, some of the most common user mistakes are recognized and tips are shown to fix them, reducing support costs or the time employees spend to figure them out.
• It's now ensured that the error location in the template is included in the message returned by TemplateException.getMessage(). The stack trace always showed this information anyway, but some users only see the "message", not the stack trace, and that often didn't contained the location.
• The template language part of the stack trace is now more detailed, and easier to understand. This is especially helpful in applications that use a complex library of macros and functions.
• Several smaller bugs were fixed that made the error information wrong or lacking.
• The layout of the error messages is now more consistent, and generally easier to read.
• Changes regarding boolean to string conversions and formatting:
• ?c (computer-language formatting) now works with booleans too, always giving "true" or "false" regardless of the boolean_format. This way it's safe for generating JavaScript in a context where human-readable text is also rendered.
• If the boolean_format setting is set to anything but the default "true,false" value, boolean values will be automatically converted to string where a string value is expected by the template language, instead of giving an error. This helps you spare those?string-s after boolean values. This is the same logic as with numbers and dates, which were always automatically converted to string, according the corresponding format setting. Except, the provided default boolean format is useless for automatic conversion (but it's still there for ?string, for backward compatibility), hence it must be set manually. (We certainly couldn't come up with a sensible default anyway, as for booleans it depends too much on the application, not to mention the localisation issues.)
• Exactly like with numbers and dates, automatic conversion doesn't happen in these cases:
• Comparisons, i.e., someBoolean == 'true' is still an error
• Method calls where the declared type of the parameter is String but the actual value is a boolean; still an error
• When the boolean value is used as key in expr[key], it's still an error (there was no automatic conversion there for other types either, as numerical and string keys have different meaning)
• The opposite direction, i.e., string to boolean conversion; won't happen
• New built-ins for numbers: abs, is_nan, is_infinite. Like n?abs will give the absolute value of n.
• New built-in for sequences: join. Like [1, 2, 3]?join(", ") will give the string "1, 2, 3".
• If you set the incompatible_improvements setting (see here) to 2.3.20 or higher, ?html will escape apostrophe-quotes just like ?xhtml does. Utilizing this is highly recommended, because otherwise if interpolations are used inside attribute values that use apostrophe-quotation () instead of plain quotation mark (), they might produce HTML/XML that's not well-formed. Note that ?html didn't do this because long ago there was no cross-browser way of doing this, but it's not a real concern anymore. Also note that this will be the default behavior starting from 2.4.
• Bug fix [390] (and other improvements): ?js_string and ?json_string didn't escape the u2028-u2029 line terminators (problem for JavaScript) and the u007F-u009F control characters (maybe a problem in JSON, depending on implementation). Furthermore, the escaping of \, become safer in that now they are escaped whenever it can't be guaranteed that they won't be part of or