ftl - 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

# 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 old-syntax (`#`-less) format of this directive is not supported.

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. The values of the attributes can be of any type (string, number, sequence... etc.). FreeMarker doesn't try to understand the meaning of the attributes. It's up to the application that encapsulates FreeMarker (as a Web application framework). Thus, the set of allowed attributes and their semantic is application (Web application framework) dependent. Programmers: you can get the attributes associated with a `Template` object with its `getCustomAttributeNames` and `getCustomAttribute` methods (inherited from `freemarker.core.Configurable`). As the template attributes are associated with the `Template` object when the template is parsed, the attributes can be read anytime, the template need not be executed. The methods mentioned return the attribute values unwrapped, that is, with FreeMarker independent type as `java.util.List`.

- `auto_esc`: A boolean constant to turn auto-escaping on or off. It depends on the `auto_escaping_policy` of the FreeMarker configuration, but usually 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. (That is, this will be the `encoding` setting of the newly created `Template`, and not even the `encoding` parameter to `Configuration.getTemplate` can override it). Note however, that FreeMarker will try to find and interpret the `ftl` directive first with the automatically guessed encoding (which depends on the FreeMarker configuration set by the programmers), 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.

- `ns_prefixes`: This is a hash that associates prefixes with node namespaces. For example: `{"e":"http://example.com/ebook", "vg":"http://example.com/vektorGraphics"}`. This is mostly used with XML processing where the prefixes can be used in XML queries, but it also influences the working of directives `visit` and `recurse`. Only one prefix can be registered for the same node namespace (otherwise an error will occur), so there is one-to-one relation between prefixes and node namespaces. Prefixes `D` and `N` are reserved. If you register prefix `D`, then other than you associate the node namespace with prefix `D`, you also set the default node namespace. Prefix `N` can't be registered; it is used to denote nodes with no node namespace in certain places, when (and only when) prefix `D` is registered. (To see the usage of default node namespace, `N`, and prefixes in general, see the part about XML processing and `visit` and `recurse` in the reference.) The effect of `ns_prefixes` is limited to a single FTL namespace, namely, to the FTL namespace that was created for the template. This also means that `ns_prefixes` has effect only when an FTL namespace is created for the template that contains it, otherwise the `ns_prefixes` parameter has no effect. An FTL namespace is made for a template when: (a) the template is the "main" template, that is, it is not invoked as a result of an `<#include ...>`, but it is directly invoked (with the `process` Java method of class `Template` or `Environment`); (b) the template is invoked directly with `<#import ...>`.

- `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. Other names can exist if the programmers has added them via the `registered_custom_output_formats` configuration setting (`Configuration.setRegisteredCustomOutputFormats(...)`). 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.

- `strict_syntax`: This turns on/off "strict syntax", which is the standard syntax after FreeMarker 2.1. 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) depends on the FreeMarker configuration set by the programmers, but it's most certainly set to `true`. For more information read: Deprecated FTL constructs/Old FTL syntax

- `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`. (And for backward compatibility, strings `"yes"`, `"no"`, `"true"`, `"false"`). The default value (i.e. when you don't use this parameter) depends on the FreeMarker configuration set by the programmers, but it should be `true` for new projects.

Note:

As of FreeMarker 2.3.23, you can 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, regardless of the FreeMarker configuration settings.

Previous Next