macro, nested, return
Synopsis
<#macro name param1 param2 ... paramN>
...
<#nested loopvar1, loopvar2, ..., loopvarN>
...
<#return>
...
</#macro>
Where:
-
name: name
of macro variable. It's not an expression. However, it can be
written as a string literal, which is useful if the macro name
contains reserved characters, for example <#macro
"foo-bar">.... Note that
this string literal does not expand interpolations (as
"${foo}").
-
param1,
param2, ...etc.:
the name of the local
variables store the parameter values (not expression),
optionally followed by = and the default
value (that's an expression). The default value can even be
another parameter, for example <#macro section title
label=title>.
-
paramN, the
last parameter, may optionally include a trailing ellipsis
(...), which indicates the macro takes a
variable number of parameters. If called using named parameters,
paramN will be a
hash containing all of the undeclared key/value pairs passed to
the macro. If called using positional parameters,
paramN will be a
sequence of the extra parameters.
-
loopvar1,
loopvar2, ...etc.:
Optional. The values of loop
variables that the nested directive
wants to create for the nested content. These are
expressions.
The return and nested
directives are optional and can be used anywhere and for any times
between the <#macro
...> and
</#macro>.
Parameters without default value must precede parameters with
default value
(paramName=defaultValue).
Description
Creates a macro variable (in the current namespace, if you
know namespace feature). If you are new to macros and user-defined
directives you should read the the tutorial about user-defined
directives.
Macro variable stores a template fragment (called macro
definition body) that can be used as user-defined directive.
The variable also stores the name of allowed parameters to the
user-defined directive. You must give value for all of those
parameters when you use the variable as directive, except for
parameters that has a default value. The default value will be used
if and only if you don't give value for the parameter when you call
the macro.
The variable will be created at the beginning of the template;
it does not mater where the macro directive is
placed in the template. Thus, this will work:
 | | |
|
<#-- call the macro; the macro variable is already created: -->
<@test/>
...
<#-- create the macro variable: -->
<#macro test>
Test text
</#macro> |
| |
| | |
However, if the macro definitions are inserted with
include directive, they will not be available
until FreeMarker has executed the include
directive.
Example: Macro without parameters:
| | |
|
<#macro test>
Test text
</#macro>
<#-- call the macro: -->
<@test/> |
| |
| | |
Output:
Example: Macro with parameters:
| | |
|
<#macro test foo bar baaz>
Test text, and the params: ${foo}, ${bar}, ${baaz}
</#macro>
<#-- call the macro: -->
<@test foo="a" bar="b" baaz=5*5-2/> |
| |
| | |
Output:
| | |
|
Test text, and the params: a, b, 23
|
| |
| | |
Example: Macro with parameters and default parameter
values:
| | |
|
<#macro test foo bar="Bar" baaz=-1>
Test text, and the params: ${foo}, ${bar}, ${baaz}
</#macro>
<@test foo="a" bar="b" baaz=5*5-2/>
<@test foo="a" bar="b"/>
<@test foo="a" baaz=5*5-2/>
<@test foo="a"/> |
| |
| | |
Output:
| | |
|
Test text, and the params: a, b, 23
Test text, and the params: a, b, -1
Test text, and the params: a, Bar, 23
Test text, and the params: a, Bar, -1
|
| |
| | |
Example: A more complex macro.
| | |
|
<#macro list title items>
<p>${title?cap_first}:
<ul>
<#list items as x>
<li>${x?cap_first}
</#list>
</ul>
</#macro>
<@list items=["mouse", "elephant", "python"] title="Animals"/> |
| |
| | |
Output:
| | |
|
<p>Animals:
<ul>
<li>Mouse
<li>Elephant
<li>Python
</ul>
|
| |
| | |
Example: A macro with support for a variable number of named
parameters:
| | |
|
<#macro img src extra...>
<img src="/context${src?html}"
<#list extra?keys as attr>
${attr}="${extra[attr]?html}"
</#list>
>
</#macro>
<@img src="/images/test.png" width=100 height=50 alt="Test"/> |
| |
| | |
Output:
| | |
|
<img src="/context/images/test.png"
alt="Test"
height="50"
width="100"
> |
| |
| | |
nested
The nested directive executes the
template fragment between the start-tag and end-tags of the
user-defined directive. The nested part can contain anything what
is valid in templates; interpolations, directives, ...etc. It is
executed in the context where the macro was called from, rather
than in the context of the macro definition body. Thus, for
example, you don't see the local variables of the macro in the
nested part. If you don't call the nested
directive, the part between the start-tag and end-tags of the
user-defined directive will be ignored.
Example:
| | |
|
<#macro do_twice>
1. <#nested>
2. <#nested>
</#macro>
<@do_twice>something</@do_twice> |
| |
| | |
Output:
| | |
|
1. something
2. something
|
| |
| | |
The nested directive can create loop variables for the
nested content. For example:
| | |
|
<#macro do_thrice>
<#nested 1>
<#nested 2>
<#nested 3>
</#macro>
<@do_thrice ; x>
${x} Anything.
</@do_thrice> |
| |
| | |
This will print:
| | |
|
1 Anything.
2 Anything.
3 Anything.
|
| |
| | |
A more complex example:
| | |
|
<#macro repeat count>
<#list 1..count as x>
<#nested x, x/2, x==count>
</#list>
</#macro>
<@repeat count=4 ; c, halfc, last>
${c}. ${halfc}<#if last> Last!</#if>
</@repeat> |
| |
| | |
The output will be:
| | |
|
1. 0.5
2. 1
3. 1.5
4. 2 Last!
|
| |
| | |
return
With the return directive, you can leave
a macro or function definition body anywhere. Example:
| | |
|
<#macro test>
Test text
<#return>
Will not be printed.
</#macro>
<@test/> |
| |
| | |
Output:
