12.10. 宏

#macro 脚本元素允许模板设计者在VTL 模板中定义重复的段。 Velocimacros 不管是在复杂还是简单的场合都非常有用。下面这个Velocimacro,仅用来节省击键和减少排版错误,介绍了一些Velocity宏的概念。

#macro( d )
<tr><td></td></tr>
#end

在例子中,Velocimacro定义为d,它可以象调用其他VTL指令一样的形式来进行调用:

#d()

当这个模板被调用时, Velocity 将 #d() 替换为一个单行的空表格。

Velocimacro 可以带一些参数,也可以不带参数(如上例所示)。但在他被调用时,所带的参数必须和其定义时的参数一样。很多Velocimacros 定义为不止一个参数。下面这个宏带有两个参数,一个颜色,一个数组。

#macro( tablerows $color $somelist )
#foreach( $something in $somelist )
    <tr><td bgcolor=$color>$something</td></tr>
#end
#end

在这个例子中定义的Velocimacro,名为tablerows, 要求两个参数。第一个参数代替$color, 第二个代替$somelist。

可以写进VTL 模板中的东西都可以写进Velocimacro 的主体部分。tablerows 宏其实是一个foreach 语句。在#tablerows 宏的定义中有两个#ende语句,第一个属于#foreach, 第二个结束宏定义。

#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
    #tablerows( $color $greatlakes )
</table>

请注意$greatlakes 替换了$somelist。这样,当#tablerows 宏被调用时,将产生以下输出:

<table>
    <tr><td bgcolor="blue">Superior</td></tr>
    <tr><td bgcolor="blue">Michigan</td></tr>
    <tr><td bgcolor="blue">Huron</td></tr>
    <tr><td bgcolor="blue">Erie</td></tr>
    <tr><td bgcolor="blue">Ontario</td></tr>
</table>

Velocimacros 在Velocity 模板语句内定义,这意味着它在同一站点内的其他Velocity 模板中并不有效。定义一个宏,并使其与其他模板共享很具有明显的优点:他减少了在大量的模板内重复定义宏的工作,并减少了出错的机会,并确保对其他宏的改变对其他所有模板有效。

但如果 #tablerows($color $list) 宏是在一个Velocimacros 模板库内定义的,它就可以被其他常规模板所用。当然,它可以用于各种目的,也可重用多次。在表示所有真菌类(fungi)的mushroom.vm 模板中,#tablerows 宏可以被用来列出典型的蘑菇。

#set( $parts = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $parts )
</table>

我们对mushroom.vm执行请求,Velocity 将在模板库内找到#tablerows 宏 (在velocity.properties 文件中定义)并产生以下输出:

<table>
    <tr><td bgcolor="#CC00FF">volva</td></tr>
    <tr><td bgcolor="#CC00FF">stipe</td></tr>
    <tr><td bgcolor="#CC00FF">annulus</td></tr>
    <tr><td bgcolor="#CC00FF">gills</td></tr>
    <tr><td bgcolor="#CC00FF">pileus</td></tr>
</table>