embed
Page Contents
Synopsis
[#embed path] or [#embed path options]
Where:
- path: The path of the file to embed; must be 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".)
-
options: One
or more of these:
encoding=encoding,
parse=parse
- encoding: Expression evaluates to string
- parse: Expression evaluates to boolean (also accepts a few string values for backward compatibility)
This directive is only available since FreeMarker 2.4.
Description
You can use it to insert the output of another template file (specified by the path parameter) into your template. The output from the embedded file is inserted at the point where the include tag occurs. The embed directive is not replaced by the content of the embedded file, it just processes the other file each time when FreeMarker reaches the embed directive in the course of template processing. So, for example if the embed is inside a list loop, you can specify different filenames in each cycle.
Note
This directive is not be confused with the JSP (Servlet) include, as it doesn't involve the Servlet container at all, just processes another FreeMarker template. Regarding how to do a "JSP include" read this...
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.
Example:
Assume /common/copyright.ftl contains:
 | | | |
|
| | |
| | |
Then this:
| | | |
|
| | |
| | |
Assuming the me variable is in the data-mode, will output this:
| | | |
|
| | |
| | |
The supported options are:
-
parse: If it is true, then the embeded file will be parsed as FTL, otherwise the whole file will be considered as plain text. If you omit this option, then it defaults to true.
-
encoding: The embedded file inherits the encoding (in practice: the charset) of the including template, unless you specify an encoding with this option. Encoding names are the same as the ones supported be java.io.InputStreamReader (as of Java API 1.3: MIME-preferred charset names from the IANA Charset Registry). Examples of valid names: ISO-8859-2, UTF-8, Shift_JIS, Big5, EUC-KR, GB2312.
Example:
| | | |
|
| | |
| | |
Using acquisition
There's a special path component represented by an asterisk (*). It is interpreted as "this directory or any of its parents". Therefore, if the template located in /foo/bar/template.ftl has the following line:
| | | |
|
| | |
| | |
then the engine will look for the template in following locations, in this order:
- /foo/bar/footer.ftl
- /foo/footer.ftl
- /footer.ftl
This mechanism is called acquisition and allows the designers to place commonly embedded files in a parent directory, and redefine them on a per-subdirectory basis as needed. We say that the including template acquires the template to embed from the first parent directory that has it. Note that you can specify not only a template name to the right of the asterisk, but a subpath as well. I.e., if the previous template instead read:
| | | |
|
| | |
| | |
then the engine would look for the template in following locations, in this order:
- /foo/bar/commons/footer.ftl
- /foo/commons/footer.ftl
- /commons/footer.ftl
Finally, the asterisk needn't be the first element of the path:
| | | |
|
| | |
| | |
would cause the engine to look for the template in following locations, in this order:
- /foo/bar/commons/footer.ftl
- /foo/bar/footer.ftl
- /foo/footer.ftl
- /footer.ftl
However, there can be at most one asterisk in the path. Specifying more than one asterisk will result in a template not being found.
Localized lookup
Whenever a template is loaded, it is assigned a locale. A locale is a language and an optional country or dialect identifier. A template is typically loaded by some code that the programmer wrote and he chooses a locale for the template based on some aspect. For example, when the FreemarkerServlet loads templates, it always requests the template with locale matching the language preference of the browser that requested the web page.
Whenever a template is loaded, it is assigned a locale. A locale is a language and an optional country or dialect identifier. A template is typically loaded by some code that the programmer wrote and he chooses a locale for the template based on some aspect. For example, when the FreeMarkerServlet loads templates, it always requests the template with locale matching the language preference of the browser that requested the web page.
When a template embeds another template, it attempts to load a template with the same locale. Suppose your template was loaded with locale en_US, which means U.S. English. When you embed another template:
| | | |
|
| | |
| | |
the engine will in fact look for several templates, in this order:
- footer_en_US.ftl,
- footer_en.ftl, and finally
- footer.ftl
Note that you can disable localized lookup feature with the setLocalizedLookup method of Configuration.
When you use both acquisition and localized template lookup, the template with more specific locale in a parent directory takes precedence over template with less specific locale in a child directory. Suppose you use the following embedding from /foo/bar/template.ftl:
| | | |
|
| | |
| | |
the engine will look for these templates, in this order:
- /foo/bar/footer_en_US.ftl
- /foo/footer_en_US.ftl
- /footer_en_US.ftl
- /foo/bar/footer_en.ftl
- /foo/footer_en.ftl
- /footer_en.ftl
- /foo/bar/footer.ftl
- /foo/footer.ftl
- /footer.ftl
