<#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
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
and will write this to the output:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
then these are valid macro calls:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
If a macro has no parameters, then you can omit the parentheses:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
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.