<#import path as hash>
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.)
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 "/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. before the macro name above. All that was defined in
/libs/commons.ftl will be inside
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.
path parameter can be a relative path like
"../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.
/ (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.
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
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.