Old-style macro and call directives

Page Contents

Synopsis
Description

Synopsis

<#macro name(argName1, argName2, ... argNameN)>
  ...
</#macro>
 
<#call name(argValue1, argValue2, ... argValueN)>

Where:

name: name of the macro (not expression)
argName1, argName2, ...etc.: the name of the local variables store the parameter values (not expression)
argValue1, argValue2, ...etc.: expressions, the value of the parameters

Description

Note

This is the documentation of FreeMarker 2.1 macro and macro related directives. These are still working, but deprecated. You may want to read the FreeMarker 2.2+ references: macro, return, user-defined directive call

A macro is a template fragment with an associated name. You can use that named fragment on multiple places in your template, so it helps in repetitive tasks. A macro can have parameters that influence the output generated when you use the macro.

You define a macro with the macro directive, and then you can use the defined macro in the whole template. The macro directive itself does not write anything to the output, it just defines the macro. For example this will define a macro called warning:

<#macro warning(message)>
  <div align=center>
  <table border=1 bgcolor=yellow width="80%"><tr><td align=center>
    <b>Warning!</b>
    <p>${message}
  </td></tr></table>
  </div>
</#macro>

The macro definition body (the section between the macro start-tag and end-tag) will be processed whenever you use the call directive with the name of the macro. For example this calls the macro called warning:

<#call warning("Unplug the machine before opening the cover!")>

and will write this to the output:

  <div align=center>
  <table border=1 bgcolor=yellow width="80%"><tr><td align=center>
    <b>Warning!</b>
    <p>Unplug the machine before opening the cover!
  </td></tr></table>
  </div>

The parameters passed in as parameters to the call directive will be accessible in the macro definition body as local variables.

When you call a macro, you must specify the same number of parameters as were specified in the macro definition. For example if this is the macro definition:

<#macro test(a, b, c)>Nothing...</#macro>

then these are valid macro calls:

<#call test(1, 2, 3)>
<#call test("one", 2 + x, [1234, 2341, 3412, 4123])>

If a macro has no parameters, then you can omit the parentheses:

<#macro test>mooo</#macro>
<#call test>

When you define a macro it will be available in the template, where you have defined it only. But probably you want to use the same macros in more templates. In this case you can store your macro definitions in a common file, and then include that file in all templates where you need those macros.

It's fine to call a macro that's defined further down in the template (since macros are defined at parse time, not in process time). However, if the macro definitions are inserted with include directive, they will not be available until FreeMarker has executed the include directive.

You can leave a macro definition body before the </#macro> tag with the return directive.


FreeMarker Manual -- For FreeMarker 2.3.20 HTML generated: 2013-06-27 20:54:33 GMT