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

# import

## Synopsis

    <#import path as hash>

Where:

- `path`: The path of a template. This is an expression that evaluates to a string. (With other words, it doesn't have to be a fixed string, it can also be something like, for example, `profile.baseDir + "/menu.ftl"`.)
- `hash`: The unquoted name of hash variable by which you can access the namespace. Not an expression. (If you have to import into a dynamically constructed name, you have to use this trick.)

## Description

Used for making a collection of macros, functions, and other variables available for the importing template, which were defined in the imported template. For example, let's say you have written macros to generate some commonly needed pieces output, and you have put them into `/libs/commons.ftl`. Then, in the template where you want to use them, do this (near the top of the the template by convention, next to any other `import`-s):

Template

    <#import "/libs/commons.ftl" as com>

Later in same template, let's say you want to use the `copyright` macro defined in `/libs/commons.ftl`. Then you can call that macro like this:

Template

    <@com.copyright date="1999-2002"/>

Note the `com.` before the macro name above. All that was defined in `/libs/commons.ftl` will be inside `com`.

Described more technically, `import` first creates a new empty namespace, and then executes the template given with `path` parameter inside that namespace, so the template populates the namespace with variables (macros, functions, ...etc.). Then the namespace is assigned to the variable specified with the `hash` parameter, and you can access its contents through that. A namespace is a hash, hence the dot operator worked above. The assignment is like the `assign` directive, that is, it sets the variable in the current namespace. Except, if the import happens in the namespace of the main (topmost) template, the hash variable is also created in the global namespace.

If you call `import` with the same `path` for multiple times, it will create the namespace and run the template for the first call of `import` only. The later calls will just give back the namespace that was created and initialized when the template was imported for the first time, and will not execute the imported template.

Any output printed by the imported template will be ignored (will not be inserted at the place of `import` directive invocation). An imported template is executed to populate its namespace with variables, and not to write to the output.

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 uses the `import` directive. Absolute paths are relative to a base (often referred as the ''root directory of the templates'') that the programmer defines when configuring FreeMarker.

Always use `/` (slash) to separate path components, never `\` (backslash). If you are loading templates from your local file system and it uses backslashes (like under Windows), FreeMarker will do the necessary conversions automatically.

Like with the `include` directive, acquisition and localized lookup may be used for resolving the path.

Note that it's possible to automatically do the commonly used imports for all templates, with the "auto imports" setting of `Configuration`. Because templates may not use all the automatically imported namespaces, it's also possible to make imports lazy (on demand), with the "lazy auto imports" setting of `Configuration`.

If you are new to namespaces, you should read: Template Author's Guide/Miscellaneous/Namespaces

In case you are not sure if you should use the `import`, or the somewhat similar `include` directive, then see this.

Previous Next