Velocity下面的Velocimacros设置

Velocimacros

#macro script element允许模板设计者定义一段可重用的VTL template。Velocimacros广泛用于简单和复杂的行列。Velocimacros的出现是为了减少编码和极小化排版错误，对Velocimacros的概念提供一个介绍。

#macro( d )

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

#end

在上面的例子中Velocimacro被定义为d，然后你就可以在任何VTL directive中以如下方式调用它：

#d()

当你的template被调用时，Velocity将用<tr><td></td></tr>替换为#d()。

每个Velocimacro可以拥有任意数量的参数――甚至0个参数，虽然定义时可以随意设置参数数量，但是调用这个Velocimacro时必须指定正确的参数。下面是一个拥有两个参数的Velocimacro，一个参数是color另一个参数是array：

#macro( tablerows $color $somelist )

#foreach( $something in $somelist )

<tr><td bgcolor=$color>$something</td></tr>

#end

#end

Velocimacro在这个例子的定义，tablerows，有两个元素。第一个是替换 $color ,第二个是替换$somelist。

任何东西都可以通过Velocimacro加入到VTL模板中。tablerows Velocimacro 是一个foreach 标识。 这里有两个#end标识在#tablerows Velocimacro 定义里面。第一个是属于 #foreach，第二个是属于Velocimacro定义的。

#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )

#set( $color = "blue" )

<table>

#tablerows( $color $greatlakes )

</table>

注意到$greatlakes 替代 $somelist。当#tablerows Velocimacro被调用时，就会产生下面的输出：

<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模板内实现行内定义（inline），也就意味着同一个web site内的其他Velocity模板不可以获得Velocimacros的定义。定义一个可以被所有模板共享的Velocimacro显然是有很多好处的：它减少了在一大堆模板中重复定义的数量、节省了工作时间、减少了出错的几率、保证了单点修改。

上面定义的#tablerows( $color $list )Velocimacro被定义在一个Velocimacros模板库(在velocity.properties中定义)里，所以这个macro可以在任何规范的模板中被调用。它可以被多次应用并且可以应用于不同的目的。例如下面的调用：

#set( $parts = ["volva","stipe","annulus","gills","pileus"] )

#set( $cellbgcol = "#CC00FF" )

<table>

#tablerows( $cellbgcol $parts )

</table>

当为mushroom.vm实现一个请求时，Velocity会在模板库中找到#tablerows Velocimacro(定义在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>

Velocimacro arguments

Velocimacro可以使用以下任何元素作为参数：

l          Reference：任何以$开头的reference

l          String literal：

l          Number literal：

l          IntegerRange：[1….3]或者[$foo….$bar]

l          对象数组：[“a”,”b”,”c”]

l          boolean值：true、false

当将一个reference作为参数传递给Velocimacro时，请注意reference作为参数时是以名字的形式传递的。这就意味着参数的值在每次Velocimacro内执行时才会被产生。这个特性使得你可以将一个方法调用作为参数传递给Velocimacro，而每次Velocimacro执行时都是通过这个方法调用产生不同的值来执行的。例如：

#macro( callme $a )

$a $a $a

#end

#callme( $foo.bar() )

执行的结果是：reference $foo的bar（）方法被执行了三次。

在第一次扫描中，出现惊人的作用。但是当你考虑到Velocimacro的最原始动机：消除剪切、粘贴、复制，简单地使用VTL使它更灵活。它允许你对传递对象到Velocimacro，例如一个产生重复序列颜色，着色表格的行的对象。

如果你不需要这样的特性可以通过以下方法：

#set( $myval = $foo.bar() )

#callme( $myval )

Velocimacro properties

Velocity.properties文件中的某几行能够使Velocimacros的实现更加灵活。注意更多的内容可以看Developer Guide。

Velocity.properties文件中的velocimacro.libraary：一个以逗号分隔的模板库列表。默认情况下，velocity查找唯一的一个库：VM_global_library.vm。你可以通过配置这个属性来指定自己的模板库。

Velocity.properties文件中的velocimacro.permissions.allow.inline属性：有两个可选的值true或者false，通过它可以确定Velocimacros是否可以被定义在regular template内。默认值是ture――允许设计者在他们自己的模板中定义Velocimacros。

Velocity.properties文件中的velocimacro.permissions.allow.inline.replace.global属性有两个可选值true和false，这个属性允许使用者确定inline的Velocimacro定义是否可以替代全局Velocimacro定义（比如在velocimacro.library属性中指定的文件内定义的Velocimacro）。默认情况下，此值为false。这样就阻止本地Velocimacro定义覆盖全局定义。

Velocity.properties文件中的velocimacro.permissions.allow.inline.local.scale属性也是有true和false两个可选值，默认是false。它的作用是用于确定你inline定义的Velocimacros是否仅仅在被定义的template内可见。换句话说，如果这个属性设置为true，一个inline定义的Velocimacros只能在定义它的template内使用。你可以使用此设置实现一个奇妙的VM窍门：a template can define a private implementation of the second VM that will be called by the first VM when invoked by that template. All other templates are unaffected。

Velocity.properties文件中的velocimacro.context.localscope属性有true和false两个可选值，默认值为false。当设置为true时，任何在Velocimacro内通过#set()对context的修改被认为是针对此velocimacro的本地设置，而不会永久的影响内容。

Velocity.properties文件中的velocimacro.library.autoreload属性控制Velocimacro库的自动加载。默认是false。当设置为ture时，对于一个Velocimacro的调用将自动检查原始库是否发生了变化，如果变化将重新加载它。这个属性使得你可以不用重新启动servlet容器而达到重新加载的效果，就像你使用regular模板一样。这个属性可以使用的前提就是resource loader缓存是off状态（file.resource.loader.cache = false）。注意这个属性实际上是针对开发而非产品的。

Velocimacro Trivia

Velocimacro必须被定义在他们被使用之前。也就是说，你的#macro()声明应该出现在使用Velocimacros之前。

特别要注意的是，如果你试图#parse()一个包含#macro()的模板。因为#parse()发生在运行期，但是解析器在parsetiem决定一个看似VM元素的元素是否是一个VM元素，这样#parse()-ing一组VM声明将不按照预期的样子工作。为了得到预期的结果，只需要你简单的使用velocimacro.library使得Velocity在启动时加载你的VMs