老式的 macro 和 call 指令

概要

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

这里：

• name：宏的名称(不是表达式)
• argName1， argName2等： 存储参数值的 局部变量 的名称(不是表达式)
• argValue1， argValue2， 等：表达式，参数的值

描述

宏是关联名称的模板段。你可以在你的模板中的很多位置使用命名的代码段， 所以它可以在重复的任务中帮助你。宏可以有参数，这会在你调用它的时候影响生成的输出。

你可以使用 macro 指令来定义宏，之后你可以在整个模板中定义宏。 macro 指令本身不往输出中写任何东西，它只是用来定义宏。 例如这会定义一个名为 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>

当你使用 call 指令和宏名称时， 宏定义体(在宏开始标签和结束标签之间)会被处理。例如， 这会调用名为 warning 的宏：

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

将会输出：

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

给 call 指令传递的参数可以在宏定义体中作为 局部变量访问。

当调用宏时，必须指定和宏定义时指定的个数相同的参数。 例如，如果这是宏的定义：

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

那么这些是合法的宏调用：

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

如果宏没有参数，那么可以忽略圆括号：

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

当你定义宏时，那么它在模板中就是可用的，你也只能在模板中来定义宏。 但是你可能想在更多模板中使用相同的宏。这种情况下你可以在公共文件中存储你定义的宏， 之后在所有你需要这些宏的模板中包含那个文件。

调用定义在模板下部的宏是不错的 (因为宏在解析时间定义，而不是执行时间)。然而， 如果宏定义被插入到 include 指令中， 它们知道 FreeMarker 执行 include 指令时才会可用。

你可以用 return 指令在 </#macro> 标签之前留下宏定义体。