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):
<#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:
<@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.