include

Synopsis

<#include path>
or
<#include path options>

Where:

Description

You can use it to insert another FreeMarker template file (specified by the path parameter) into your template. The output from the included template is inserted at the point where the include tag occurs. The included file shares the variables with the including template, similarly like if it was copy-pasted into it. The include directive is not really replaced by the content of the included file, instead it processes the included file each time when FreeMarker reaches the include directive in the course of template processing. So for example if the include is inside a list loop, you can specify different file names in each cycle.

The path parameter can be a relative path like "foo.ftl" and "../foo.ftl", or an absolute like "/foo.ftl". Relative paths are relative to the directory of the template that contains the import directive. Absolute paths are relative to a base (often referred as the 'root directory of the templates') that the programmer defines when he configures FreeMarker.

Always use / (slash) to separate path components, never \ (backslash). Even if you are loading templates from your local file system and it uses backslashes (like under. Windows), use /.

Example:

Assume /common/copyright.ftl contains:

Then this:

will output this:

The supported options are:

Example:

Note, that it is possible to automatically do the commonly used inclusions for all templates, with the "auto includes" setting of Configuration.

Using acquisition

There's a special path component represented by an asterisk (*). It is interpreted as "this directory or any of its parents". Therefore, if the template located in /foo/bar/template.ftl has the following line:

then the engine will look for the template in following locations, in this order:

This mechanism is called acquisition and allows the designers to place commonly included files in a parent directory, and redefine them on a per-subdirectory basis as needed. We say that the including template acquires the template to include from the first parent directory that has it. Note that you can specify not only a template name to the right of the asterisk, but a subpath as well. I.e. if the previous template instead read:

then the engine would look for the template in following locations, in this order:

Finally, the asterisk needn't be the first element of the path:

would cause the engine to look for the template in following locations, in this order:

However, there can be at most one asterisk in the path. If you specifying more asterisks, the template won't be found.

Localized lookup

A locale is a language and an optional country or dialect identifier (plus also maybe a further variant identifier, like "MAC"). Whenever a template is requested, a desired locale is always specified (explicitly or implicitly), and FreeMarke will try to find a variant of the template that matches that locale. When a template includes or imports another template, internally that will also be requested for a locale, for the locale that the locale setting is set to, and that's usually for the locale of the top-level template.

Suppose your template was loaded with locale en_US, which means U.S. English. When you include another template:

the engine will in fact look for several templates, in this order:

and it will use the first one that exists.

Note that if how (and if) FreeMarker searches the localized variations is configurable by the programmers, so we are just describing the default behavior here. You can disable localized lookup with the localized_lookup setting (Configuration.setLocalizedLookup(boolean)). Also, you can define your own sequence of deduced template names with the template_lookup_strategy setting (Configuration.setTemplateLookupStrategy(TemplateLookupStrategy)).

When you use both acquisition (i.e., * step in the path) and localized template lookup, the template with more specific locale in a parent directory takes precedence over template with less specific locale in a child directory. Suppose you use the following include from /foo/bar/template.ftl:

the engine will look for these templates, in this order: