宏调用

#macro 脚本元素准许模板设计者定义一个可重用的VTL模板片段. Velocimacros(宏调用)被广泛用在简单和复杂的场景中.Velocimacro可以用来保存用户的点击次数和最少的板式错误, 提供一个简单的概念介绍。

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

上个实例中Velocimacro被定义为d, 它可以像其他VTL方式一样被调用:

#d()

当#d()被调用的时, Velocity将用定义的一行内容来替换#d().如果你想在行里面添加内容, 你也可以向下面这样来改变macro的定义:

#macro( d )  <tr><td>$!bodyContent</td></tr>  #end

现在, 如果你想调用macro会和之前有点不同, 名字之前需要加上#@ 加上一个内容体,同时以#end调用, 当Velocity加载时遇见 $!bodyContent会进行显示:

#@d()Hello!#end

如果你一直坚持像之前那种方式调用, 我们使用隐形的引用代替body引用($!bodyContent 代替$bodyContent), 它将一直显示一个空的单元格.

Velocimacro也可以携带许多参数 — 甚至是不带参数, 如同第一个实例中, 参数是可选项– 但是当Velocimacro执行时, 它必须调用和你定义的方法的参数匹配. 被执行的Velocimacros要多于上面定义的. 下面实例所示一个Velocimacro携带两个参数一个是color和一个数组.

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

上面的Velocimacro实例中, 定义一个tablerows,带两个参数. 第一个参数是$color, 第二个参数是 $somelist.

任何可以被放到VTL模板中都可以作为Velocimacro的函数体.  tablerows 是Velocimacro的一个 foreach语句. 这里有两个 #end语句被定义在#tablerows中; 第一个是属于 #foreach, 第二个是属于Velocimacro .

#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模板。定义一个Velocimacro并在所有模板中共享,这使它具有明显的优势: 它避免了在各个页面中重复定义Velocimacro, 减少工作量并且可以避免错误, 这种也可以通过改变一个地方而达到其他地方一起修改的目的.

#tablerows($color $list) Velocimacro 被定义在 Velocimacros 模板的依赖包中, 它可以保证在其他地方被大量使用. 它能够被多次重复使用来解决不同的问题. 在模板 mushroom.vm 中专注与正真的事情,#tablerows Velocimacro 能够被遍历,显示所有部分:

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

Velocimacro ArgumentsVelocimacros可以携带下面的VTL元素作为参数 :

• Reference : anything that starts with ‘$’
• String literal : something like “$foo” or ‘hello’
• Number literal : 1, 2 etc
• IntegerRange : [ 1..2] or [$foo .. $bar]
• ObjectArray : [ “a”, “b”, “c”]
• boolean value true
• boolean value false

当传递一个引用作为Velocimacros的参数时,注意引用是通过名字传递的. 这意味着它们的值是在Velocimacro中已经生成了. 这个特性准许你传递一个方法的调用引用在方法中也可以使用方法调用. 例如, 当我们调用下面的Velocimacro将显示

#macro( callme $a )           $a $a $a       #end         #callme( $foo.bar() )

在方法中 bar() 的结果将被调用三次.

第一次看到这个特性会发现很惊奇, 当你仔细的思考Velocimacros背后的动机–消除VTL中公共的重复使用 –它变的有意义. 它准许你做一些事情,比如传递一个对象的状态, 例如在Velocimacro中重复生成有颜色的表格对象.

如果你不想使用这个特性,你就想从一个引用的方法中获取值,你可以这样做 :

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

Velocimacro Properties在 velocity.properties 文件中准许灵活的实现Velocimacros. 这里也提供了开发者文档Developer Guide.

velocimacro.library – 一个通用的和其他依赖包分开的 Velocimacro模板依赖包. 默认, Velocity看起来想一个单独的 函数库: VM_global_library.vm. 配置模板的路径用来使用找到Velocimacro 函数库.

velocimacro.permissions.allow.inline – 这个属性的值可以是true或者false, 决定是否可以在模板中定义Velocimacros. 默认情况是, true, 准许模板设计者可以自行定义Velocimacros.

velocimacro.permissions.allow.inline.to.replace.global -它的值可以设定为true或者false, 这个设置准许用户指定一个模板中定义的Velocimacro能代替全局定义, 它在启动的时候被 velocimacro.library属性加载. 默认是, false, 避免在启动时候模板中定义的Velocimacros成为全局Velocimacros.

velocimacro.permissions.allow.inline.local.scope – 这个属性可能值为true 或者 false, 默认为 false, 控制 定义的Velocimacros对定义中的模板是可见的.简而言之, 如果这个属性设置为 true, 一个模板能够定义能够被定义的模板使用的VMs内 . You can use this for fancy VM tricks – if a global VM calls another global VM, 在行内的作用域内, 一个模板能够定义一个私有的实现第二个VM,它能被第一个VM调用. 但是对其他模板没有影响.

velocimacro.library.autoreload – 这个属性控制Velocimacro依赖包自动加载. 这个默认是的是false.当把属性设置为 true,当Velocimacro被执行时它将检查Velocimacro是否改变, 它重载很有必要的.它准许你改变和测试Velocimacro 不需要重庆你的应用和服务器容器, 仅仅像你可以用普通的模板. 这个模式需要关闭缓存才起作用(e.g.file.resource.loader.cache = false ). 这个特征主要用于开发模式, 而不是生产模式.

#set( $email = "foo" )  $email

## The following line defines $email in this template:  #set( $email = "foo" )  $email  \$email

foo  $email

## The following line defines $email in this template:  #set( $email = "foo" )  \\$email  \\\$email

\foo  \$email

$email  \$email  \\$email  \\\$email

$email  \$email  \\$email  \\\$email

#set( $foo = "gibbous" )  $moon = $foo

${my:invalid:non:reference}

#set( $D = '$' )  ${D}{my:invalid:non:reference}

${esc.d}{my:invalid:non:reference}

## #include( "a.txt" ) renders as <contents of a.txt>  #include( "a.txt" )    ## \#include( "a.txt" ) renders as #include( "a.txt" )  \#include( "a.txt" )    ## \\#include ( "a.txt" ) renders as \<contents of a.txt>  \\#include ( "a.txt" )

#if( $jazz )      Vyacheslav Ganelin  #end

Vyacheslav Ganelin

\#if( $jazz )      Vyacheslav Ganelin  \#end

#if( true )       Vyacheslav Ganelin   #end

\\#if( $jazz )     Vyacheslav Ganelin  \\#end

\ Vyacheslav Ganelin  \

\

\\\#if( $jazz )      Vyacheslave Ganelin  \\#end

#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )  #foreach( $shogun in $imperial )      $shogun  #end

Send me #set($foo=["$10 and ","a pie"])#foreach($a in $foo)$a#end please.

Send me  #set( $foo = ["$10 and ","a pie"] )  #foreach( $a in $foo )  $a  #end  please.

Send me  #set($foo       = ["$10 and ","a pie"])                   #foreach           ($a in $foo )$a           #end please.

#set( $foo = $bar + 3 )  #set( $foo = $bar - 4 )  #set( $foo = $bar * 6 )  #set( $foo = $bar / 2 )

#set( $foo = $bar % 5 )

[n..m]

第一个实例:  #foreach( $foo in [1..5] )  $foo  #end    第二个实例:  #foreach( $bar in [2..-2] )  $bar  #end    第三个实例:  #set( $arr = [0..1] )  #foreach( $i in $arr )  $i  #end    第四个实例:  [1..3]

First example:  1 2 3 4 5    Second example:  2 1 0 -1 -2    Third example:  0 1    Fourth example:  [1..3]

#set( $foo = "bar" )  $\!foo  $\!{foo}  $\\!foo  $\\\!foo

$!foo  $!{foo}  $\!foo  $\\!foo

\$foo  \$!foo  \$!{foo}  \\$!{foo}

$foo  $!foo  $!{foo}  \bar

#set($stuff = "#bold('hello')" )  #center( $stuff )

#center( "#bold( 'hello' )" )

#macro( inner $foo )    inner : $foo  #end    #macro( outer $foo )     #set($bar = "outerlala")     outer : $foo  #end    #set($bar = 'calltimelala')  #outer( "#inner($bar)" )

Outer : inner : outerlala

#macro( foo $color )    <tr bgcolor=$color><td>Hi</td></tr>    <tr bgcolor=$color><td>There</td></tr>  #end    #foo( $bar.rowColor() )

#set($color = $bar.rowColor())  #foo( $color )

file.resource.loader.path = templates      file.resource.loader.cache = false      velocimacro.library.autoreload = true

#set( $size = "Big" )         #set( $name = "Ben" )          The clock is $size$name.

#set( $size = "Big" )        #set( $name = "Ben" )          #set($clock = "$size$name" )          The clock is $clock.

#set( $size = "Big" )        #set( $name = "Ben" )          #set($clock = "${size}Tall$name" )          The clock is $clock.