<#include filename>
or
<#include filename options>

Where:

You can use it to insert the contents of another file (specified by the filename parameter) into your template. The output from the included file is inserted at the point where the include tag occurs. The include directive is not replaced by the content of the included file, nor does it really insert anything into the template itself. It just processes the included file. The inclusion happens each times when FreeMarker reaches the include directive in the course of template processing. So, for example if the include is inside a list, you can specify different filenames in each cycle.

The filename is the path of the file to include, relative to the including template. However, if you start the path with /, then the path is an absolute path. Absolute path means here that it is relative to a base (often referred as the ``root directory of the templates'') that the programmer defines when he configures FreeMarker.

Also, always use slashes to separate path components. If you are loading templates from your local file system and it uses backslashes (i.e. Windows), FreeMarker will convert them automatically.

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.

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. Specifying more than one asterisk will result in a template not being found.

Whenever a template is loaded, it is assigned a locale. A locale is a language and an optional country or dialect identifier. A template is typically loaded by some code that the programmer wrote and he chooses a locale for the template based on some aspect. For example, when the FreemarkerServlet loads templates, it always requests the template with locale matching the language preference of the browser that requested the web page.

Whenever a template is loaded, it is assigned a locale. A locale is a language and an optional country or dialect identifier. A template is typically loaded by some code that the programmer wrote and he chooses a locale for the template based on some aspect. For example, when the FreeMarkerServlet loads templates, it always requests the template with locale matching the language preference of the browser that requested the web page.

When a template includes another template, it attempts to load a template with the same locale. 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:

Note that you can disable localized lookup feature with the setLocalizedLookup method of Configuration.

When you use both acquisition 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: