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. It follows the same syntax as like top-level variable references, like myMacro or my\-macro. However, it can also be written as a string literal, which is useful if the macro name contains characters that can’t be specified in an identifier, 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>. The parameter name uses the same syntax as like [top-level variable references], so the same features and restrictions apply.

  • paramN, the last parameter may optionally has 3 trailing dots (...), which indicates that the macro takes a variable number of parameters and the parameters that doesn’t match any other parameters will be collected in this last parameter (also called the catch-all parameter). When the macro is called with named parameters, paramN will be a hash containing all of the undeclared key/value pairs passed to the macro. When the macro is called using positional parameters, paramN will be the sequence of the extra parameter values. (Inside the macro, to find out which was the case, you can use myCatchAllParam?is_sequence.)

  • 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:

Template 
<#-- call the macro; the macro variable is already created: -->
<@test/>
...

<#-- create the macro variable: -->
<#macro test>
  Test text
</#macro>

Example: Macro without parameters:

Template 
<#macro test>
  Test text
</#macro>
<#-- call the macro: -->
<@test/>

Output:

Output 
  Test text

Example: Macro with parameters:

Template 
<#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:

Output 
  Test text, and the params: a, b, 23

Example: Macro with parameters and default parameter values:

Template 
<#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:

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.

Template 
<#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:

Output 
  <p>Animals:
  <ul>
      <li>Mouse
      <li>Elephant
      <li>Python
  </ul>

Example: A macro with support for a variable number of named parameters:

Template 
<#macro img src extra...>
  <img src="/myapp${src?ensure_starts_with('/')}"
    <#list extra as attrName, attrVal>
      ${attrName}="${attrVal}"
    </#list>
  >
</#macro>
<@img src="/images/test.png" width=100 height=50 alt="Test"/>

Output:

Output 
  <img src="/context/images/test.png"
    alt="Test"
    height="50"
    width="100"
  >

Example: A macro that supports a variable number of positional parameters, regardless if it uses named or positional parameter passing:

Template 
<#macro m a b ext...>
  a = ${a}
  b = ${b}
  <#if ext?is_sequence>
    <#list ext as e>
      ${e?index} = ${e}
    </#list>
  <#else>
    <#list ext as k, v>
      ${k} = ${v}
    </#list>
  </#if>
</#macro>

<@m 1 2 3 4 5 />

<@m a=1 b=2 c=3 d=4 e=5 data\-foo=6 myns\:bar=7 />

Output:

Output 
  a = 1
  b = 2
      0 = 3
      1 = 4
      2 = 5

  a = 1
  b = 2
      c = 3
      d = 4
      e = 5
      data-foo=6
      myns:bar=7

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:

Template 
<#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:

Template 
<#macro do_thrice>
  <#nested 1>
  <#nested 2>
  <#nested 3>
</#macro>
<@do_thrice ; x>
  ${x} Anything.
</@do_thrice>
Output 
  1 Anything.
  2 Anything.
  3 Anything.

A more complex example:

Template 
<#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>
Output 
  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:

Template 
<#macro test>
  Test text
  <#return>
  Will not be printed.
</#macro>
<@test/>
Output 
  Test text
Page contents