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.