setting

Synopsis

<#setting name=value>

Where:

• name: name of the setting. It is not expression!
• value: New value of the setting. Expression

Description

Sets a setting for the further part of processing. Settings are values that influence the behavior of FreeMarker. The new value will be present only in the template processing where it was set, and does not touch the template itself. The initial value of settings is set by the programmer (see: Programmer's Guide/The Configuration/Settings).

The supported settings are:

• locale: The locale (language) of the output. It can influence the presentation format of numbers, dates, etc. The value is a string which consist of a language code (lowercase two-letter ISO-639 code) plus optional county code (uppercase two-letter ISO-3166 code) separated from the language code with underscore, and if we have specified the country then an optional variant code (not standardized) separated from the country with underscore. Examples of valid values: en, en_US, en_US_MAC. FreeMarker will try to use the most specific available locale, so if you specify en_US_MAC but that is not known, then it will try en_US, and then en, and then the default locale of the computer (which is may set by the programmer).

• number_format: The number format that is used to convert numbers to strings when no explicit format is specified. Can be one of the following:

  • Predefined values defined by the Java platform: number (the default), currency, or percent

  • c since 2.3.24 (was called computer before that, which still works), which formats like the c built-in

  • Format pattern written in Java decimal number format syntax, for example 0.###. FreeMarker extends this format to allow specifying rounding mode, symbols used, etc.

  • Values starting with @ that's also followed by a letter, refer to a custom format. For example, "@price" refers to the custom format registered with the "price" name. The custom format name is possibly followed by space or _ and then format parameters, whose interpretation depends on the custom format. For backward compatibility, the initial @ only has this new meaning if either the incompatible_improvements setting is at least 2.3.24, or there's any custom formats defined. When the initial @ isn't followed by a letter (any UNICODE letter), it's never treated as a reference to a custom format.

• boolean_format: The comma-separated pair of strings for representing true and false values respectively that is used to convert booleans to strings when no explicit format is specified (like in ${booleanValue}). Note that currently white space isn't removed from this string, so don't put space after the comma. Default value is "true,false", but FreeMarker will deny using that particular value for ${booleanValue}, and requires using ${booleanValue?c} instead (this works since 2.3.21). For any other value, like "Y,N", ${booleanValue} will work. See also:string built-in.

• date_format, time_format, datetime_format: The format used to convert date/time/date-time values (Java java.util.Date-s and its subclasses) to strings when no explicit format is specified via the string built-in (or otherwise), as in the case of ${someDate}. The date_format setting only effects the formatting of date values that store no time part, time_format only effects the formatting of times that store no date part, and datetime_format only effects formatting of date-time values. These settings also effects what format do ?time, ?date, and ?datetime expect when it's applied on a string value.

  The possible setting values are (the quotation marks aren't part of the value itself):

  • Patterns accepted by Java's SimpleDateFormat, for example "dd.MM.yyyy HH:mm:ss" (where "HH" means 0-23 hours) or "MM/dd/yyyy hh:mm:ss a" (where "a" prints AM or PM, if the current language is English).

    Warning!

    Be careful not to use YYYY (upper case, means "week year") instead of yyyy (lower case, means year)! It's an easy mistake to do, and hard to notice during testing, as "week year" only differs from "year" near the edge of years.

  • "xs" for XML Schema format, or "iso" for ISO 8601:2004 format. These formats allow various additional options, separated with space, like in "iso m nz" (or with _, like in "iso_m_nz"; this is useful in a case like lastModified?string.iso_m_nz). The options and their meanings are:

    • Accuracy options:

      • ms: Milliseconds, always shown with all 3 digits, even if it's all 0-s. Example: 13:45:05.800
      • s: Seconds (fraction seconds are dropped even if non-0), like 13:45:05
      • m: Minutes, like 13:45. This isn't allowed for "xs".
      • h: Hours, like 13. This isn't allowed for "xs".
      • Neither: Up to millisecond accuracy, but trailing millisecond 0-s are removed, also the whole milliseconds part if it would be 0 otherwise. Example: 13:45:05.8

    • Time zone offset visibility options:

      • fz: "Force Zone", always show time zone offset (even for for java.sql.Date and java.sql.Time values). But, because ISO 8601 doesn't allow for dates (means date without time of the day) to show the zone offset, this option will have no effect in the case of "iso" with dates.
      • nz: "No Zone", never show time zone offset
      • Neither: Always show time zone offset, except for java.sql.Date and java.sql.Time, and for "iso" date values.

    • Time zone options:

      • u: Use UTC instead of what the time_zone setting suggests. However, java.sql.Date and java.sql.Time aren't affected by this (see sql_date_and_time_time_zone to understand why)
      • fu: "Force UTC", that is, use UTC instead of what the time_zone or the sql_date_and_time_time_zone setting suggests. This also effects java.sql.Date and java.sql.Time values
      • Neither: Use the time zone suggested by the time_zone or the sql_date_and_time_time_zone configuration setting

    Options from the same category are mutually exclusive, like using m and s together is an error.

    The options can be specified in any order.

    The accuracy and time zone offset visibility options don't influence parsing, only formatting. For example, even if you use "iso m nz", "2012-01-01T15:30:05.125+01" will be parsed successfully and with milliseconds accuracy. The time zone options (like "u") influence what time zone is chosen only when parsing a string that doesn't contain time zone offset.

    Parsing with "iso" understands both "extend format" and "basic format", like 20141225T235018. It doesn't, however, support the parsing of all kind of ISO 8601 strings: if there's a date part, it must use year, month and day of the month values (not week of the year), and the day can't be omitted.

    The output of "iso" is deliberately so that it's also a good representation of the value with XML Schema format, except for 0 and negative years, where it's impossible. Also note that the time zone offset is omitted for date values in the "iso" format, while it's preserved for the "xs" format.

  • "short", "medium", "long", or "full", which has locale-dependent meaning defined by the Java platform (see in the documentation of java.text.DateFormat). For date-time values, you can specify the length of the date and time part independently, be separating them with _, like "short_medium". ("medium" means "medium_medium" for date-time values.)

  • Values starting with @ that's also followed by a letter, refer to a custom format, like "@worklog" refers to the custom format registered with the "worklog" name. The format name is possibly followed by space or _ and then format parameters, whose interpretation depends on the custom format. For backward compatibility, the initial @ only has this new meaning if either the incompatible_improvements setting is at least 2.3.24, or there's any custom formats defined. When the initial @ isn't followed by a letter (any UNICODE letter), it's never treated as a reference to a custom format.

• time_zone: The name of the time zone used to format times for display. As with all settings, the default is chosen by the programmers when they set up FreeMarker (via the Configuration class), but it's most often the default time zone of the JVM. Can be any value that is accepted by Java TimeZone API, or "JVM default" (since FreeMarker 2.3.21) to use the JVM default time zone. Examples: "GMT", "GMT+2", "GMT-1:30", "CET", "PST", "America/Los_Angeles".

  Warning!

  If you change this setting from its default value, you should certainly also set sql_date_and_time_time_zone to "JVM default". See more in the Java API documentation of Configurable.setSQLDateAndTimeTimeZone(TimeZone).

• sql_date_and_time_time_zone (since FreeMarker 2.3.21): This handles a highly technical issue, so it should usually be set from the Java code by the programmers. For programmers: If this is set to non-null, for date-only and time-only values coming from SQL database (more precisely, for java.sql.Date and java.sql.Time objects) FreeMarker will use this time zone instead of the time zone specified by the time_zone FreeMarker setting. See more in the Java API documentation of Configurable.setSQLDateAndTimeTimeZone(TimeZone).

• c_format (since FreeMarker 2.3.32): Sets what format to use when formatting for computer consumption, like "JavaScript or JSON". Mostly prominently this affects the c built-in, hence the name. See valid values and their meaning here: Template Author's Guide/Miscellaneous/Formatting for humans, or for computers.

• url_escaping_charset: The charset used for URL escaping (e.g. for ${foo?url}) to calculate the escaped (%XX) parts. Usually the framework that encloses FreeMarker should set it, so you hardly ever should set this setting in templates. (Programmers can read more about this here...)

• output_encoding: Tells FreeMarker what the charset of the output is. As FreeMarker outputs a stream of UNICODE characters (it writes into a java.io.Writer), it's not affected by the output encoding, but some macros/functions and built-ins may want to use this information.

• classic_compatible: Used for better compatibility with very old FreeMarker versions (mostly 1.7.x). See the documentation of freemarker.template.Configurable.isClassicCompatible() for more information.

Example: Assume that the initial locale of template is de_DE (German). Then this:

${1.2}
<#setting locale="en_US">
${1.2}

will output this:

1,2
1.2

because German people use the comma as their decimal separator, while US people use the dot.