ftl

Synopsis

<#ftl param1=value1 param2=value2 ... paramN=valueN>

Where:

  • param1, param2, …etc.: Name of the parameter. Not an expression. Allowed parameters are: encoding, strip_whitespace, strip_text, …etc. See below.
  • value1, value2, …etc.: The value of parameter. This must be a constant expression (as true, or "ISO-8859-5", or {x:1, y:2}). It can’t use variables.

Description

Tells information about the template for FreeMarker and for other tools, also helps programs to automatically detect if a text file is an FTL file. This directive, if present, must be the very first thing in the template. Any white-space before this directive will be ignored.

The settings (encoding, white-space stripping, etc.) given here has the highest precedence, that is, they will be used for the template regardless of any FreeMarker configuration settings.

Possible parameters:

  • attributes: This is a hash that associates arbitrary attributes (name-value pairs) to the template. Scaffander currently supports only one attribute to define bracket interpolation syntax ([#ftl attributes={"interpolation_syntax":"squareBracket"}] or <#ftl attributes={"interpolation_syntax":"squareBracket"}>, see alternative syntax for details)

  • auto_esc: A boolean constant to turn auto-escaping on or off. Auto-escaping will be by default on, if the current output format uses auto-escaping by default. So you mostly use this to disable auto-escaping (false value). An attempt to use true value when the current output format is a non-markup output format (which hence can’t escape) will cause parse-time error. Note that you can turn auto-escaping on/off for only a part of the template with the autoesc and noautoesc directives.

  • encoding: With this you can specify the encoding (charset) of the template in the template file itself. Note however, that FreeMarker will try to find and interpret the ftl directive first with the automatically guessed encoding, and only then realizes if the ftl directive dictates something different, and re-read the template with the new encoding. Thus, the template must be valid FTL until the end of ftl tag with the encoding tried first. The valid values of this parameter are MIME-preferred charset names from the IANA Charset Registry, like ISO-8859-5, UTF-8 or Shift_JIS.

  • output_format: Specifies the output format of this template. This must be a string literal, which refers to the name of the output format. See the table of predefined output formats here. The referred output format must be known by the Configuration, or else a parse-time error will occur. The name can also refer to a so called combined output format as "outerFormatName{innerFormatName}"; see more about combined output formats here.

  • strip_text: When enabled, all top-level text in a template is removed when the template is parsed. This does not affect text within macros, directives, or interpolations. Valid values are the boolean constants true and false. (And for backward compatibility, strings “yes”, “no”, “true”, “false”). The default value (i.e. when you don’t use this parameter) is false.

  • strip_whitespace: This enables/disables white-space stripping. Valid values are the boolean constants true and false. The default value is true.

You can also use camel case instead of snake case for parameter names, like outputFormat instead of output_format. But know that then within the same template, FreeMarker will enforce the usage of camel case for all identifiers that are part of the template language (user defined names are not affected).

This directive also determines if the template uses angle bracket syntax (e.g. <#include 'foo.ftl'>) or square bracket syntax (e.g. [#include 'foo.ftl']). Simply, the syntax used for this directive will be the syntax used for the whole template.

Page contents