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

Imports a library. That is, it creates a new empty namespace, and then executes the template given with path parameter in that namespace so the template populates the namespace with variables (macros, functions, ...etc.). Then it makes the newly created namespace available to the caller with a hash variable. The hash variable will be created as a plain variable in the namespace used by the caller of import (as if you would create it with assign directive), with the name given with the hash parameter. If the import happens in the namespace of the main 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 very first call of import only. The later calls will just create a hash by which you can access the same namespace.

The output printed by the imported template will be ignored (will not be inserted at the place of importing). The template is executed to populate the namespace with variables, and not to write to the output.

Example:

<#import "/libs/mylib.ftl" as my>

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

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 he configures 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 convert them automatically.

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

Note, that it is possible to automatically do the commonly used imports for all templates, with the "auto imports" setting of Configuration.

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