VTL说明文档

关于这个指南

这个指南是针对Velocity模版语言(VTL)的说明。更多其它的信息，请参考Velocity用户指南(http://velocity.apache.org/engine/releases/velocity-1.7/user-guide.html)。

说明

变量

表达式：

$ [ ! ][ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ][ } ]

示例：

速记表达式：$mud-Slinger_9
速记表达式：$!mud-Slinger_9
正规表达法：${mud-Slinger_9}
正规表达法：$!{mud-Slinger_9}

属性

表达式：

$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ]* .[a..z, A..Z ][ a..z, A-Z, 0..9, -, _ ]* [ } ]

示例：

合法的表达式：$customer.Address
正规的表达式：${purchase.Total}

方法

表达式：

$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ]* .[ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ]*( [ optional parameter list... ] ) [ } ]

示例：

合法的表达式：$customer.getAddress()
正规的表达式：${purchase.getTotal()}
带参数列表的合法表达式：$page.setTitle("My Home Page")

VTL属性可以使用取出set和get的速记表达式方式，$object.getMethod()或者$object.setMethod()都可以缩写成$object.Method，允许的情况下，一般都是比较喜欢写成属性的表达式方式。属性和方法主要的区别就在于方法可以有一个带参数的列表。

命令

#set - Establishes the value of a reference

格式：

# [ { ] set [ } ] ( $ref = [ ", ' ]arg[ ", ' ] )

使用：

$ref -
arg -

示例：

变量：#set($monkey=$bill)
字符串：#set($monkey.Friend='monica')
属性：#set($monkey.Blame=$whitehouse.Leak)
方法：#set( $monkey.Plan = $spindoctor.weave($web))
数字：#set( $monkey.Number = 123 )
区间操作：#set( $monkey.Numbers = [1..3] )
列表：#set( $monkey.Say = ["Not", $my, "fault"] )
Map：#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"})

RHS也可以是一个表达式，比如：

加法：#set( $value = $foo + 1 )
减法：#set( $value = $bar - 1 )
乘法：#set( $value = $foo * $bar )
除法：#set( $value = $foo / $bar )
取余：#set( $value = $foo % $bar )

#if/#elseif/#else - Output conditional on truth of statements

格式：

# [ { ] if [ } ] ( [condition] ) [output] [ # [ { ] elseif [ } ] ( [condition] ) [output] ]* [ # [ { ] else [ } ] [output] ] # [ { ] end [ } ]

使用：

条件：如果是boolean类型，considered true if it has a true false；如果不是boolean类型，如果不为null则为true
输出：包含VTL

示例：

操作名	符号	可选符号	示例
数字等于	==	eq	#if($foo == 42)
字符等于	==	eq	#if($foo == 'bar')
对象相等	==	eq	#if($foo == $bar)
不等	!=	ne	#if($foo != $bar)
大于	>	gt	#if($foo > 42)
小于	<	lt	#if($foo < 42)
大于等于	>=	ge	#if($foo >= 42)
小于等于	<=	le	#if($foo <= 42)
boolean取反	!	not	#if(!$foo)

注意：

==可以用来比较数字、字符串和对象相等，最后一个例子中(对象不是相同的类)，toString()方法会被调用，然后将出来的字符串进行对比
你可以使用括号分隔他们，当文本后面紧跟着#的时候，这个是十分有用的。

#if( $foo == $bar)it's true!#{else}it's not!#end</li>

#foreach - Loops through a list of objects

格式：

# [ { ] foreach [ } ] ($refinarg)statement# [ { ] end [ } ]

用法：

$ref - 循环列表中的第一个变量引用。
arg - 它可以使一种列表引用(对象数组，集合或者Map)，一种数组列表或者一个区间操作。

statement - 当Velocity在列表arg中找到一个合法的对象时，它将输出合法的VTL。

示例：

引用：#foreach ( $item in $items )
数组列表：#foreach ( $item in ["Not", $my, "fault"] )
区间操作：#foreach ( $item in [1..3] )

Velocity提供了一个简单的方法来获取循环的次数：

<table>
#foreach( $customer in $customerList )

<tr><td>$foreach.count</td><td>$customer.Name</td></tr>
#end
</table>

另外，在Velocity1.5中允许循环最大数字是可以控制的。默认没有限制：

#
The maximum allowed number of loops.
directive.foreach.maxloops = -1

#include - Renders local file(s)
that are not parsed by Velocity

格式：

# [ { ] include [ } ] ( arg[ arg2 ... argn] )

arg - TEMPLATE_ROOT下一个合法的文件引入。

示例：

String：#include( "disclaimer.txt" "opinion.txt" )
变量：#include( $foo $bar )

#parse - Renders a local template that is parsed by Velocity

格式：

# [ { ] parse [ } ] ( arg )

arg - TEMPLATE_ROOT下的模版文件。

示例：

String： #parse( "lecorbusier.vm" )
变量：#parse( $foo )

递归也是被允许的，可以看一下velocity.properties中的parse_directive.maxdepth来修改parse的深度（默认的parse深度是10）。

#stop - Stops the template engine

格式：

# [ { ] stop [ } ]

使用场景：

停止目前的模版，在debug模版的时候比较好用。

#break - Stops the current directive

格式：

# [ { ] break [ } ]

使用场景：终止目前的内容指令，早期在#foreach中是用来提前结束循环的，也可以再其他的范围。你甚至可以在外部范围中跳过特殊的范围。

#evaluate - Dynamically evaluates a string or reference

格式：

# [ { ] evaluate [ } ] ( arg )

arg - String literal or reference to be dynamically evaluated.

示例：

String: #evaluate( 'string with VTL #if(true)will be displayed#end' )
变量: #include( $foo )

#define - Assigns a block of VTL to a reference

格式：

# [ { ] define [ } ] ( $ref )statement# [ { ] end [ } ]

$ref - Reference that is assigned the VTL block as a value.
statement - Statement that is assigned to the reference.

示例：

#define( $hello ) Hello $who #end #set( $who = "World!") $hello ## displays Hello World!

#macro - Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required

格式：

# [ { ] macro [ } ] ( vmname $arg1 [ $arg2 $arg3 ... $argn ] ) [ VM VTL code... ] # [ { ] end [ } ]

vmname - 调用VM的时候命名

$arg1 $arg2 [ ... ] - VM参数。可以有多个参数，但是参数必须在定义匹配上。
[ VM VTL code... ] - 任何合法的VTL代码都可以放置到模版中，也可以放到VM中。

一旦定义，vm可以像其他VTL指令一样来使用。

#vmname( $arg1 $arg2 )

除此，当你在body中想要调用vm，你必须在vm前面添加@，通过$!bodyContent，body就会找到宏定义的引用。

#@vmname( $arg1 $arg2 ) here is the body#end

VMs可以2个地方定义：

模板库：可以从任何模版中来预封装或者自定义，用户定义，网站定制
内联：在velocity.properties中仅当velocitymarco.permissions.allowInline=true的时候，可以再正式的模版中使用。

注释

注释不是运行时渲染的。

单行注释

## This is a comment.

多行注释

This is a multiline comment.

This is the second line

不做解析的内容

不做解析的内容是在运行时渲染的，而不是不解析。

#[[

This has invalid syntax that would normally need "poor man's escaping" like:

#define()
${blah

]]#