Release date: 2023-01-12
Changes on the FTL side
Added new configuration setting,
c_format(also settable via the
settingdirective). This specifies what syntax to use when formatting values for computer consumption/parser, like
"JSON". Most prominently, this affects the
cbuilt-in, hence the name. See valid setting values, and their meaning here: Template Author's Guide/Miscellaneous/Formatting for humans, or for computers.
If you set the
incompatible_improvementssetting to 2.3.32, the default of
incompatible_improvements, the default value is
"legacy"that emulates the old behavior of
?c(where you can lose numerical precision, etc.), so it's recommended to set it to something else.
?cnow formats string values to string literals (with quotation marks and escaping), according the language specified in the
c_formatsetting, such as
Java, etc. Earlier,
?conly allowed numbers, and booleans.
To generate JSON, you can now write a piece of template like this:Template
Then the output will be like:Output
"fullName": "John Doe",
Note that the quotation marks were added by
?c, and weren't typed into the template.
Added ?cn, which is like
?c, except if the value is
null/missing, it will output a
nullliteral, according the language specified in the new
Let's say, in the previous example
user.fullNameis expected to be
nullsometimes. Then you can just use
If said variable is
null, the output will be like this (otherwise it will be a quoted string like earlier):Output
Note that with this approach you don't complicate the template anymore to avoid printing quotation marks. Of course,
?cnworks on numerical and boolean values as well (and of course those won't be quoted, only strings).
c_format-s other than
"legacy"use slightly different number formatting than
?cdid in earlier versions. The change affects some non-whole numbers, and whole numbers with over 100 digits. The goal of this change is to make the formatting lossless, and also to avoiding huge output with exponents of high magnitude. See details at the documentation of the
incompatible_improvementssetting to 2.3.32 will change the default of
Of course, all this only affects number formatting done with
?cn, and with
number_format, and not number formatting in general.
For consistency, when setting the
number_formatsetting (also when formatting with
"c"can be used instead of "computer". Both has the same effect on formatting, but
"c"is preferred from now on.
?c_upper_case, which are the non-localized (computer language) variants of
?upper_case. The primary problem people run into with the localized versions is that with Turkish locale the letter
Ihas different conversions than in most languages, which causes problem if the conversion was for computer consumption (for technical purposes), and not for humans.
freemarker.ext.xml, which is the old, long deprecated XML wrapper, that almost nobody uses anymore (the commonly used one is
_registerNamespacekey now works, doing what the documentation always stated. Before this fix it just behaved as if it was the name of an element you are looking for.
Changes on the Java side
Configurable.setCFormat(CFormat), with the usual accompanying setting API methods/constants. See the
c_format-, and the
?c-related changes earlier in the FTL section.
Environment.getCTemplateNumberFormat()that returns a
freemarker.core.TemplateNumberFormat, and deprecated
getCNumberFormat()that returns a
java.text.NumberFormat. The behavior defined in the
CFormat(see earlier) is only reflected exactly by the return value of the new method. The deprecated method returns a format that's a best effort approximation.
freemarker.core.MarkupOutputFormat.outputForeign(MO2 mo, Writer out)method, which for a
true, allows full control over how to print a different markup into it. This can check what other markup is allowed, and do conversion if necessary. (GitHub PR 83)
Fixed performance bug with XML processing (
freemarker.ext.dom) when converting an XML element that contains lots of text nodes (instead of a single big text node) to a string. (GitHub PR 82)
javaSctringEncto support quoting. Also
FREEMARKER-198: Fixed possible deadlock when the
DefaultObjectWrapperclass static initialization is triggered in different threads around the same time. (In the very unlikely case your application can run into this, this will hang the code that initializes FreeMarker before it has processed any templates, and it can't happen anymore if any template processing managed to start.)
FREEMARKER-190: Updated dom4j version used during FreeMarker project compilation from 1.3 to 2.1.3. Users can still use FreeMarker with dom4j 1.3 (mostly just luck, but it works). FreeMarker's dom4j support is long deprecated anyway, and almost nobody uses it anyway. We were forced to do this change because old dom4j versions have security vulnerabilities, and although FreeMarker is not affected by them (like we do not pull in dom4j as dependency into the projects of our users), we were flagged as vulnerable at certain places for merely supporting 1.3.
DefaultMemberAccessPolicy-rules(used by default), and
unsafeMethods.properties(long deprecated, not used by default). Note that no matter how much we tweak these, they will never provide proper security if you have untrusted templates! See this in the FAQ!