FreeMarker设计指南(4)

4、杂项

（1）用户定义指令

l         宏和变换器变量是两种不同类型的用户定义指令，它们之间的区别是宏是在模板中使用macro指令定义，而变换器是在模板外由程序定义，这里只介绍宏

l         基本用法

Ø         宏是和某个变量关联的模板片断，以便在模板中通过用户定义指令使用该变量，下面是一个例子：

<#macro greet>

  <font size="+2">Hello Joe!</font>

</#macro>  

Ø         作为用户定义指令使用宏变量时，使用@替代FTL标记中的#

<@greet></@greet>

Ø         如果没有体内容，也可以使用：

<@greet/>

l         参数

Ø         在macro指令中可以在宏变量之后定义参数，如：

<#macro greet person>

  <font size="+2">Hello ${person}!</font>

</#macro> 

Ø         可以这样使用这个宏变量：

<@greet person="Fred"/> and <@greet person="Batman"/> 

输出结果是：

  <font size="+2">Hello Fred!</font>

 and   <font size="+2">Hello Batman!</font>

Ø         宏的参数是FTL表达式，所以下面的代码具有不同的意思：

<@greet person=Fred/>

Ø         这意味着将Fred变量的值传给person参数，该值不仅是字符串，还可以是其它类型，甚至是复杂的表达式

Ø         宏可以有多参数，下面是一个例子：

<#macro greet person color>

  <font size="+2" color="${color}">Hello ${person}!</font>

</#macro> 

Ø         可以这样使用该宏变量：

<@greet person="Fred" color="black"/> 

Ø         其中参数的次序是无关的，因此下面是等价的：

<@greet color="black" person="Fred"/>

Ø         只能使用在macro指令中定义的参数，并且对所有参数赋值，所以下面的代码是错误的：

<@greet person="Fred" color="black" background="green"/>

<@greet person="Fred"/>

Ø         可以在定义参数时指定缺省值，如：

<#macro greet person color="black">

  <font size="+2" color="${color}">Hello ${person}!</font>

</#macro>  

Ø         这样<@greet person="Fred"/>就正确了

Ø         宏的参数是局部变量，只能在宏定义中有效

l         嵌套内容

Ø         用户定义指令可以有嵌套内容，使用<#nested>指令执行指令开始和结束标记之间的模板片断

Ø         例子：

<#macro border>

  <table border=4 cellspacing=0 cellpadding=4><tr><td>

    <#nested>

  </tr></td></table>

</#macro>  

这样使用该宏变量：

<@border>The bordered text</@border>

输出结果：

  <table border=4 cellspacing=0 cellpadding=4><tr><td>

    The bordered text

  </tr></td></table>

Ø         <#nested>指令可以被多次调用，例如：

<#macro do_thrice>

  <#nested>

  <#nested>

  <#nested>

</#macro>

<@do_thrice>

  Anything.

</@do_thrice>  

输出结果：

  Anything.

  Anything.

  Anything. 

Ø         嵌套内容可以是有效的FTL，下面是一个有些复杂的例子：

<@border>

  <ul>

  <@do_thrice>

    <li><@greet person="Joe"/>

  </@do_thrice>

  </ul>

</@border> 

输出结果：

  <table border=4 cellspacing=0 cellpadding=4><tr><td>

      <ul>

    <li><font size="+2">Hello Joe!</font>

    <li><font size="+2">Hello Joe!</font>

    <li><font size="+2">Hello Joe!</font>

  </ul>

  </tr></td></table>  

Ø         宏定义中的局部变量对嵌套内容是不可见的，例如：

<#macro repeat count>

  <#local y = "test">

  <#list 1..count as x>

    ${y} ${count}/${x}: <#nested>

  </#list>

</#macro>

<@repeat count=3>${y?default("?")} ${x?default("?")} ${count?default("?")}</@repeat>

输出结果：

    test 3/1: ? ? ?

    test 3/2: ? ? ?

    test 3/3: ? ? ?

Ø          

l         在宏定义中使用循环变量