Velocity用户手册
2007-10-17 00:03
429 查看
１、Velocity是什么？Velocity是一个基于java的模板引擎（template engine）。它允许任何人仅仅简单的使用模板语言（template language）来引用由java代码定义的对象。
当Velocity应用于web开发时，界面设计人员可以和java程序开发人员同步开发一个遵循MVC架构的web站点，也就是说，页面设计人员可以只关注页面的显示效果，而由java程序开发人员关注业务逻辑编码。Velocity将java代码从web页面中分离出来，这样为web站点的长期维护提供了便利，同时也为我们在JSP和PHP之外又提供了一种可选的方案。
Velocity的能力远不止web站点开发这个领域，例如，它可以从模板（template）产生SQL和PostScript、XML，它也可以被当作一个独立工具来产生源代码和报告，或者作为其他系统的集成组件使用。Velocity也可以为Turbine web开发架构提供模板服务（template service）。Velocity+Turbine提供一个模板服务的方式允许一个web应用以一个真正的MVC模型进行开发。
２、Velocity能为我们作什么？
The Mud Store Example
假设你是一家专门出售Mud的在线商店的页面设计人员，让我们暂且称它为“在线MUD商店”。你们的业务很旺，客户下了各种类型和数量的mud订单。他们都是通过输入用户名和密码后才登陆到你的网站，登陆后就允许他们查看订单并购买更多的mud。现在，一种非常流行的mud正在打折销售。另外有一些客户规律性的购买另外一种也在打折但是不是很流行的Bright Red Mud，由于购买的人并不多所以它被安置在页面的边缘。所有用户的信息都是被跟踪并存放于数据库中的，所以某天有一个问题可能会冒出来：为什么不使用velocity来使用户更好的浏览他们感兴趣的商品呢？
Velocity使得web页面的客户化工作非常容易。作为一个web site的设计人员，你希望每个用户登陆时都拥有自己的页面。
你会见了一些公司内的软件工程师，你发现他们每个人都同意客户应该拥有具有个性化的信息。那让我们把软件工程师应该作的事情发在一边，看一看你应该作些什么吧。
你可能在页面内嵌套如下的VTL声明：
<html>
<body>
Hello $customer.Name!
<table>
#foreach( $mud in $nudsOnSpecial )
#if ( $customer.hasPurchased( $mud ) )
<tr><td>$flogger.getPromo( $mud )</td></tr>
#end
#end
</table>
一、Velocity Template Language(VTL):AN introductionVTL意味着提供最简单、最容易并且最整洁的方式合并页面动态内容。
VTL使用references来在web site内嵌套动态内容，一个变量就是一种类型的reference。变量是某种类型的refreence，它可以指向java代码中的定义，或者从当前页面内定义的VTL statement得到值。下面是一个VTL statement的例子，它可以被嵌套到HTML代码中：
#set ( $a = “Velocity” )
和所有的VTL statement一样，这个statement以＃字符开始并且包含一个directive：set。当一个在线用户请求你的页面时，Velocity Templating Engine将查询整个页面以便发现所有＃字符，然后确定哪些是VTL statement，哪些不需要VTL作任何事情。
＃字符后紧跟一个directive：set时，这个set directive使用一个表达式（使用括号封闭）――一个方程式分配一个值给变量。变量被列在左边，而它的值被列在右边，最后他们之间使用＝号分割。
在上面的例子中，变量是$a，而它的值是Velocity。和其他的references一样以$字符开始，而值总是以双引号封闭。Velocity中仅有String可以被赋值给变量。
记住以下的规则：
使用$字符开始的references用于得到什么；使用#字符开始的directives用于作些什么。
Hello Velocity World!
一旦某个变量被分配了一个值，那么你就可以在HTML文件的任何地方引用它。在下面的例子中，一个值被分配给$foo变量，并在其后被引用。
<html>
<body>
#set ( $foo = “Velocity” )
Hello $foo World!
</body>
</html>
上面的实现结果是在页面上打印“Hello Velocity World！”
为了使包含VTL directives的statement更具有可读性，我们鼓励你在新行开始每个VTL statement，尽管你不是必须这么作。Set directive将在后面详细描述。
二、注释
1.单行注释：
## This is a single line comment.
2.多行注释：
#*
Thus begins a multi-line comment. Online visitors won’t
see this text because the Velocity Templating Engine will
ignore it.
*#
3.文档格式：
#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
information:
@version 5
@author
*#
三、References在VTL中有三种类型的references：变量(variables)、属性(properties)、方法(methods)。
作为一个使用VTL的页面设计者，你和你的工程师必须就references的名称达成共识，以便你可以在你的template中使用它们。
Everything coming to and from a reference被作为一个String对象处理。如果有一个对象$foo是一个Integer对象，那么Velocity将调用它的toString()方法将这个对象转型为String类型。
1.变量
格式要求同java。
2.属性
例子：
$customer.Address
$purchase.Total
$customer.Address有两种含义。它可以表示：查找hashtable对象customer中以Address为关键字的值；也可以表示调用customer对象的getAddress()方法。当你的页面被请求时，Velocity将确定以上两种方式选用那种，然后返回适当的值。
3.方法
一个方法就是被定义在java中的一段代码，并且它有完成某些有用工作的能力，例如一个执行计算和判断条件是否成立、满足等。方法是一个由$开始并跟随VTL标识符组成的References，一般还包括一个VTL方法体。例如：
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( “My Home Page” )
$person.setAttributes( [“Strange”, “Weird”, “Excited”] )
前两个例子$customer.getAddress()和$purchase.getTotal()看起来挺想上面的属性$customer.Address 和 $purchase.Total。如果你觉得他们之间有某种联系的话，那你是正确的。
VTL属性可以作为VTL方法的缩写。$customer.Address属性和使用$customer.getAddress()方法具有相同的效果。如果可能的话使用属性的方式是比较合理的。属性和方法的不同点在于你能够给一个方法指定一个参数列表。
4.正式reference标记
reference的正是格式如下：
${mudSlinger} 变量
${customer.Address} 属性
${purchase.getTotal()} 方法
非正是格式更见常用，但是有时还是使用正是格式比较适合。例如：你希望通过一个变量$vice来动态的组织一个字符串。
Jack is a $vicemaniac.
本来变量是$vice现在却变成了$vicemaniac，这样Veloctiy就不知道您到底要什么了。所以，应该使用正是格式书写
Jack is a ${vice}maniac
现在Velocity知道变量是$vice而不是$vicemaniac。
5.Quiet reference notation 例如：
<input type=”text” name=”email” value=”$email” />
当页面的form被初始加载时，变量$email还没有值，这时你肯定是希望它能够显示一个blank text来代替输出”$email”这样的字段。那么使用quiet reference notation就比较合适。
<input type=”text” name=”email” value=”$!email”/>
这样文本框的初始值就不会是email而是空值了。
正式和quiet格式的reference notation也可一同使用，像下面这样：
<input type=”text” name=”email” value=”$!{email}”/>
Getting literal
Velocity使用特殊字符$和#来帮助它工作，所以如果要在template里使用这些特殊字符要格外小心。本节将讨论$字符。
6.货币字符
在VTL中使用$2.5这样的货币标识是没有问题得的，VTL不会将它错认为是一个reference，因为VTL中的reference总是以一个大写或者小写的字母开始。
Escaping valid VTL reference
VTL中使用“/”作为逃逸符。
例如：
#set( $email = “foo” )
$email
/$email
//$email
///$email
将render为：
foo
$email
/foo
//$email
如果email变量没有被定义则
$email
/$email
//$email
///$email
将被render为：
$email
/$email
//$email
///$email
注意：VTL中未被定义的变量将被认为是一个字符串，所以以下例子：
#set( $foo = “gibbous” )
$moon = $foo
的输出结果是：
$moon = gibbous
7.Case substitution现在你已经对reference比较熟悉了，你可以将他们高效的应用于你的template了。Velocity利用了很多java规范以方便了设计人员的使用。例如：
$foo
$foo.getBar()
## is the same as
$foo.Bar
$data.getUser(“jon”)
## is the same as
$data.User(“jon”)
$data.getRequest().getServerName()
# is the same as
$data.Request.ServerName
## is the same as
${data.Request.ServerName}
但是，注意VTL中不会将reference解释为对象的实例变量。例如：$foo.Name将被解释为Foo对象的getName（）方法，而不是Foo对象的Name实例变量。
四、Directives
Reference允许设计者使用动态的内容，而directive使得你可以应用java代码来控制你的显示逻辑，从而达到你所期望的显示效果。
1. #set
#set directive被用于设置一个reference的值。例如：
#set ( $primate = “monkey” )
#set ( $customer.Behavior = $primate )
赋值左侧的（LHS）必须是一个变量或者属性reference。右侧（RHS）可以是以下类型中一种：
a. 变量reference
b. String literal
c. 属性reference
d. 方法reference
e. number literal
f. ArrayList
下面是应用各种类型的RHS的例子：
＃set ( $monkey = $bill ) ##变量reference
＃set ( $monkey.Friend = “monica” ) ##String literal
＃set ( $monkey.Blame = $whitehouse.Leak )##属性reference
＃set ( $monkey.Plan = $spindoctor.weave($web) )##方法reference
＃set ( $monkey.Number = 123 )##Number literal
＃set ( $monkey.Say = [“Not”, $my, “fault”] )##ArrayList
注意：最后一个例子的取值方法为：$monkey.Say.get(0)
RHS也可以是一个简单的算术表达式：
#set ( $value = $foo + 1 )
#set ( $value = $bar -1 )
#set ( $value = $foo * $bar )
#set ( $value = $foo / $bar )
如果你的RHS是一个null，VTL的处理将比较特殊：它将指向一个已经存在的reference，这对初学者来讲可能是比较费解的。例如：
#set ( $resut = $query.criteria(“name”) )
The result of the first query is $result
#set ( $resut = $query.criteria(“address”) )
The result of the second query is $result
如果$query.criteria(“name”)返回一个“bill”，而$query.criteria(“address”)返回的是null，则显示的结果如下：
The result of the first query is bill
The result of the first query is bill
看看下面的例子：
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
在上面的例子中，程序将不能智能的根据$result的值决定查询是否成功。在$result被#set后（added to the context），它不能被设置回null（removed from the context）。打印的结果将显示两次查询结果都成功了，但是实际上有一个查询是失败的。
为了解决以上问题我们可以通过预先定义的方式：
#set( $criteria = [“name”, “address”] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria( $criterion ) )
#if( $result )
Query was successful
#end
#end
String Literals
当你使用#set directive，String literal封闭在一对双引号内。
#set ( $directoryRoot = “www” )
#set ( $templateName = “index.vm” )
#set ( $template = “$directoryRoot/$tempateName” )
$template
上面这段代码的输出结果为：www/index.vm
但是，当string literal被封装在单引号内时，它将不被解析：
#set ( $foo = “bar” )
$foo
#set ( $blargh = ‘$foo’ )
结果：
bar
$foo
上面这个特性可以通过修改velocity.properties文件的stringliterals.interpolate = false的值来改变上面的特性是否有效。
2.条件语句 if/elseif/else 当一个web页面被生成时使用Velocity的#if directrive，如果条件成立的话可以在页面内嵌入文字。例如：
#if ( $foo )
<strong>Velocity!</strong>
#end
上例中的条件语句将在以下两种条件下成立：
l $foo是一个boolean型的变量，且它的值为true
l $foo变量的值不为null
这里需要注意一点：Velocity context仅仅能够包含对象，所以当我们说“boolean”时实际上代表的时一个Boolean对象。即便某个方法返回的是一个boolean值，Velocity也会利用内省机制将它转换为一个Boolean的相同值。
如果条件成立，那么#if和#end之间的内容将被显示。
#elseif和#else元素可以同#if一同使用。例如：
#if( $foo < 10 )
<strong> Go North </strong>
#elseif( $foo == 10 )
<strong> Go East </strong>
#elseif( $foo == 6 )
<strong> Go South </strong>
#else
<strong> Go West </strong>
#end
注意这里的Velocity的数字是作为Integer来比较的――其他类型的对象将使得条件为false，但是与java不同它使用“＝＝”来比较两个值，而且velocity要求等号两边的值类型相同。
关系、逻辑运算符
Velocity中使用等号操作符判断两个变量的关系。例如：
#set ( $foo = “deoxyribonucleic acid” )
#set ( $bar = “ribonucleic acid” )
#if ( $foo == $foo )
In this case it’s clear they aren’t equivalent.So…
#else
They are not equivalent and this will be the output.
#end
3.Velocity有AND、OR和NOT逻辑运算符。
下面是一些例子：
## logical AND
#if( $foo && $bar )
<strong> This AND that </strong>
#end
## logical OR
#if ( $foo || $bar )
<strong>This OR That </strong>
#end
##logical NOT
#if ( !$foo )
<strong> NOT that </strong>
#end
[b]4.[/b]循环 ：Foreach循环
例子：
<ul>
#foreach ( $product in $allProducts )
<li> $product </li>
#end
</ul>
每次循环$allProducts中的一个值都会赋给$product变量。
$allProducts可以是一个Vector、Hashtable或者Array。分配给$product的值是一个java对象，并且可以通过变量被引用。例如：如果$product是一个java的Product类，并且这个产品的名字可以通过调用他的getName（）方法得到。
现在我们假设$allProducts是一个Hashtable，如果你希望得到它的key应该像下面这样：
<ul>
#foreach ( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key) </li>
#end
</ul>
Velocity还特别提供了得到循环次数的方法，以便你可以像下面这样作：
<table>
#foreach ( $customer in $customerList )
<tr><td>$velocityCount</td><td>$customer.Name</td></tr>
#end
</table>
$velocityCount变量的名字是Velocity默认的名字，你也可以通过修改velocity.properties文件来改变它。默认情况下，计数从“1”开始，但是你可以在velocity.properties设置它是从“1”还是从“0”开始。下面就是文件中的配置：
# Default name of loop counter
# variable reference
directive.foreach.counter.name = velocityCount
# Default starting value of the loop
# counter variable reference
directive.foreach.counter.initial.value = 1
5.include
#include script element允许模板设计者引入本地文件。被引入文件的内容将不会通过模板引擎被render。为了安全的原因，被引入的本地文件只能在TEMPLATE_ROOT目录下。
#inclued ( “one.txt” )
如果您需要引入多个文件，可以用逗号分隔就行：
#include ( “one.gif”, “two.txt”, “three.htm” )
在括号内可以是文件名，但是更多的时候是使用变量的：
#inclue ( “greetings.txt”, $seasonalstock )
6.parse
#parse script element允许模板设计者一个包含VTL的本地文件。Velocity将解析其中的VTL并render模板。
#parse( “me.vm” )
就像#include，#parse接受一个变量而不是一个模板。任何由#parse指向的模板都必须包含在TEMPLATE_ROOT目录下。与#include不同的是，#parse只能指定单个对象。
你可以通过修改velocity.properties文件的parse_direcive.maxdepth的值来控制一个template可以包含的最多#parse的个数――默认值是10。#parse是可以递归调用的，例如：如果dofoo.vm包含如下行：
Count down.
#set ( $count = 8 )
#parse ( “parsefoo.vm” )
All done with dofoo.vm!
那么在parsefoo.vm模板中，你可以包含如下VTL：
$count
#set ( $count = $count – 1 )
#if ( $count > 0 )
#parse( “parsefoo.vm” )
#else
All done with parsefoo.vm!
#end
的显示结果为：
Count down.
8
7
6
5
4
3
2
1
0
All done with parsefoo.vm!
All done with dofoo.vm!
7.Stop
#stop script element允许模板设计者停止执行模板引擎并返回。把它应用于debug是很有帮助的。
#stop
8.Velocimacros
#macro script element允许模板设计者定义一段可重用的VTL template。例如：
#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
调用#tablerows Velocimacro：
#set ( $greatlakes = [ “Superior”, “Michigan”, “Huron”, “Erie”, “Ontario” ] )
#set ( $color = “blue” )
<table>
#tablerows( $color $greatlakes )
</table>
经过以上的调用将产生如下的显示结果：
<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>
上面VTL将产生如下的输出：
<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>
9.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（）方法被执行了三次。
如果你不需要这样的特性可以通过以下方法：
#set ( $myval = $foo.bar() )
#callme ( $myval )
10.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。
11.Escaping VTL directives
VTL directives can be escaped with “/”号，使用方式跟VTL的reference使用逃逸符的格式差不多。
## #include( “a.txt” ) renders as <ontents 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” )
在对在一个directive内包含多个script元素的VTL directives使用逃逸符时要特别小心（比如在一个if-else-end statement内）。下面是VTL的if-statement的典型应用：
#if ( $jazz )
Vyacheslav Ganelin
#end
如果$jazz是ture，输出将是：
Vyacheslav Ganelin
如果$jazz是false，将没有输出。使用逃逸符将改变输出。考虑一下下面的情况：
/#if ( $jazz )
Vyacheslav Ganelin
/#end
现在无论$jazz是true还是false，输出结果都是：
#if ( $jazz )
Vyacheslav Ganelin
#end
事实上，由于你使用了逃逸符，$jazz根本就没有被解析为boolean型值。在逃逸符前使用逃逸符是合法的，例如：
//#if ( $jazz )
Vyacheslav Ganelin
//#end
以上程序的显示结果为：
/ Vyacheslav Ganelin
/
但是如果$jazz为false，那么将没有输出。（书上说会没有输出，但是我觉得应该还有有“/”字符被输出。）
VTL：Formatting issues
尽管在此用户手册中VTL通常都开始一个新行，如下所示：
#set ( $imperial = [ “Munetaka”, “Koreyasu”, “Hisakira”, “Morikune” ] )
#foreach ( $shogun in $imperial )
$shogun
#end
但是像下面这种写法也是可以的：
Send me #set($foo = [“$10 and”,”a cake”])#foreach($a in $foo)$a #end please.
上面的代码可以被改写为：
Send me
#set ( $foo = [“$10 and “,”a cake”] )
#foreach ( $a in $foo )
$a
#end
please.
或者
Send me
#set($foo = [“$10 and “,”a cake”])
#foreach （$a in $foo ）$a
#end please.
这两种的输出结构将一样。
其他特性和杂项
math 在模板中可以使用Velocity内建的算术函数，如：加、减、乘、除
#set ( $foo = $bar + 3 )
#set ( $foo = $bar - 4 )
#set ( $foo = $bar * 6 )
#set ( $foo = $bar / 2 )
当执行除法时将返回一个Integer类型的结果。而余数你可以使用%来得到：
#set ( $foo = $bar % 5 )
在Velocity内使用数学计算公式时，只能使用像-n,-2,-1,0,1,2,n这样的整数，而不能使用其它类型数据。当一个非整型的对象被使用时它将被logged并且将以null作为输出结果。
12.Range Operator
Range operator可以被用于与#set和#foreach statement联合使用。对于处理一个整型数组它是很有用的，Range operator具有以下构造形式：
[n..m]
m和n都必须是整型，而m是否大于n则无关紧要。例子：
First example:
#foreach ( $foo in [1..5] )
$foo
#end
Second example:
#foreach ( $bar in [2..-2] )
$bar
#end
Third example:
#set ( $arr = [0..1] )
#foreach ( $i in $arr )
$i
#end
Fourth example:
[1..3]
上面四个例子的输出结果为：
First example：
1 2 3 4 5
Second example：
2 1 0 -1 -2
Third example：
0 1
Fourth example：
[1..3]
注意：range operator只在#set和#foreach中有效。
Advanced Issue：Escaping and！
当一个reference被“！”分隔时，并且在它之前有逃逸符时，reference将以特殊的方式处理。注意这种方式与标准的逃逸方式时不同的。对照如下：
#set ( $foo = “bar” )
特殊形式 标准格式
Render前 Render后 Render前 Render后
$/!foo $!foo /$foo /$foo
$/!{foo} $!{foo} /$!foo /$!foo
$//!foo $/!foo /$!{foo} /$!{foo}
$///!foo $//!foo //$!{foo} /bar
13.Velocimacro杂记
Can I user a directive or another VM as an argument to a VM?
例如：#center ( #bold( “hello” ) )
不可以。一个directive的参数使用另外一个directive是不合法的。
但是，还是有些事情你可以作的。最简单的方式就是使用双引号：
#set ( $stuff = “#bold( ‘hello’ )” )
#center ( $stuff )
上面的格式也可以缩写为一行：
#center ( “#bold( ‘hello’ ) )
请注意在下面的例子中参数被evaluated在Velocimacro内部，而不是在calling level。例子：
#macro ( inner $foo )
inner : $foo
#end
#macro ( outer $foo )
#set ( $bar = “outerlala” )
outer : $foo
#end
#set ( $bar = ‘calltimelala’ )
#outer( “#inner($bar)” )
输出结果为：
outer : inner : outerlala
记住Veloctiy的特性：参数的传递是By Name的。例如：
#macro ( foo $color )
<tr bgcolor = $color ><td>Hi</td></tr>
<tr bgcolor = $color ><td>There</td></tr>
#end
#foo ( $bar.rowColor() )
以上代码将导致rowColor()方法两次调用，而不是一次。为了避免这种现象的出现，我们可以按照下面的方式执行：
#set ( $color = $bar.rowColor() )
#foo ( $color )
can I register velocimacros via #parse()?
目前，Velocimacros必须在第一次被模板调用前被定义。这就意味着你的#macro()声明应该出现在使用Velocimacros之前。
如果你试图#parse()一个包含#macro() directive的模板，这一点是需要牢记的。因为#parse()发生在运行期，但是解析器在parsetiem决定一个看似VM元素的元素是否是一个VM元素，这样#parse()-ing一组VM声明将不按照预期的样子工作。为了得到预期的结果，只需要你简单的使用velocimacro.library使得Velocity在启动时加载你的VMs。
What is velocimacro autoreloading？
velocimacro.library.autoreload是专门为开发而非产品使用的一个属性。此属性的默认值是false。
String concatenation
开发人员最常问的问题是我如何作字符拼接？在java中是使用“＋”号来完成的。
在VTL里要想实现同样的功能你只需要将需要联合的reference放到一起就行了。例如：
#set ( $size = “Big” )
#set ( $name = “Ben” )
The clock is $size$name.
输出结果将是：The clock is BigBen.。更有趣的情况是：
#set ( $size = “Big” )
#set ( $name = “Ben” )
#set ( $clokc = “$size$name” )
The clock is $clock.
上例也会得到同样的结果。最后一个例子，当你希望混合固定字段到你的reference时，你需要使用标准格式：
#set ( $size = “Big” )
#set ( $name = “Ben” )
#set ( $clock = “${size}Tall$name” )
The clock is $clock.
输出结果是：The clock is BigTallBen.。使用这种格式主要是为了使得$size不被解释为$sizeTall。
Velocity 用户指南手册中文版（转）
[align=left]1. 关于[/align]
[align=left]Velocity 用户指南旨在帮助页面设计者和内容提供者了解Velocity 和其简单而又强大的脚本语言（Velocity Template Language (VTL)）。本指南中有很多示例展示了用Velocity来讲动态内容嵌入到网站之中，但是所有的VTL examples 都同演示用于所有的页面和模版。[/align]
[align=left]感谢选择Velocity![/align]
[align=left] [/align]
[align=left]2. 什么是Velocity?[/align]
[align=left]Velocity 是一个基于Java的模版引擎。它允许web 页面设计者引用JAVA代码预定义的方法。Web 设计者可以根据MVC模式和JAVA程序员并行工作，这意味着Web设计者可以单独专注于设计良好的站点，而程序员则可单独专注于编写底层代码。Velocity 将Java 代码从web页面中分离出来，使站点在长时间运行后仍然具有很好的可维护性，并提供了一个除JSP和PHP之外的可行的被选方案。[/align]
[align=left]Velocity可用来从模板产生web 页面，SQL, PostScript以及其他输出。他也可用于一个独立的程序以产生源代码和报告，或者作为其它系统的一个集成组件。这个项目完成后，Velocity将为Turbine web 应用程序框架提供模板服务。Velocity+Turbine 方案提供的模板服务将允许web 应用按真正的mvc模式进行开发。[/align]
[align=left] [/align]
[align=left]3. Velocity 可以做什么?[/align]
[align=left]3.1. Mud Store 示例[/align]
[align=left]假设你是一个专门销售泥浆（MUD）的在线商店的页面设计者。我们称他为"The Online Mud Store"。生意很好。客户订购各种各样的类型和数量的泥浆。他们使用他们的用户名和密码登陆到商店中来，就可以浏览他们的订货和购买其他东西。现在，赤土陶泥正在促销，这是一种很常用的泥巴。一少部分顾客很有规律的购买一种亮红土Bright Red Mud，这也是促销产品，但是不太常用，因此被移到页面的边缘。所有顾客的信息都在数据库中被跟踪，因此有一天问题出现了：为什么不使用Velocity来定位目标客户，这些客户对某种类型的产品特别感兴趣？[/align]
[align=left]Velocity 使针对访问者个性的WEB页面客户化（个性化）非常容易。作为一个在线泥巴商店的站点设计者，以想在客户以登陆进展点后就看到它们想看的页面。[/align]
[align=left]你遇到你公司的软件工程师，每个人都认为$customer 将保持当前登陆进入的客户信息，而$mudsOnSpecial 将士当前所有促销的泥巴。$flogger 对象包含有助于促销的方法。对于当前的任务，让我们仅关注这三个问题。记住，你不需要担心软件工程师如何从数据库中取得顾客信息，但你必须知道他们可以。这样可以使你专注于你的工作而软件工程师则忙于他们自己的工作。[/align]
[align=left]你可以在你的页面中嵌入如下的VTL语句：[/align]
[align=left] [/align]
[align=left]foreach语句的细节将进一步细说，但重要的是这个短小的脚本居然可以在你的站点上运行。当有一个倾向于亮红土的顾客登陆进来时，亮红土正在促销，这就是这个顾客所看到的，并且促销显示非常显著。如果另外一个长期购买赤陶土的顾客登陆进来，赤陶土促销的提示信息则应该在前面中间位置。Velocity是非常灵活的，受限的只是你的创造力。[/align]
[align=left]写在VTL参考文档中的是其他Velocity 元素，他们一起给你很强大的能力和灵活性以创建很好的站点。待你更加了解这些元素，就可以开始释放Velocity的强大动力。[/align]
[align=left]4. Velocity模板语言(VTL): 介绍[/align]
[align=left]Velocity模板语言(VTL)旨在为Web页面结合动态内容提供最容易、简单和简洁的方法。即使有一点或者没有编程经验的页面设计者也可以很快能为页面提供动态内容。[/align]
[align=left]VTL 使用引用（references）来将动态内容嵌入web页面，每个变量就是某一个类型的引用。变量实际上是一个可以调用定义在java代码中的内容的引用，或者它可以从页面内的VTL语句得出自身的值。下面是一个例子，说明可以嵌入到HTML文档中的VTL语句。[/align]
[align=left] [/align]
[align=left]这个VTL语句，就像所有的VTL语句一样，以#字符开始，并跟着一个指令set。当一个在线访问这请求页面时， Velocity 模伴引擎在页面内搜索所有#字符，然后决定是哪一个标记了VTL语句的开始，哪个标记不需要VTL做什么动作。[/align]
[align=left] [/align]
[align=left] #字符后面紧跟一个指令set.。set指令使用一个括在括号内的表达式---一个等式将一个值指派给一个变量。变量在等号的左边而值在等号的右边。[/align]
[align=left] [/align]
[align=left]在上面的示例中，变量是$a值是Velocity。这个变量就象其他引用一样，以一个$字符开始。值通常在引号之中，对Velocity来说一般没有类型冲突的问题，因为只有字符串 (基于文本的信息)可以传递给变量。[/align]
[align=left] [/align]
[align=left]下面的主要规则可能有助于理解Velocity 是如何工作的：引用以$开头用于取得什么东西，而指令以#开始用于做什么事情。[/align]
[align=left]在上面的例子中，#set用于将一个值指派给一个变量。而变量$a则可以用来在模板中输出"Velocity" 。[/align]
[align=left]5. Hello Velocity World![/align]
[align=left]一旦一个值被赋给一个变量，便可以在HTML中随处引用它。在下面的示例中，先给变量$foo赋值然后引用它。[/align]
[align=left] [/align]
[align=left]这个页面的结果是输出"Hello Velocity World!"。[/align]
[align=left]为了使包含VTL 指令的语句具有可读性，我们鼓励每个VTL语句在一个新行开始，虽然并不一定要这样做。set将随后深入解释。[/align]
[align=left] [/align]
[align=left]6. 注释[/align]
[align=left]可以用注释加入描述性文本，他们并不在模板引擎中输出。注释可以有助于你的记忆或者想其他人解释你的VTL语句正在做什么。[/align]
[align=left] [/align]
[align=left]单行注释以##开始，并在本行结束。如果需要加入多行注释，并不需要加入很多的单行注释。多行注释，以#*开始并以*#结束可以处理这种情况。[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]下面事一些例子说明单行注释和多行注释如何工作。[/align]
[align=left] [/align]
[align=left]还有第三种注释， VTL 注释块，可以用来存储诸如文档作者、版本信息等。[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]7. 引用[/align]
[align=left]VTL中有三种类型的引用：变量，属性和方法。作为使用VTL的设计者，你和你的工程师必须在饮用的特定命名上取得一致，以便在你的模板中正确的使用他们。[/align]
[align=left] [/align]
[align=left]有关引用的所有参数都处理为字符串对象。Everything coming to and from a reference is treated as a String object. 假如有一个对象表示$foo (比如说是整型对象)，Velocity 将调用其toString() 方法来将此对象转换为一个字符串。[/align]
[align=left]7.1. 变量Variables[/align]
[align=left]变量的简略标记是有一个前导"$"字符后跟一个 VTL 标识符（Identifier.）组成。一个VTL 标识符必须以一个字母开始(a .. z或 A .. Z)。剩下的字符将由以下类型的字符组成：[/align]
[align=left]字母 (a .. z, A .. Z) [/align]
[align=left]数字 (0 .. 9) [/align]
[align=left]连字符("-") [/align]
[align=left]下划线 ("_") [/align]
[align=left]下面是一些有效的变量引用:[/align]
[align=left] [/align]
[align=left]当VTL 引用一个变量时，比如$foo，变量可以从模板的set指令取得值，也可以从[/align]
[align=left] Java 代码中取得。例如，如果Java 变量$foo在模板被请求的时候具有值bar，则bar将替换页面中的所有$foo的实例。或者，如果包含下面的语句：[/align]
[align=left] [/align]
[align=left]紧跟指令后的所有$foo的实例的输出将会一样值。[/align]
[align=left]7.2. 属性[/align]
[align=left]
VTL引用的第二种元素是属性，而属性具有独特的格式。属性的简略标记识前导符$后跟一个VTL 标识符，在后跟一个点号(".")最后又是一个VTL 标识符。这是一些有效的示例：[/align]
[align=left] [/align]
[align=left]请看第一个例子，$customer.Address.。他有两种意思。它可以意味着，查询由customer标是的哈希表并按关键字Address返回值。但是$customer.Address也可能引用一个方法（下述，$customer.Address可能是$customer.getAddress().的缩写。当一个页面被请求时，Velocity 将决定这两种可能到底是哪一个，然后返回相应的值。[/align]
[align=left]7.3. 方法[/align]
[align=left]方法在JAVA代码中定义，并作一些有用的事情，比如运行一个计算器或者作出一个决定。方法是实际上也是引用，由前导符"$"后跟一个VTL 标识符，后跟一个VTL 方法体（Method Body）。 VTL 方法体由一个VTL 标识符后跟一个左括号，再跟可选的参数列表，最后是右括号。下面是一些有效的方法示例：[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]前面两个例子-- $customer.getAddress()和$purchase.getTotal() – 看起来有点象上面属性一节中所用的样子，$customer.Address和$purchase.Total.。如果你想这些例子在某些方面相关，那你就对了。[/align]
[align=left] [/align]
[align=left]VTL 属性可以为VTL方法用作简略标记。属性$customer.Address具有和方法$customer.getAddress() 完全一样的效果。属性和方法的主要不同点是方法中可以添加参数列表。[/align]
[align=left]简略标记可以用在下面的方法中：[/align]
[align=left] [/align]
[align=left]我们或许希望方法可以为我们放回属于太阳系的行星的名字，喂养我们的蚯蚓，或者从相册中返回一张照片。下面只有长的那个标记是可以工作的方法：[/align]
[align=left]7.4. 形式引用符Formal Reference Notation[/align]
[align=left]引用的简略符号如上所述，但是另外还有一种引用的形式符号，示例如下：[/align]
[align=left] [/align]
[align=left]在大多数情况下，我们将使用引用的简略符号，但在一些情况下，也需要拥戴哦形式引用符以便正确处理。[/align]
[align=left]假定你正在纸片上构件一个句子，将使用$vice作为句子中名词的词根。我们的目标是允许人们选择词根，然后产生以下两种结果之一：[/align]
[align=left]"Jack is a pyromaniac."[/align]
[align=left]或者 "Jack is a kleptomaniac."。[/align]
[align=left] 在这种情况下，使用简略符号是不太充分的。考虑到下面的例子：[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]这里有个不确定性， Velocity 假定 $vicemaniac，（而不是 $vice）是一个你想要使用的标识符。找不到$vicemaniac的值，他将返回$vicemaniac。使用形式符号便可解决这个问题：[/align]
[align=left]现在Velocity 知道$vice（而不是$vicemaniac）是一个引用。形式符号常用在饮用咋模板中和文本直接邻近的地方。[/align]
[align=left] [/align]
[align=left]7.5. 安静引用符Quiet Reference Notation[/align]
[align=left]当 Velocity 遇到一个位定义的引用时，其通常行为是输出这个引用的映像。比如，假设下面的引用出现在模板中的一部分：[/align]
[align=left] 当表单初次装入时，变量引用$email无值，你宁愿是一个空白域而不是具有值"$email"。使用安静引用符可以绕过Velocity的常规行为，在VTL中不用$email而是用$!email 符号。所以，上面的例子将会看起来像下面的样子：[/align]
[align=left]现在，当表单初次装入时， $email 仍然没有值，但是将输出空字符串而不是"$email"。[/align]
[align=left] [/align]
[align=left]形式和安静引用符可以一起使用，如下所示：[/align]
[align=center] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. 取得语义Getting literal[/align]
[align=left]VTL 特别的字符，比如$ 和 #，来做这个工作，因此在模板中使用这些自负的时候必须格外小心。本节讲述$ 的转义。[/align]
[align=left]1.1. 货币[/align]
[align=left]我们写下句子 "I bought a 4 lb. sack of potatoes at the farmer's market for only $2.50!" ，这并没有什么问题。但如前所述，VTL标识符总是以大写或是小写字母开始，所以$2.50 在引用中将不能出错。[/align]
[align=left]1.2. 转义有效的VTL 引用[/align]
[align=left]问题将会出现，因为Velocity 将有一个潜在的冲突。转义特殊字符是处理VTL模板种特殊字符的最好的办法，者可以用一个反斜线来进行。[/align]
[align=left] [/align]
[align=left]如果 Velocity 在VTL模板中遇到一个$email引用，他将在上下文中查找相应的值。这里，输出将是foo，因为 $email 是定义了的。如果$email 未定义，输出将是$email 。[/align]
[align=left] [/align]
[align=left]假设$email 是定义了的（比如，具有值foo)，但是你想输出 $email。可以有几种方法来做这个事情，不是最简单的是使用转义符。[/align]
[align=left] [/align]
[align=left]将输出是[/align]
[align=left] [/align]
[align=left]注意： / 绑定在$ 的左边。从做绑定原则使///$email 被解释为//$email。和上面例子比较下面的例子，这里$email 未定义。[/align]
[align=left]输出[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]注意，Velocity 处理定义和未定义的引用是不同的。下面一个set 指令将$foo 设为值gibbous.。[/align]
[align=left] [/align]
[align=left]输出将是$moon = gibbous [/align]
[align=left]-- 这里 $moon 作为字面输出，因为他并没有定义。而gibbous 将在$foo 的位置输出。[/align]
[align=left] [/align]
[align=left]我们也可以转义VTL 指令，这将在指令一节祥述。[/align]
[align=left] [/align]
[align=left]2. Case Substitution [/align]
[align=left]现在你大致了解了引用，可以在模板中使用它们了。Velocity 采用了很多JAVA原理的优点，模板设计人员会发现非常容易使用。例如：[/align]
[align=left]这个例子显示了引用的一些其他用法。Velocity 借鉴了Java的自省和组件bean特征，来解决引用名在上下文中作为对象和对象方法的问题。可以在你的模板的任何地方插入引用和求值。[/align]
[align=left]Velocity, 建模在Sun Microsystems定义的BEAN规范之上，是大小写敏感的；开发者努力捕捉和纠正可能出现的用户错误。当方法getFoo() 在模板中通过$bar.foo引用时，Velocity 首先尝试$getfoo。如果失败，他会再尝试 $getFoo。类似地，当一个模板引用到 $bar.Foo， Velocity 将尝试 $getFoo() 先，然后尝试 getfoo()。[/align]
[align=left]注意：模板中引用示例变量的问题仍然没有解决。只有引用等价于JavaBean的 getter/setter 方法解决了。(比如 $foo.Name 解决了到类 Foo的 getName() 示例方法的引用，但不能引用Foo的一个公共实例变量Name)。[/align]
[align=left]3. 指令[/align]
[align=left]因为指令（使用脚本来有效操控JAVA代码的输出）允许页面设计员真正专注于咱点的外观和内容设计，引用允许模板设计员为Web页面产生动态内容。[/align]
[align=left] [/align]
[align=left]3.1. #set [/align]
[align=left] #set 指令用来为引用设置相应的值。值可以被值派给变量引用或者是属性引用，而且赋值要在括号里括起来。[/align]
[align=left]赋值的左边必须是一个变量应用或者是属性引用。右边可以是下面的类型之一：[/align]
[align=left]变量引用[/align]
[align=left]字面字符串[/align]
[align=left]属性引用[/align]
[align=left]方法引用[/align]
[align=left]字面数字[/align]
[align=left]数组列表[/align]
[align=left] [/align]
[align=left]这些例子演示了上述的每种类型：[/align]
[align=left]注意：最后一个例子中，在方括号[..] 中定义的项目可以被ArrayList 类定义的方法访问。比如，你可以使用$monkey.Say.get(0)访问上述的第一个元素。[/align]
[align=left]右边也可以是一个简单的算术表达式:[/align]
[align=left]如果右边是一个属性或方法引用，取值是NULL，他将不会赋值给左边。通过这种机制将一个存在的引用从上下文中删除是不可能的。这对Velocity的新手可能会混淆。例如：[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]如果， $query.criteria("name") 放回字符串"bill"，而$query.criteria("address") 返回 null，上述VTL 将解释为：[/align]
[align=left]这往往会给那些想构建#foreach循环来试图通过属性和方法引用来设置一个引用的新手带来困惑，下面马上通过#if指令测试一下。例如：[/align]
[align=left]在上面的例子中，依靠$result 的去值来决定查询是否成功恐怕不是英明的做法。当$result 被#set设置后(添加到上下文中)，他就不能再被设值为null (从上下文中删除)。[/align]
[align=left] [/align]
[align=left]我们对此的解决方法是预设$result 为 false。然后如果 $query.criteria() 调用失败，你就可以检查之。[/align]
[align=left] [/align]
[align=left]不象其他Velocity 指令， #set 指令没有#end 语句。[/align]
[align=left]3.2. 字面字符串[/align]
[align=left]当使用#set 指令时，括在双引号中的字面字符串将解析和重新解释，如下所示：[/align]
[align=left]输出将会是：[/align]
[align=left] [/align]
[align=left]然而，当字面字符串括在单引号中时，他将不被解析：[/align]
[align=left] [/align]
[align=left]输出是：[/align]
[align=left]默认情况下，使用单引号来渲染未解析文本在Velocity是有效的。这种特征可以通过编辑velocity.properties 中的 stringliterals.interpolate=false来改变。[/align]
[align=left] [/align]
[align=left]3.3. 条件[/align]
[align=left]3.4. If / ElseIf / Else [/align]
[align=left] Velocity中的#if 指令允许在页面生成时，在IF条件为真的情况下包含文本。例如：[/align]
[align=left] [/align]
[align=left]变量 $foo 先求值，以决定是否为真。在这两种情况下为真： (i) $foo 是一个逻辑变量并具有真的值，或者 (ii) 值非空。要记住Velocity 上下文仅包括对象，所以当我们说“布尔”'boolean'时，他会被表示为“布尔类”(Boolean class)。这对即使是返回布尔类型的方法也是真的—自省架构将返回一个具有相同逻辑值的布尔类。[/align]
[align=left]如果求值为真时， #if 和 #end 语句之间的内容将输出。在这种情况下，如果 $foo 为真，输出将是"Velocity!"。相反，如果 $foo 具有一个null 值，或者逻辑假，语句求值为假，则没有输出。[/align]
[align=left]一个 #elseif 或者 #else 项可以用在#if 语句中。请注意， Velocity 模板引擎将在第一个为真的表达式时停止。下面的例子中，假设$foo 具有值15 而 $bar 等于 6。[/align]
[align=left] [/align]
[align=left]在这个例子中，$foo 大于10，所以前面两个比较失败。接下来比较$bar 和6，结果为真，所以输出为Go South。[/align]
[align=left]请注意在现在， Velocity的数值比较约束为整型—其他类型都将求值为false。仅有一个例外是等于'=='，这时Velocity 要求等号两边的对象具有相同的类型。[/align]
[align=left]3.5. 关系和逻辑操作符[/align]
[align=left]Velocity 使用等式操作符来决定两个变量间的关系。这里是一个简单的例子演示如何使用等式操作符：[/align]
[align=left]Velocity 也具有逻辑AND, or 和 NOT 操作符。更进一步的信息，请看VTL参考手册VTL Reference Guide 。下面是一些演示如何使用逻辑操作符的例子：[/align]
[align=left]例子中#if() 指令仅在$foo 和$bar 斗为真的时候才为真。如果$foo 为假，则表达式也为假；并且 $bar 将不被求值。如果 $foo 为真，Velocity 模板引擎将继续检查$bar;的值，如果 $bar 为真，则整个表达式为真。并且输出This AND that 。如果 $bar 为假，将没有输出因为整个表达式为假。[/align]
[align=left]逻辑OR 的工作方式相同，唯一的例外是其中一个表达式要被求值，以便决定整个表达式是否为真。请看下面的例子：[/align]
[align=left] [/align]
[align=left]如果 $foo 为真，Velocity 模板引擎就不需要去察看$bar 的值，不管 $bar 是否为真，真个表达式都为真，因此输出This or That 。如果 $foo 为假，$bar 就必须检查其值了。在这种情况下，如果$bar 也是为假，表达式将为假，没有任何输出。当然，如果$bar 为真，则真个表达式为真，输出This or That。[/align]
[align=left]对于逻辑NOT 操作符，只有一个操作数：[/align]
[align=left]这里，如果$foo 为真，!$foo 求值为假，没有输出。如果$foo 为假，!$foo 求值为真，输出NOT that 。请当心，不要和安静引用quiet reference $!foo 混淆它们是完全不同的。[/align]
[align=center] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. 循环[/align]
[align=left]1.1. Foreach 循环[/align]
[align=left] #foreach 元素允许进行循环，例如：[/align]
[align=left]这个#foreach 循环将导致$allProducts 列表 (对象) 为查询所有的产品$products (目标)遍历一遍。每次经过循环，从$allProducts 取得的值将置于$product 变量之中。[/align]
[align=left]$allProducts 变量的内容是一个矢量，一个哈希表或者数组。赋给$product 变量的值是一个Java 对象并且可以从一个类似的变量引用。例如，如果 $product 真是一个Java的产品类，其名称可以通过引用$product.Name 方法来检索(即: $Product.getName())。[/align]
[align=left] [/align]
[align=left]我们假定 $allProducts 是一个哈希表。如果你想检索关键字的值或者在哈希表中的对象，你可以使用以下的代码：[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]Velocity 提供一个更容易的方式或的循环计数，以便你可以做下面类似的工作：[/align]
[align=left] [/align]
[align=left]循环计数变量的缺省名称是$velocityCount，在velocity.properties 配置文件中标明。默认情况下，该变量从1开始计数，但是可以在velocity.properties 文件中设为从0或者1开始。下面是velocity.properties 文件中循环变量设置一节: [/align]
[align=left] [/align]
[align=left]2. 包含[/align]
[align=left]#include 脚本元素允许模板设计人员包含（导入）本地文件，这个文件将插入到#include 指令被定义的地方。文件的内容并不通过模板引擎来渲染。处于安全的原因，被包含的文件只可以放在TEMPLATE_ROOT下。[/align]
[align=left] [/align]
[align=left] #include 指令引用的文件在双引号内。如果超过一个文件，其间用逗号隔开。[/align]
[align=left] [/align]
[align=left]被包含的文件并不是一定要用文件名来引用，事实上，最好的办法是使用变量而不是文件名。这在根据规则决定何时提交页面时，决定目标输出是很有用的。[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]3. 解析[/align]
[align=left] #parse 脚本元素允许页面设计员导入包含VTL的本地文件。 Velocity将解析和渲染指定的模板。[/align]
[align=left] [/align]
[align=left]就象 #include 指令，#parse 可以使用变量而不是一个实在的模板文件。#parse 引用的模板文件必须包含的TEMPLATE_ROOT指定的目录之下。和 #include 指令不一样， #parse 只有一个参数。[/align]
[align=left]VTL 模板templates can have #parse statements referring to templates that in turn have #parse statements. By default set to 10, the parse_directive.maxdepth line of the velocity.properties allows users to customize maximum number of #parse referrals that can occur from a single template. (Note: If the parse_directive.maxdepth property is absent from the velocity.properties file, Velocity will set this default to 10.) Recursion is permitted, for example, if the template dofoo.vm contains the following lines: [/align]
[align=left] [/align]
[align=left]It would reference the template parsefoo.vm, which might contain the following VTL: [/align]
[align=left] [/align]
[align=left]After "Count down." is displayed, Velocity passes through parsefoo.vm, counting down from 8. When the count reaches 0, it will display the "All done with parsefoo.vm!" message. At this point, Velocity will return to dofoo.vm and output the "All done with dofoo.vm!" message.[/align]
[align=left] [/align]
[align=left]4. 停止[/align]
[align=left] [/align]
[align=left] #stop 脚本允许模板设计员停止模板引擎的执行，并返回。这通常用作调试。[/align]
[align=center] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. 宏[/align]
[align=left]#macro 脚本元素允许模板设计者在VTL 模板中定义重复的段。 Velocimacros 不管是在复杂还是简单的场合都非常有用。下面这个Velocimacro，仅用来节省击键和减少排版错误，介绍了一些Velocity宏的概念。[/align]
[align=left] [/align]
[align=left]在例子中，Velocimacro定义为d，它可以象调用其他VTL指令一样的形式来进行调用：[/align]
[align=left] [/align]
[align=left]当这个模板被调用时， Velocity 将 #d() 替换为一个单行的空表格。[/align]
[align=left] [/align]
[align=left]Velocimacro 可以带一些参数，也可以不带参数（如上例所示）。但在他被调用时，所带的参数必须和其定义时的参数一样。很多Velocimacros 定义为不止一个参数。下面这个宏带有两个参数，一个颜色，一个数组。[/align]
[align=left] [/align]
[align=left]在这个例子中定义的Velocimacro，名为tablerows, 要求两个参数。第一个参数代替$color, 第二个代替$somelist。[/align]
[align=left]可以写进VTL 模板中的东西都可以写进Velocimacro 的主体部分。tablerows 宏其实是一个foreach 语句。在#tablerows 宏的定义中有两个#ende语句，第一个属于#foreach, 第二个结束宏定义。[/align]
[align=left] [/align]
[align=left]请注意$greatlakes 替换了$somelist。这样，当#tablerows 宏被调用时，将产生以下输出：[/align]
[align=left] [/align]
[align=left]Velocimacros 在Velocity 模板语句内定义，这意味着它在同一站点内的其他Velocity 模板中并不有效。定义一个宏，并使其与其他模板共享很具有明显的优点：他减少了在大量的模板内重复定义宏的工作，并减少了出错的机会，并确保对其他宏的改变对其他所有模板有效。[/align]
[align=left]但如果 #tablerows($color $list) 宏是在一个Velocimacros 模板库内定义的，它就可以被其他常规模板所用。当然，它可以用于各种目的，也可重用多次。在表示所有真菌类（fungi）的mushroom.vm 模板中，#tablerows 宏可以被用来列出典型的蘑菇。[/align]
[align=left] [/align]
[align=left]我们对mushroom.vm执行请求，Velocity 将在模板库内找到#tablerows 宏 (在velocity.properties 文件中定义)并产生以下输出：[/align]
[align=left] [/align]
[align=left]Velocimacro 参数[/align]
[align=left]Velocimacros 的参数可以是以下的VTL元素：[/align]
[align=left]引用（Reference）: 以 '$' 打头的元素[/align]
[align=left]字面字符串（String literal） : 比如"$foo" 或 'hello' [/align]
[align=left]字面数字: 1, 2 …. [/align]
[align=left]整数范围: [ 1..2] 或 [$foo .. $bar] [/align]
[align=left]对象数组: [ "a", "b", "c"] [/align]
[align=left]布尔真[/align]
[align=left]布尔假[/align]
[align=left] [/align]
[align=left]当把引用作为参数传递给Velocimacros时，请注意引用是按“名字”传递的。这意味着他们的值在每次使用他们的Velocimacro中产生。这个特性允许你在方法调用是传递引用，并在每次使用时进行方法调用。例如，Fo，当调用下面的Velocimacro 时，[/align]
[align=left] [/align]
[align=left]结果是，在方法bar() 中，引用 $foo 被调用了3次。[/align]
[align=left]咋看时，这个特征让人吃惊，当当你考虑一下Velocimacros的原本动机 – 在VTL模板中避免很多“剪切复制”操作—你就会明白。它允许你将无状态对象，比如在一个颜色表格行内重复产生一些颜色次序的对象，传递给Velocimacro。[/align]
[align=left]如果你需要使用这个特征，你通常可以从方法内取得一个值，作为一个新的引用传递给宏：[/align]
[align=left] [/align]
[align=left]Velocimacro 属性[/align]
[align=left]在velocity.properties 文件中有数行定义可以用来灵活实现Velocimacros。详细情况请参见开发指南（Developer Guide）。[/align]
[align=left]velocimacro.library –是一个逗号分隔的所有Velocimacro 模板库的列表。默认情况下， Velocity 搜寻一个单一的库VM_global_library.vm.。预先配置的模板路径用来查找Velocimacro 库。[/align]
[align=left] [/align]
[align=left]velocimacro.permissions.allow.inline –这个属性决定Velocimacros 是否可以在常规模板内定义，取值为逻辑True或者False。默认情况下，设置为true，允许设计者在产规模板内定义宏。[/align]
[align=left]velocimacro.permissions.allow.inline.to.replace.global –逻辑true 或者false，允许标明是否允许在常规模板内定义的Velocimacro 代替在模板库中定义并通过velocimacro.library属性在启动时装入的全局宏。默认设置为false。[/align]
[align=left]velocimacro.permissions.allow.inline.local.scope –逻辑true 或者false，默认值为false。控制是否在模板内定义的Velocimacros 仅在定义它的模板内可见。换句话说，如果设置为true，一个模板可以定义仅能被他所用的宏。你可以用它来做一些漂亮的宏，如果一个全局调用另一个全局宏，在局部（inline）范围内，当被一个模板调用时，该模板可以定义一个被第一个全局宏调用的第二个全局宏的私有实现。其他所有模板都不受影响。[/align]
[align=left] [/align]
[align=left]velocimacro.context.localscope –逻辑值true 或者 false，缺省值为false。但设置为true时，所有在Velocimacro 内通过 #set() 进行的修改都将被视为Velocimacro 的本地行为，不会影响到其上下文。[/align]
[align=left]velocimacro.library.autoreload –此属性控制Velocimacro 库的自动载入。缺省值为false。如果设置为true，被调用的Velocimacro得源库将被检查是否改变，并在必要是重新载入。这将使你可以改变和测试Velocimacro 库，而不必重新启动应用服务器或者servlet容器，就象你工作在常规模板一样。这个模时仅在资源载入器的缓存模时被关闭的情况下有效 (如 file.resource.loader.cache = false )。此特征为开发时设计，不要在生产模式时使用。[/align]
[align=left]Velocimacro Trivia [/align]
[align=left]当前， Velocimacros 在其首次在模版中使用前必须首先定义它。这意味着， #macro() 宣称应该在使用Velocimacros之前。[/align]
[align=left]如果你想#parse() 一个包含#macro() 指令的模板，记住这个非常重要。因为#parse() 在运行时发生，解析器在解析时要决定是否模版中一个看起来像VM的元素真是VM，所以解析一系列VM 宣称可能并不能如愿地工作的很好。为避免如此，可以简单地使用velocimacro.library 的办法，使Velocity 在启动时载入VM。[/align]
[align=left] [/align]
[align=left]2. 转义 VTL 指令[/align]
[align=left]VTL 可以通过反斜杠("/")来进行转义，directives can be escaped with the backslash character in a manner similar to valid VTL references. [/align]
[align=left] [/align]
[align=left]在转义在一个单一指令内包含多个脚本元素（比如f-else-end语句）的指令时应多加小心。下面是一个典型的VTL if语句；[/align]
[align=left] [/align]
[align=left]如果 $jazz为 true，输出是[/align]
[align=left] [/align]
[align=left]如果 $jazz 为false，将没有输出。转义脚本元素将改变输出。考虑下面的情况；[/align]
[align=left] [/align]
[align=left]不管 $jazz 是真或假，输出都是[/align]
[align=left] [/align]
[align=left]事实上，因为所有脚本元素都被转义了， $jazz 永远不会被求值。将设反斜杠在被合法转义的脚本元素之前[/align]
[align=left] [/align]
[align=left]这时，如果$jazz 为真，输出是[/align]
[align=left] [/align]
[align=left]为理解这个情况，请注意在一个新行结束是将在输出中忽略新的一行。因此，经过#if()前的'//' 加工后，#if()块紧跟第一个'/'。最后一个/位于新的一行，因为在'Ganelin'后又一个新行，所以，最后的那个位于#end 之前的//是语句块的一部分。[/align]
[align=left]如果 $jazz 为false，这里将没有输出。注意，在开始破坏了if语句的情况将不能被正确转义：[/align]
[align=left] [/align]
[align=left]这里，#if 被转义，但有一个#end 被保留了；所以有多个结束语句将导致解析错误。[/align]
[align=center] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. VTL: 格式化[/align]
[align=left]虽然在本指南中的VTL经常显示在新行中或者有空格，但是下面的VTL [/align]
[align=left] [/align]
[align=left]和下面的写法同样有效。[/align]
[align=left] [/align]
[align=left]Velocity的行为并不受空格的影响，前述的指令也可以写成：[/align]
[align=left] [/align]
[align=left]或者[/align]
[align=left] [/align]
[align=left]上面每种写法结果都一样。[/align]
[align=left]2. 其它特征和杂项[/align]
[align=left]2.1. 数学特征[/align]
[align=left]Velocity 有一些内建的数学功能，可以使用set指令用在模版中。下面的共识分别演示了加减乘除运算：[/align]
[align=left] [/align]
[align=left]当进行除法运算时，结果将会是整数。When a division operation is performed, the result will be an integer. 余数则可以通过模(%)运算获得。[/align]
[align=left] [/align]
[align=left]在Velocity 中，只有整数可以进行数学运算；如果执行非整数的数学运算，将被记录下来，并返回null 。[/align]
[align=left]2.2. 范围操作符[/align]
[align=left]范围操作符可以和#set 和#foreach 语句一起使用。有助于产生一个整数的目标数组，范围操作符有以下的结构：[/align]
[align=left]
[/align]
[align=left] [/align]
[align=left]n 和 m 都必须是整数或者可以产生整数。不管 m 大于或者小于n 都没关系；在m小于n这种情况下，范围可以向下计数。下面是使用范围操作符的例子：[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]他们分别产生一下输出[/align]
[align=left] [/align]
[align=left]范围操作符和#set 和#foreach 指令一起使用时，只是产生数组。[/align]
[align=left]页面设计人员在设计具有相同尺寸的表格时，有时没有足够的数据来填充，他们会发现范围操作符非常有用。[/align]
[align=left]2.3. 进阶：转义和! [/align]
[align=left]当一个引用被! 字符处于静寂模式，并且! 字符在转义符/ 前出现，应用将用一种特别的方式处理。请注意他和常规转义的不同，下面这种情况/ 先于! 出现: [/align]
[align=left] [/align]
[align=left]这样将被加工成[/align]
[align=left] [/align]
[align=left] [/align]
[align=left]对比常规转义，/先于 $: [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]这是结果是：[/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]3. Velocimacro 杂记[/align]
[align=left]本节是关于Velocimacros的一个小型FAQ。本届内容会不时更新，所以请常来检查新的内容，[/align]
[align=left]注 : 本节中， 'Velocimacro' 将简写为'VM'。[/align]
[align=left] [/align]
[align=left]Q:是否可以使用指令directive 或者 VM 作为另一个VM的参数? 例如: #center( #bold("hello") ) [/align]
[align=left]A: 不行。指令不能用作指令的参数，而大多数情况下，作为实际的应用，VM就是指令。[/align]
[align=left]不过也有一些办法。一个简单的做法是使用双引号来加工你的内容。所以，你可以这样：[/align]
[align=left] [/align]
[align=left]甚至可以节省一个步骤：[/align]
[align=left] [/align]
[align=left]请注意，后面这个例子中，参数是在VM内部被求值，不是在调用的那一层次上。换句话说，被传入的VM的参数是整个被传入的，并且在传入的VM内部被求值。所以我们可以这样做：[/align]
[align=left] [/align]
[align=left]这里，输入将会是：[/align]
[align=left] [/align]
[align=left]因为"#inner($bar)" 的求值发生在#outer()内部，所以在#outer() 内设置的$bar得值会是其使用的值。[/align]
[align=left]这是一个有意的保护特征—参数按名称传递给VM，所以可以将象状态引用的东西传给VM ，比如：[/align]
[align=left] [/align]
[align=left]rowColor() 被重复调用而不是一次。为避免如此，可以调用VM外部的方法，然后将值传递给VM. [/align]
[align=left] [/align]
[align=left]Q:是否可以通过#parse()注册VM ? [/align]
[align=left]A：当前， Velocimacros 在其首次在模版中使用前必须首先定义它。这意味着， #macro() 宣称应该在使用Velocimacros之前。[/align]
[align=left]如果你想#parse() 一个包含#macro() 指令的模板，记住这个非常重要。因为#parse() 在运行时发生，解析器在解析时要决定是否模版中一个看起来像VM的元素真是VM，所以解析一系列VM 宣称可能并不能如愿地工作的很好。为避免如此，可以简单地使用velocimacro.library 的办法，使Velocity 在启动时载入VM。[/align]
[align=left] [/align]
[align=left]Q. 什么是VM自动载入（Velocimacro Autoreloading）? [/align]
[align=left]A. 这是一个属性，在开发时使用，而不时运行时：[/align]
[align=left] velocimacro.library.autoreload [/align]
[align=left]默认值为false。当设置为true时，连同<type>.resource.loader.cache 属性设置为false（这里<type> 是使用的资源载入器的名称，比如'file') ，Velocity 引擎在你创建VM库文件是将自动载入其改变，这样你就不必将其导入servlet 引擎（或者应用程序）中，或者用其他手段来使其自动重新载入。[/align]
[align=left] [/align]
[align=left]下面是一个简单的设置配置组合：[/align]
[align=left] [/align]
[align=left]注意在生产状态（运行时）不要使其打开。[/align]
[align=left] [/align]
[align=left]4. 字符串联[/align]
[align=left]开发者常问的一个问题是“我如何进行字符串串联？”是否有类似于JAVA中的'+'操作符？[/align]
[align=left]为了串联VTL中的引用，你不得不将它们“放在一起”。而你想要放置在一起的上下文很重要，下面举例说明。[/align]
[align=left]在常规“笨办法”模板中：[/align]
[align=left] 输出将会是：'The clock is BigBen’。我们来看更有趣的事情，比如，当你想串联一个字符串并传递给一个方法，或者设置一个新的引用，可以这样：[/align]
[align=left] [/align]
[align=left]结果是一样的。作为最后一个例子，当你想混合“静态”字符串到引用中，你可能需要使用“形式引用”：[/align]
[align=left] [/align]
当Velocity应用于web开发时，界面设计人员可以和java程序开发人员同步开发一个遵循MVC架构的web站点，也就是说，页面设计人员可以只关注页面的显示效果，而由java程序开发人员关注业务逻辑编码。Velocity将java代码从web页面中分离出来，这样为web站点的长期维护提供了便利，同时也为我们在JSP和PHP之外又提供了一种可选的方案。
Velocity的能力远不止web站点开发这个领域，例如，它可以从模板（template）产生SQL和PostScript、XML，它也可以被当作一个独立工具来产生源代码和报告，或者作为其他系统的集成组件使用。Velocity也可以为Turbine web开发架构提供模板服务（template service）。Velocity+Turbine提供一个模板服务的方式允许一个web应用以一个真正的MVC模型进行开发。
２、Velocity能为我们作什么？
The Mud Store Example
假设你是一家专门出售Mud的在线商店的页面设计人员，让我们暂且称它为“在线MUD商店”。你们的业务很旺，客户下了各种类型和数量的mud订单。他们都是通过输入用户名和密码后才登陆到你的网站，登陆后就允许他们查看订单并购买更多的mud。现在，一种非常流行的mud正在打折销售。另外有一些客户规律性的购买另外一种也在打折但是不是很流行的Bright Red Mud，由于购买的人并不多所以它被安置在页面的边缘。所有用户的信息都是被跟踪并存放于数据库中的，所以某天有一个问题可能会冒出来：为什么不使用velocity来使用户更好的浏览他们感兴趣的商品呢？
Velocity使得web页面的客户化工作非常容易。作为一个web site的设计人员，你希望每个用户登陆时都拥有自己的页面。
你会见了一些公司内的软件工程师，你发现他们每个人都同意客户应该拥有具有个性化的信息。那让我们把软件工程师应该作的事情发在一边，看一看你应该作些什么吧。
你可能在页面内嵌套如下的VTL声明：
<html>
<body>
Hello $customer.Name!
<table>
#foreach( $mud in $nudsOnSpecial )
#if ( $customer.hasPurchased( $mud ) )
<tr><td>$flogger.getPromo( $mud )</td></tr>
#end
#end
</table>
一、Velocity Template Language(VTL):AN introductionVTL意味着提供最简单、最容易并且最整洁的方式合并页面动态内容。
VTL使用references来在web site内嵌套动态内容，一个变量就是一种类型的reference。变量是某种类型的refreence，它可以指向java代码中的定义，或者从当前页面内定义的VTL statement得到值。下面是一个VTL statement的例子，它可以被嵌套到HTML代码中：
#set ( $a = “Velocity” )
和所有的VTL statement一样，这个statement以＃字符开始并且包含一个directive：set。当一个在线用户请求你的页面时，Velocity Templating Engine将查询整个页面以便发现所有＃字符，然后确定哪些是VTL statement，哪些不需要VTL作任何事情。
＃字符后紧跟一个directive：set时，这个set directive使用一个表达式（使用括号封闭）――一个方程式分配一个值给变量。变量被列在左边，而它的值被列在右边，最后他们之间使用＝号分割。
在上面的例子中，变量是$a，而它的值是Velocity。和其他的references一样以$字符开始，而值总是以双引号封闭。Velocity中仅有String可以被赋值给变量。
记住以下的规则：
使用$字符开始的references用于得到什么；使用#字符开始的directives用于作些什么。
Hello Velocity World!
一旦某个变量被分配了一个值，那么你就可以在HTML文件的任何地方引用它。在下面的例子中，一个值被分配给$foo变量，并在其后被引用。
<html>
<body>
#set ( $foo = “Velocity” )
Hello $foo World!
</body>
</html>
上面的实现结果是在页面上打印“Hello Velocity World！”
为了使包含VTL directives的statement更具有可读性，我们鼓励你在新行开始每个VTL statement，尽管你不是必须这么作。Set directive将在后面详细描述。
二、注释
1.单行注释：
## This is a single line comment.
2.多行注释：
#*
Thus begins a multi-line comment. Online visitors won’t
see this text because the Velocity Templating Engine will
ignore it.
*#
3.文档格式：
#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
information:
@version 5
@author
*#
三、References在VTL中有三种类型的references：变量(variables)、属性(properties)、方法(methods)。
作为一个使用VTL的页面设计者，你和你的工程师必须就references的名称达成共识，以便你可以在你的template中使用它们。
Everything coming to and from a reference被作为一个String对象处理。如果有一个对象$foo是一个Integer对象，那么Velocity将调用它的toString()方法将这个对象转型为String类型。
1.变量
格式要求同java。
2.属性
例子：
$customer.Address
$purchase.Total
$customer.Address有两种含义。它可以表示：查找hashtable对象customer中以Address为关键字的值；也可以表示调用customer对象的getAddress()方法。当你的页面被请求时，Velocity将确定以上两种方式选用那种，然后返回适当的值。
3.方法
一个方法就是被定义在java中的一段代码，并且它有完成某些有用工作的能力，例如一个执行计算和判断条件是否成立、满足等。方法是一个由$开始并跟随VTL标识符组成的References，一般还包括一个VTL方法体。例如：
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( “My Home Page” )
$person.setAttributes( [“Strange”, “Weird”, “Excited”] )
前两个例子$customer.getAddress()和$purchase.getTotal()看起来挺想上面的属性$customer.Address 和 $purchase.Total。如果你觉得他们之间有某种联系的话，那你是正确的。
VTL属性可以作为VTL方法的缩写。$customer.Address属性和使用$customer.getAddress()方法具有相同的效果。如果可能的话使用属性的方式是比较合理的。属性和方法的不同点在于你能够给一个方法指定一个参数列表。
4.正式reference标记
reference的正是格式如下：
${mudSlinger} 变量
${customer.Address} 属性
${purchase.getTotal()} 方法
非正是格式更见常用，但是有时还是使用正是格式比较适合。例如：你希望通过一个变量$vice来动态的组织一个字符串。
Jack is a $vicemaniac.
本来变量是$vice现在却变成了$vicemaniac，这样Veloctiy就不知道您到底要什么了。所以，应该使用正是格式书写
Jack is a ${vice}maniac
现在Velocity知道变量是$vice而不是$vicemaniac。
5.Quiet reference notation 例如：
<input type=”text” name=”email” value=”$email” />
当页面的form被初始加载时，变量$email还没有值，这时你肯定是希望它能够显示一个blank text来代替输出”$email”这样的字段。那么使用quiet reference notation就比较合适。
<input type=”text” name=”email” value=”$!email”/>
这样文本框的初始值就不会是email而是空值了。
正式和quiet格式的reference notation也可一同使用，像下面这样：
<input type=”text” name=”email” value=”$!{email}”/>
Getting literal
Velocity使用特殊字符$和#来帮助它工作，所以如果要在template里使用这些特殊字符要格外小心。本节将讨论$字符。
6.货币字符
在VTL中使用$2.5这样的货币标识是没有问题得的，VTL不会将它错认为是一个reference，因为VTL中的reference总是以一个大写或者小写的字母开始。
Escaping valid VTL reference
VTL中使用“/”作为逃逸符。
例如：
#set( $email = “foo” )
将render为：
foo
/foo
如果email变量没有被定义则
将被render为：
注意：VTL中未被定义的变量将被认为是一个字符串，所以以下例子：
#set( $foo = “gibbous” )
$moon = $foo
的输出结果是：
$moon = gibbous
7.Case substitution现在你已经对reference比较熟悉了，你可以将他们高效的应用于你的template了。Velocity利用了很多java规范以方便了设计人员的使用。例如：
$foo
$foo.getBar()
## is the same as
$foo.Bar
$data.getUser(“jon”)
## is the same as
$data.User(“jon”)
$data.getRequest().getServerName()
# is the same as
$data.Request.ServerName
## is the same as
${data.Request.ServerName}
但是，注意VTL中不会将reference解释为对象的实例变量。例如：$foo.Name将被解释为Foo对象的getName（）方法，而不是Foo对象的Name实例变量。
四、Directives
Reference允许设计者使用动态的内容，而directive使得你可以应用java代码来控制你的显示逻辑，从而达到你所期望的显示效果。
1. #set
#set directive被用于设置一个reference的值。例如：
#set ( $primate = “monkey” )
#set ( $customer.Behavior = $primate )
赋值左侧的（LHS）必须是一个变量或者属性reference。右侧（RHS）可以是以下类型中一种：
a. 变量reference
b. String literal
c. 属性reference
d. 方法reference
e. number literal
f. ArrayList
下面是应用各种类型的RHS的例子：
＃set ( $monkey = $bill ) ##变量reference
＃set ( $monkey.Friend = “monica” ) ##String literal
＃set ( $monkey.Blame = $whitehouse.Leak )##属性reference
＃set ( $monkey.Plan = $spindoctor.weave($web) )##方法reference
＃set ( $monkey.Number = 123 )##Number literal
＃set ( $monkey.Say = [“Not”, $my, “fault”] )##ArrayList
注意：最后一个例子的取值方法为：$monkey.Say.get(0)
RHS也可以是一个简单的算术表达式：
#set ( $value = $foo + 1 )
#set ( $value = $bar -1 )
#set ( $value = $foo * $bar )
#set ( $value = $foo / $bar )
如果你的RHS是一个null，VTL的处理将比较特殊：它将指向一个已经存在的reference，这对初学者来讲可能是比较费解的。例如：
#set ( $resut = $query.criteria(“name”) )
The result of the first query is $result
#set ( $resut = $query.criteria(“address”) )
The result of the second query is $result
如果$query.criteria(“name”)返回一个“bill”，而$query.criteria(“address”)返回的是null，则显示的结果如下：
The result of the first query is bill
The result of the first query is bill
看看下面的例子：
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
在上面的例子中，程序将不能智能的根据$result的值决定查询是否成功。在$result被#set后（added to the context），它不能被设置回null（removed from the context）。打印的结果将显示两次查询结果都成功了，但是实际上有一个查询是失败的。
为了解决以上问题我们可以通过预先定义的方式：
#set( $criteria = [“name”, “address”] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria( $criterion ) )
#if( $result )
Query was successful
#end
#end
String Literals
当你使用#set directive，String literal封闭在一对双引号内。
#set ( $directoryRoot = “www” )
#set ( $templateName = “index.vm” )
#set ( $template = “$directoryRoot/$tempateName” )
$template
上面这段代码的输出结果为：www/index.vm
但是，当string literal被封装在单引号内时，它将不被解析：
#set ( $foo = “bar” )
$foo
#set ( $blargh = ‘$foo’ )
结果：
bar
$foo
上面这个特性可以通过修改velocity.properties文件的stringliterals.interpolate = false的值来改变上面的特性是否有效。
2.条件语句 if/elseif/else 当一个web页面被生成时使用Velocity的#if directrive，如果条件成立的话可以在页面内嵌入文字。例如：
#if ( $foo )
<strong>Velocity!</strong>
#end
上例中的条件语句将在以下两种条件下成立：
l $foo是一个boolean型的变量，且它的值为true
l $foo变量的值不为null
这里需要注意一点：Velocity context仅仅能够包含对象，所以当我们说“boolean”时实际上代表的时一个Boolean对象。即便某个方法返回的是一个boolean值，Velocity也会利用内省机制将它转换为一个Boolean的相同值。
如果条件成立，那么#if和#end之间的内容将被显示。
#elseif和#else元素可以同#if一同使用。例如：
#if( $foo < 10 )
<strong> Go North </strong>
#elseif( $foo == 10 )
<strong> Go East </strong>
#elseif( $foo == 6 )
<strong> Go South </strong>
#else
<strong> Go West </strong>
#end
注意这里的Velocity的数字是作为Integer来比较的――其他类型的对象将使得条件为false，但是与java不同它使用“＝＝”来比较两个值，而且velocity要求等号两边的值类型相同。
关系、逻辑运算符
Velocity中使用等号操作符判断两个变量的关系。例如：
#set ( $foo = “deoxyribonucleic acid” )
#set ( $bar = “ribonucleic acid” )
#if ( $foo == $foo )
In this case it’s clear they aren’t equivalent.So…
#else
They are not equivalent and this will be the output.
#end
3.Velocity有AND、OR和NOT逻辑运算符。
下面是一些例子：
## logical AND
#if( $foo && $bar )
<strong> This AND that </strong>
#end
## logical OR
#if ( $foo || $bar )
<strong>This OR That </strong>
#end
##logical NOT
#if ( !$foo )
<strong> NOT that </strong>
#end
[b]4.[/b]循环 ：Foreach循环
例子：
<ul>
#foreach ( $product in $allProducts )
<li> $product </li>
#end
</ul>
每次循环$allProducts中的一个值都会赋给$product变量。
$allProducts可以是一个Vector、Hashtable或者Array。分配给$product的值是一个java对象，并且可以通过变量被引用。例如：如果$product是一个java的Product类，并且这个产品的名字可以通过调用他的getName（）方法得到。
现在我们假设$allProducts是一个Hashtable，如果你希望得到它的key应该像下面这样：
<ul>
#foreach ( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key) </li>
#end
</ul>
Velocity还特别提供了得到循环次数的方法，以便你可以像下面这样作：
<table>
#foreach ( $customer in $customerList )
<tr><td>$velocityCount</td><td>$customer.Name</td></tr>
#end
</table>
$velocityCount变量的名字是Velocity默认的名字，你也可以通过修改velocity.properties文件来改变它。默认情况下，计数从“1”开始，但是你可以在velocity.properties设置它是从“1”还是从“0”开始。下面就是文件中的配置：
# Default name of loop counter
# variable reference
directive.foreach.counter.name = velocityCount
# Default starting value of the loop
# counter variable reference
directive.foreach.counter.initial.value = 1
5.include
#include script element允许模板设计者引入本地文件。被引入文件的内容将不会通过模板引擎被render。为了安全的原因，被引入的本地文件只能在TEMPLATE_ROOT目录下。
#inclued ( “one.txt” )
如果您需要引入多个文件，可以用逗号分隔就行：
#include ( “one.gif”, “two.txt”, “three.htm” )
在括号内可以是文件名，但是更多的时候是使用变量的：
#inclue ( “greetings.txt”, $seasonalstock )
6.parse
#parse script element允许模板设计者一个包含VTL的本地文件。Velocity将解析其中的VTL并render模板。
#parse( “me.vm” )
就像#include，#parse接受一个变量而不是一个模板。任何由#parse指向的模板都必须包含在TEMPLATE_ROOT目录下。与#include不同的是，#parse只能指定单个对象。
你可以通过修改velocity.properties文件的parse_direcive.maxdepth的值来控制一个template可以包含的最多#parse的个数――默认值是10。#parse是可以递归调用的，例如：如果dofoo.vm包含如下行：
Count down.
#set ( $count = 8 )
#parse ( “parsefoo.vm” )
All done with dofoo.vm!
那么在parsefoo.vm模板中，你可以包含如下VTL：
$count
#set ( $count = $count – 1 )
#if ( $count > 0 )
#parse( “parsefoo.vm” )
#else
All done with parsefoo.vm!
#end
的显示结果为：
Count down.
8
7
6
5
4
3
2
1
0
All done with parsefoo.vm!
All done with dofoo.vm!
7.Stop
#stop script element允许模板设计者停止执行模板引擎并返回。把它应用于debug是很有帮助的。
#stop
8.Velocimacros
#macro script element允许模板设计者定义一段可重用的VTL template。例如：
#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
调用#tablerows Velocimacro：
#set ( $greatlakes = [ “Superior”, “Michigan”, “Huron”, “Erie”, “Ontario” ] )
#set ( $color = “blue” )
<table>
#tablerows( $color $greatlakes )
</table>
经过以上的调用将产生如下的显示结果：
<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>
上面VTL将产生如下的输出：
<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>
9.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（）方法被执行了三次。
如果你不需要这样的特性可以通过以下方法：
#set ( $myval = $foo.bar() )
#callme ( $myval )
10.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。
11.Escaping VTL directives
VTL directives can be escaped with “/”号，使用方式跟VTL的reference使用逃逸符的格式差不多。
## #include( “a.txt” ) renders as <ontents 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” )
在对在一个directive内包含多个script元素的VTL directives使用逃逸符时要特别小心（比如在一个if-else-end statement内）。下面是VTL的if-statement的典型应用：
#if ( $jazz )
Vyacheslav Ganelin
#end
如果$jazz是ture，输出将是：
Vyacheslav Ganelin
如果$jazz是false，将没有输出。使用逃逸符将改变输出。考虑一下下面的情况：
/#if ( $jazz )
Vyacheslav Ganelin
/#end
现在无论$jazz是true还是false，输出结果都是：
#if ( $jazz )
Vyacheslav Ganelin
#end
事实上，由于你使用了逃逸符，$jazz根本就没有被解析为boolean型值。在逃逸符前使用逃逸符是合法的，例如：
//#if ( $jazz )
Vyacheslav Ganelin
//#end
以上程序的显示结果为：
/ Vyacheslav Ganelin
/
但是如果$jazz为false，那么将没有输出。（书上说会没有输出，但是我觉得应该还有有“/”字符被输出。）
VTL：Formatting issues
尽管在此用户手册中VTL通常都开始一个新行，如下所示：
#set ( $imperial = [ “Munetaka”, “Koreyasu”, “Hisakira”, “Morikune” ] )
#foreach ( $shogun in $imperial )
$shogun
#end
但是像下面这种写法也是可以的：
Send me #set($foo = [“$10 and”,”a cake”])#foreach($a in $foo)$a #end please.
上面的代码可以被改写为：
Send me
#set ( $foo = [“$10 and “,”a cake”] )
#foreach ( $a in $foo )
$a
#end
please.
或者
Send me
#set($foo = [“$10 and “,”a cake”])
#foreach （$a in $foo ）$a
#end please.
这两种的输出结构将一样。
其他特性和杂项
math 在模板中可以使用Velocity内建的算术函数，如：加、减、乘、除
#set ( $foo = $bar + 3 )
#set ( $foo = $bar - 4 )
#set ( $foo = $bar * 6 )
#set ( $foo = $bar / 2 )
当执行除法时将返回一个Integer类型的结果。而余数你可以使用%来得到：
#set ( $foo = $bar % 5 )
在Velocity内使用数学计算公式时，只能使用像-n,-2,-1,0,1,2,n这样的整数，而不能使用其它类型数据。当一个非整型的对象被使用时它将被logged并且将以null作为输出结果。
12.Range Operator
Range operator可以被用于与#set和#foreach statement联合使用。对于处理一个整型数组它是很有用的，Range operator具有以下构造形式：
[n..m]
m和n都必须是整型，而m是否大于n则无关紧要。例子：
First example:
#foreach ( $foo in [1..5] )
$foo
#end
Second example:
#foreach ( $bar in [2..-2] )
$bar
#end
Third example:
#set ( $arr = [0..1] )
#foreach ( $i in $arr )
$i
#end
Fourth example:
[1..3]
上面四个例子的输出结果为：
First example：
1 2 3 4 5
Second example：
2 1 0 -1 -2
Third example：
0 1
Fourth example：
[1..3]
注意：range operator只在#set和#foreach中有效。
Advanced Issue：Escaping and！
当一个reference被“！”分隔时，并且在它之前有逃逸符时，reference将以特殊的方式处理。注意这种方式与标准的逃逸方式时不同的。对照如下：
#set ( $foo = “bar” )
特殊形式 标准格式
Render前 Render后 Render前 Render后
$/!foo $!foo /$foo /$foo
$/!{foo} $!{foo} /$!foo /$!foo
$//!foo $/!foo /$!{foo} /$!{foo}
$///!foo $//!foo //$!{foo} /bar
13.Velocimacro杂记
Can I user a directive or another VM as an argument to a VM?
例如：#center ( #bold( “hello” ) )
不可以。一个directive的参数使用另外一个directive是不合法的。
但是，还是有些事情你可以作的。最简单的方式就是使用双引号：
#set ( $stuff = “#bold( ‘hello’ )” )
#center ( $stuff )
上面的格式也可以缩写为一行：
#center ( “#bold( ‘hello’ ) )
请注意在下面的例子中参数被evaluated在Velocimacro内部，而不是在calling level。例子：
#macro ( inner $foo )
inner : $foo
#end
#macro ( outer $foo )
#set ( $bar = “outerlala” )
outer : $foo
#end
#set ( $bar = ‘calltimelala’ )
#outer( “#inner($bar)” )
输出结果为：
outer : inner : outerlala
记住Veloctiy的特性：参数的传递是By Name的。例如：
#macro ( foo $color )
<tr bgcolor = $color ><td>Hi</td></tr>
<tr bgcolor = $color ><td>There</td></tr>
#end
#foo ( $bar.rowColor() )
以上代码将导致rowColor()方法两次调用，而不是一次。为了避免这种现象的出现，我们可以按照下面的方式执行：
#set ( $color = $bar.rowColor() )
#foo ( $color )
can I register velocimacros via #parse()?
目前，Velocimacros必须在第一次被模板调用前被定义。这就意味着你的#macro()声明应该出现在使用Velocimacros之前。
如果你试图#parse()一个包含#macro() directive的模板，这一点是需要牢记的。因为#parse()发生在运行期，但是解析器在parsetiem决定一个看似VM元素的元素是否是一个VM元素，这样#parse()-ing一组VM声明将不按照预期的样子工作。为了得到预期的结果，只需要你简单的使用velocimacro.library使得Velocity在启动时加载你的VMs。
What is velocimacro autoreloading？
velocimacro.library.autoreload是专门为开发而非产品使用的一个属性。此属性的默认值是false。
String concatenation
开发人员最常问的问题是我如何作字符拼接？在java中是使用“＋”号来完成的。
在VTL里要想实现同样的功能你只需要将需要联合的reference放到一起就行了。例如：
#set ( $size = “Big” )
#set ( $name = “Ben” )
The clock is $size$name.
输出结果将是：The clock is BigBen.。更有趣的情况是：
#set ( $size = “Big” )
#set ( $name = “Ben” )
#set ( $clokc = “$size$name” )
The clock is $clock.
上例也会得到同样的结果。最后一个例子，当你希望混合固定字段到你的reference时，你需要使用标准格式：
#set ( $size = “Big” )
#set ( $name = “Ben” )
#set ( $clock = “${size}Tall$name” )
The clock is $clock.
输出结果是：The clock is BigTallBen.。使用这种格式主要是为了使得$size不被解释为$sizeTall。
Velocity 用户指南手册中文版（转）
[align=left]1. 关于[/align]
[align=left]Velocity 用户指南旨在帮助页面设计者和内容提供者了解Velocity 和其简单而又强大的脚本语言（Velocity Template Language (VTL)）。本指南中有很多示例展示了用Velocity来讲动态内容嵌入到网站之中，但是所有的VTL examples 都同演示用于所有的页面和模版。[/align]
[align=left]感谢选择Velocity![/align]
[align=left] [/align]
[align=left]2. 什么是Velocity?[/align]
[align=left]Velocity 是一个基于Java的模版引擎。它允许web 页面设计者引用JAVA代码预定义的方法。Web 设计者可以根据MVC模式和JAVA程序员并行工作，这意味着Web设计者可以单独专注于设计良好的站点，而程序员则可单独专注于编写底层代码。Velocity 将Java 代码从web页面中分离出来，使站点在长时间运行后仍然具有很好的可维护性，并提供了一个除JSP和PHP之外的可行的被选方案。[/align]
[align=left]Velocity可用来从模板产生web 页面，SQL, PostScript以及其他输出。他也可用于一个独立的程序以产生源代码和报告，或者作为其它系统的一个集成组件。这个项目完成后，Velocity将为Turbine web 应用程序框架提供模板服务。Velocity+Turbine 方案提供的模板服务将允许web 应用按真正的mvc模式进行开发。[/align]
[align=left] [/align]
[align=left]3. Velocity 可以做什么?[/align]
[align=left]3.1. Mud Store 示例[/align]
[align=left]假设你是一个专门销售泥浆（MUD）的在线商店的页面设计者。我们称他为"The Online Mud Store"。生意很好。客户订购各种各样的类型和数量的泥浆。他们使用他们的用户名和密码登陆到商店中来，就可以浏览他们的订货和购买其他东西。现在，赤土陶泥正在促销，这是一种很常用的泥巴。一少部分顾客很有规律的购买一种亮红土Bright Red Mud，这也是促销产品，但是不太常用，因此被移到页面的边缘。所有顾客的信息都在数据库中被跟踪，因此有一天问题出现了：为什么不使用Velocity来定位目标客户，这些客户对某种类型的产品特别感兴趣？[/align]
[align=left]Velocity 使针对访问者个性的WEB页面客户化（个性化）非常容易。作为一个在线泥巴商店的站点设计者，以想在客户以登陆进展点后就看到它们想看的页面。[/align]
[align=left]你遇到你公司的软件工程师，每个人都认为$customer 将保持当前登陆进入的客户信息，而$mudsOnSpecial 将士当前所有促销的泥巴。$flogger 对象包含有助于促销的方法。对于当前的任务，让我们仅关注这三个问题。记住，你不需要担心软件工程师如何从数据库中取得顾客信息，但你必须知道他们可以。这样可以使你专注于你的工作而软件工程师则忙于他们自己的工作。[/align]
[align=left]你可以在你的页面中嵌入如下的VTL语句：[/align]
| [align=left]<HTML>[/align] [align=left]<BODY>[/align] [align=left]Hello $customer.Name![/align] [align=left]<table>[/align] [align=left]#foreach( $mud in $mudsOnSpecial )[/align] [align=left] #if ( $customer.hasPurchased($mud) )[/align] [align=left] <tr>[/align] [align=left] <td>[/align] [align=left] $flogger.getPromo( $mud )[/align] [align=left] </td>[/align] [align=left] </tr>[/align] [align=left] #end[/align] [align=left]#end[/align] [align=left]</table>[/align] |
[align=left]foreach语句的细节将进一步细说，但重要的是这个短小的脚本居然可以在你的站点上运行。当有一个倾向于亮红土的顾客登陆进来时，亮红土正在促销，这就是这个顾客所看到的，并且促销显示非常显著。如果另外一个长期购买赤陶土的顾客登陆进来，赤陶土促销的提示信息则应该在前面中间位置。Velocity是非常灵活的，受限的只是你的创造力。[/align]
[align=left]写在VTL参考文档中的是其他Velocity 元素，他们一起给你很强大的能力和灵活性以创建很好的站点。待你更加了解这些元素，就可以开始释放Velocity的强大动力。[/align]
[align=left]4. Velocity模板语言(VTL): 介绍[/align]
[align=left]Velocity模板语言(VTL)旨在为Web页面结合动态内容提供最容易、简单和简洁的方法。即使有一点或者没有编程经验的页面设计者也可以很快能为页面提供动态内容。[/align]
[align=left]VTL 使用引用（references）来将动态内容嵌入web页面，每个变量就是某一个类型的引用。变量实际上是一个可以调用定义在java代码中的内容的引用，或者它可以从页面内的VTL语句得出自身的值。下面是一个例子，说明可以嵌入到HTML文档中的VTL语句。[/align]
| [align=left] [/align] [align=left]#set( $a = "Velocity" ) [/align] [align=left] [/align] |
[align=left]这个VTL语句，就像所有的VTL语句一样，以#字符开始，并跟着一个指令set。当一个在线访问这请求页面时， Velocity 模伴引擎在页面内搜索所有#字符，然后决定是哪一个标记了VTL语句的开始，哪个标记不需要VTL做什么动作。[/align]
[align=left] [/align]
[align=left] #字符后面紧跟一个指令set.。set指令使用一个括在括号内的表达式---一个等式将一个值指派给一个变量。变量在等号的左边而值在等号的右边。[/align]
[align=left] [/align]
[align=left]在上面的示例中，变量是$a值是Velocity。这个变量就象其他引用一样，以一个$字符开始。值通常在引号之中，对Velocity来说一般没有类型冲突的问题，因为只有字符串 (基于文本的信息)可以传递给变量。[/align]
[align=left] [/align]
[align=left]下面的主要规则可能有助于理解Velocity 是如何工作的：引用以$开头用于取得什么东西，而指令以#开始用于做什么事情。[/align]
[align=left]在上面的例子中，#set用于将一个值指派给一个变量。而变量$a则可以用来在模板中输出"Velocity" 。[/align]
[align=left]5. Hello Velocity World![/align]
[align=left]一旦一个值被赋给一个变量，便可以在HTML中随处引用它。在下面的示例中，先给变量$foo赋值然后引用它。[/align]
| [align=left]<html>[/align] [align=left]<body>[/align] [align=left]#set( $foo = "Velocity" )[/align] [align=left]Hello $foo World![/align] [align=left]</body>[/align] [align=left]<html>[/align] |
[align=left]这个页面的结果是输出"Hello Velocity World!"。[/align]
[align=left]为了使包含VTL 指令的语句具有可读性，我们鼓励每个VTL语句在一个新行开始，虽然并不一定要这样做。set将随后深入解释。[/align]
[align=left] [/align]
[align=left]6. 注释[/align]
[align=left]可以用注释加入描述性文本，他们并不在模板引擎中输出。注释可以有助于你的记忆或者想其他人解释你的VTL语句正在做什么。[/align]
| [align=left]## This is a single line comment.[/align] |
[align=left]单行注释以##开始，并在本行结束。如果需要加入多行注释，并不需要加入很多的单行注释。多行注释，以#*开始并以*#结束可以处理这种情况。[/align]
| [align=left]This is text that is outside the multi-line comment.[/align] [align=left]Online visitors can see it.[/align] [align=left] [/align] [align=left]#*[/align] [align=left] Thus begins a multi-line comment. Online visitors won't[/align] [align=left] see this text because the Velocity Templating Engine will[/align] [align=left] ignore it.[/align] [align=left]*#[/align] [align=left] [/align] [align=left]Here is text outside the multi-line comment; it is visible.[/align] |
[align=left] [/align]
[align=left]下面事一些例子说明单行注释和多行注释如何工作。[/align]
| [align=left]This text is visible. ## This text is not.[/align] [align=left]This text is visible.[/align] [align=left]This text is visible. #* This text, as part of a multi-line comment,[/align] [align=left]is not visible. This text is not visible; it is also part of the[/align] [align=left]multi-line comment. This text still not visible. *# This text is outside[/align] [align=left]the comment, so it is visible.[/align] [align=left]## This text is not visible.[/align] |
[align=left]还有第三种注释， VTL 注释块，可以用来存储诸如文档作者、版本信息等。[/align]
[align=left] [/align]
| [align=left]#**[/align] [align=left]This is a VTL comment block and[/align] [align=left]may be used to store such information[/align] [align=left]as the document author and versioning[/align] [align=left]information:[/align] [align=left]@author[/align] [align=left]@version 5[/align] [align=left]*#[/align] |
[align=left]7. 引用[/align]
[align=left]VTL中有三种类型的引用：变量，属性和方法。作为使用VTL的设计者，你和你的工程师必须在饮用的特定命名上取得一致，以便在你的模板中正确的使用他们。[/align]
[align=left] [/align]
[align=left]有关引用的所有参数都处理为字符串对象。Everything coming to and from a reference is treated as a String object. 假如有一个对象表示$foo (比如说是整型对象)，Velocity 将调用其toString() 方法来将此对象转换为一个字符串。[/align]
[align=left]7.1. 变量Variables[/align]
[align=left]变量的简略标记是有一个前导"$"字符后跟一个 VTL 标识符（Identifier.）组成。一个VTL 标识符必须以一个字母开始(a .. z或 A .. Z)。剩下的字符将由以下类型的字符组成：[/align]
[align=left]字母 (a .. z, A .. Z) [/align]
[align=left]数字 (0 .. 9) [/align]
[align=left]连字符("-") [/align]
[align=left]下划线 ("_") [/align]
[align=left]下面是一些有效的变量引用:[/align]
| [align=left]$foo[/align] [align=left]$mudSlinger[/align] [align=left]$mud-slinger[/align] [align=left]$mud_slinger[/align] [align=left]$mudSlinger1[/align] |
[align=left]当VTL 引用一个变量时，比如$foo，变量可以从模板的set指令取得值，也可以从[/align]
[align=left] Java 代码中取得。例如，如果Java 变量$foo在模板被请求的时候具有值bar，则bar将替换页面中的所有$foo的实例。或者，如果包含下面的语句：[/align]
| [align=left]#set( $foo = "bar" )[/align] |
[align=left]紧跟指令后的所有$foo的实例的输出将会一样值。[/align]
[align=left]7.2. 属性[/align]
[align=left]
VTL引用的第二种元素是属性，而属性具有独特的格式。属性的简略标记识前导符$后跟一个VTL 标识符，在后跟一个点号(".")最后又是一个VTL 标识符。这是一些有效的示例：[/align]
| [align=left]$customer.Address[/align] [align=left]$purchase.Total[/align] |
[align=left]请看第一个例子，$customer.Address.。他有两种意思。它可以意味着，查询由customer标是的哈希表并按关键字Address返回值。但是$customer.Address也可能引用一个方法（下述，$customer.Address可能是$customer.getAddress().的缩写。当一个页面被请求时，Velocity 将决定这两种可能到底是哪一个，然后返回相应的值。[/align]
[align=left]7.3. 方法[/align]
[align=left]方法在JAVA代码中定义，并作一些有用的事情，比如运行一个计算器或者作出一个决定。方法是实际上也是引用，由前导符"$"后跟一个VTL 标识符，后跟一个VTL 方法体（Method Body）。 VTL 方法体由一个VTL 标识符后跟一个左括号，再跟可选的参数列表，最后是右括号。下面是一些有效的方法示例：[/align]
[align=left] [/align]
| [align=left]$customer.getAddress()[/align] [align=left]$purchase.getTotal()[/align] [align=left]$page.setTitle( "My Home Page" )[/align] [align=left]$person.setAttributes( ["Strange", "Weird", "Excited"] )[/align] |
[align=left]前面两个例子-- $customer.getAddress()和$purchase.getTotal() – 看起来有点象上面属性一节中所用的样子，$customer.Address和$purchase.Total.。如果你想这些例子在某些方面相关，那你就对了。[/align]
[align=left] [/align]
[align=left]VTL 属性可以为VTL方法用作简略标记。属性$customer.Address具有和方法$customer.getAddress() 完全一样的效果。属性和方法的主要不同点是方法中可以添加参数列表。[/align]
[align=left]简略标记可以用在下面的方法中：[/align]
| [align=left]sun.getPlanets()[/align] [align=left]$annelid.getDirt()[/align] [align=left]$album.getPhoto()[/align] |
[align=left]我们或许希望方法可以为我们放回属于太阳系的行星的名字，喂养我们的蚯蚓，或者从相册中返回一张照片。下面只有长的那个标记是可以工作的方法：[/align]
| [align=left]$sun.getPlanet( ["Earth", "Mars", "Neptune"] )[/align] [align=left]## 不能将参数列表传递给$sun.Planets[/align] [align=left] [/align] [align=left]$sisyphus.pushRock()[/align] [align=left]## Velocity 假定我意思是$sisyphus.getRock()[/align] [align=left] [/align] [align=left]$book.setTitle( "Homage to Catalonia" )[/align] [align=left]## 不能传递一个参数列表[/align] [align=left] [/align] |
[align=left]引用的简略符号如上所述，但是另外还有一种引用的形式符号，示例如下：[/align]
| [align=left]${mudSlinger}[/align] [align=left]${customer.Address}[/align] [align=left]${purchase.getTotal()}[/align] |
[align=left]在大多数情况下，我们将使用引用的简略符号，但在一些情况下，也需要拥戴哦形式引用符以便正确处理。[/align]
[align=left]假定你正在纸片上构件一个句子，将使用$vice作为句子中名词的词根。我们的目标是允许人们选择词根，然后产生以下两种结果之一：[/align]
[align=left]"Jack is a pyromaniac."[/align]
[align=left]或者 "Jack is a kleptomaniac."。[/align]
[align=left] 在这种情况下，使用简略符号是不太充分的。考虑到下面的例子：[/align]
| [align=left]Jack is a $vicemaniac.[/align] |
[align=left] [/align]
[align=left]这里有个不确定性， Velocity 假定 $vicemaniac，（而不是 $vice）是一个你想要使用的标识符。找不到$vicemaniac的值，他将返回$vicemaniac。使用形式符号便可解决这个问题：[/align]
| [align=left]Jack is a ${vice}maniac[/align] |
[align=left] [/align]
[align=left]7.5. 安静引用符Quiet Reference Notation[/align]
[align=left]当 Velocity 遇到一个位定义的引用时，其通常行为是输出这个引用的映像。比如，假设下面的引用出现在模板中的一部分：[/align]
| [align=left]<input type="text" name="email" value="$email"/>[/align] |
| [align=left]<input type="text" name="email" value="$!email"/>[/align] |
[align=left] [/align]
[align=left]形式和安静引用符可以一起使用，如下所示：[/align]
| [align=left]<input type="text" name="email" value="$!{email}"/>[/align] |
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. 取得语义Getting literal[/align]
[align=left]VTL 特别的字符，比如$ 和 #，来做这个工作，因此在模板中使用这些自负的时候必须格外小心。本节讲述$ 的转义。[/align]
[align=left]1.1. 货币[/align]
[align=left]我们写下句子 "I bought a 4 lb. sack of potatoes at the farmer's market for only $2.50!" ，这并没有什么问题。但如前所述，VTL标识符总是以大写或是小写字母开始，所以$2.50 在引用中将不能出错。[/align]
[align=left]1.2. 转义有效的VTL 引用[/align]
[align=left]问题将会出现，因为Velocity 将有一个潜在的冲突。转义特殊字符是处理VTL模板种特殊字符的最好的办法，者可以用一个反斜线来进行。[/align]
| [align=left]foo[/align] [align=left]$email[/align] [align=left]/foo[/align] [align=left]/$email[/align] |
[align=left]如果 Velocity 在VTL模板中遇到一个$email引用，他将在上下文中查找相应的值。这里，输出将是foo，因为 $email 是定义了的。如果$email 未定义，输出将是$email 。[/align]
[align=left] [/align]
[align=left]假设$email 是定义了的（比如，具有值foo)，但是你想输出 $email。可以有几种方法来做这个事情，不是最简单的是使用转义符。[/align]
| [align=left]## The following line defines $email in this template:[/align] [align=left]#set( $email = "foo" )[/align] [align=left]$email[/align] [align=left]/$email[/align] [align=left]//$email[/align] [align=left]///$email[/align] |
[align=left]将输出是[/align]
| [align=left]foo[/align] [align=left]$email[/align] [align=left]/foo[/align] [align=left]/$email[/align] |
[align=left]注意： / 绑定在$ 的左边。从做绑定原则使///$email 被解释为//$email。和上面例子比较下面的例子，这里$email 未定义。[/align]
| [align=left]$email[/align] [align=left]/$email[/align] [align=left]//$email[/align] [align=left]///$email[/align] |
[align=left] [/align]
| [align=left]$email[/align] [align=left]/$email[/align] [align=left]//$email[/align] [align=left]///$email[/align] |
[align=left]注意，Velocity 处理定义和未定义的引用是不同的。下面一个set 指令将$foo 设为值gibbous.。[/align]
| [align=left]#set( $foo = "gibbous" )[/align] [align=left]$moon = $foo[/align] |
[align=left]输出将是$moon = gibbous [/align]
[align=left]-- 这里 $moon 作为字面输出，因为他并没有定义。而gibbous 将在$foo 的位置输出。[/align]
[align=left] [/align]
[align=left]我们也可以转义VTL 指令，这将在指令一节祥述。[/align]
[align=left] [/align]
[align=left]2. Case Substitution [/align]
[align=left]现在你大致了解了引用，可以在模板中使用它们了。Velocity 采用了很多JAVA原理的优点，模板设计人员会发现非常容易使用。例如：[/align]
| [align=left]$foo[/align] [align=left] [/align] [align=left]$foo.getBar()[/align] [align=left]## is the same as[/align] [align=left]$foo.Bar[/align] [align=left] [/align] [align=left]$data.getUser("jon")[/align] [align=left]## is the same as[/align] [align=left]$data.User("jon")[/align] [align=left] [/align] [align=left]$data.getRequest().getServerName()[/align] [align=left]## is the same as[/align] [align=left]$data.Request.ServerName[/align] [align=left]## is the same as[/align] [align=left]${data.Request.ServerName}[/align] |
[align=left]Velocity, 建模在Sun Microsystems定义的BEAN规范之上，是大小写敏感的；开发者努力捕捉和纠正可能出现的用户错误。当方法getFoo() 在模板中通过$bar.foo引用时，Velocity 首先尝试$getfoo。如果失败，他会再尝试 $getFoo。类似地，当一个模板引用到 $bar.Foo， Velocity 将尝试 $getFoo() 先，然后尝试 getfoo()。[/align]
[align=left]注意：模板中引用示例变量的问题仍然没有解决。只有引用等价于JavaBean的 getter/setter 方法解决了。(比如 $foo.Name 解决了到类 Foo的 getName() 示例方法的引用，但不能引用Foo的一个公共实例变量Name)。[/align]
[align=left]3. 指令[/align]
[align=left]因为指令（使用脚本来有效操控JAVA代码的输出）允许页面设计员真正专注于咱点的外观和内容设计，引用允许模板设计员为Web页面产生动态内容。[/align]
[align=left] [/align]
[align=left]3.1. #set [/align]
[align=left] #set 指令用来为引用设置相应的值。值可以被值派给变量引用或者是属性引用，而且赋值要在括号里括起来。[/align]
| [align=left]#set( $primate = "monkey" )[/align] [align=left]#set( $customer.Behavior = $primate )[/align] |
[align=left]变量引用[/align]
[align=left]字面字符串[/align]
[align=left]属性引用[/align]
[align=left]方法引用[/align]
[align=left]字面数字[/align]
[align=left]数组列表[/align]
[align=left] [/align]
[align=left]这些例子演示了上述的每种类型：[/align]
| [align=left]#set( $monkey = $bill ) ## variable reference[/align] [align=left]#set( $monkey.Friend = "monica" ) ## string literal[/align] [align=left]#set( $monkey.Blame = $whitehouse.Leak ) ## property reference[/align] [align=left]#set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference[/align] [align=left]#set( $monkey.Number = 123 ) ##number literal[/align] [align=left]#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList[/align] |
[align=left]右边也可以是一个简单的算术表达式:[/align]
| [align=left]#set( $value = $foo + 1 )[/align] [align=left]#set( $value = $bar - 1 )[/align] [align=left]#set( $value = $foo * $bar )[/align] [align=left]#set( $value = $foo / $bar )[/align] |
| [align=left]#set( $result = $query.criteria("name") )[/align] [align=left]The result of the first query is $result[/align] [align=left] [/align] [align=left]#set( $result = $query.criteria("address") )[/align] [align=left]The result of the second query is $result[/align] |
[align=left] [/align]
[align=left]如果， $query.criteria("name") 放回字符串"bill"，而$query.criteria("address") 返回 null，上述VTL 将解释为：[/align]
| [align=left]The result of the first query is bill[/align] [align=left] [/align] [align=left]The result of the second query is bill[/align] |
| [align=left]#set( $criteria = ["name", "address"] )[/align] [align=left] [/align] [align=left]#foreach( $criterion in $criteria )[/align] [align=left] [/align] [align=left] #set( $result = $query.criteria($criterion) )[/align] [align=left] [/align] [align=left] #if( $result )[/align] [align=left] Query was successful[/align] [align=left] #end[/align] [align=left] [/align] [align=left]#end[/align] |
[align=left] [/align]
[align=left]我们对此的解决方法是预设$result 为 false。然后如果 $query.criteria() 调用失败，你就可以检查之。[/align]
[align=left] [/align]
| [align=left]#set( $criteria = ["name", "address"] )[/align] [align=left] [/align] [align=left]#foreach( $criterion in $criteria )[/align] [align=left] [/align] [align=left] #set( $result = false )[/align] [align=left] #set( $result = $query.criteria($criterion) )[/align] [align=left] [/align] [align=left] #if( $result )[/align] [align=left] Query was successful[/align] [align=left] #end[/align] [align=left] [/align] [align=left]#end[/align] |
[align=left]3.2. 字面字符串[/align]
[align=left]当使用#set 指令时，括在双引号中的字面字符串将解析和重新解释，如下所示：[/align]
| [align=left]#set( $directoryRoot = "www" )[/align] [align=left]#set( $templateName = "index.vm" )[/align] [align=left]#set( $template = "$directoryRoot/$templateName" )[/align] [align=left]$template[/align] |
| [align=left]www/index.vm[/align] |
[align=left]然而，当字面字符串括在单引号中时，他将不被解析：[/align]
| [align=left]#set( $foo = "bar" )[/align] [align=left]$foo[/align] [align=left]#set( $blargh = '$foo' )[/align] [align=left]$blargh[/align] |
[align=left]输出是：[/align]
| [align=left]Bar[/align] [align=left] $foo[/align] |
[align=left] [/align]
[align=left]3.3. 条件[/align]
[align=left]3.4. If / ElseIf / Else [/align]
[align=left] Velocity中的#if 指令允许在页面生成时，在IF条件为真的情况下包含文本。例如：[/align]
| [align=left]#if( $foo )[/align] [align=left] <strong>Velocity!</strong>[/align] [align=left]#end[/align] |
[align=left]变量 $foo 先求值，以决定是否为真。在这两种情况下为真： (i) $foo 是一个逻辑变量并具有真的值，或者 (ii) 值非空。要记住Velocity 上下文仅包括对象，所以当我们说“布尔”'boolean'时，他会被表示为“布尔类”(Boolean class)。这对即使是返回布尔类型的方法也是真的—自省架构将返回一个具有相同逻辑值的布尔类。[/align]
[align=left]如果求值为真时， #if 和 #end 语句之间的内容将输出。在这种情况下，如果 $foo 为真，输出将是"Velocity!"。相反，如果 $foo 具有一个null 值，或者逻辑假，语句求值为假，则没有输出。[/align]
[align=left]一个 #elseif 或者 #else 项可以用在#if 语句中。请注意， Velocity 模板引擎将在第一个为真的表达式时停止。下面的例子中，假设$foo 具有值15 而 $bar 等于 6。[/align]
[align=left] [/align]
| [align=left]#if( $foo < 10 )[/align] [align=left] <strong>Go North</strong>[/align] [align=left]#elseif( $foo == 10 )[/align] [align=left] <strong>Go East</strong>[/align] [align=left]#elseif( $bar == 6 )[/align] [align=left] <strong>Go South</strong>[/align] [align=left]#else[/align] [align=left] <strong>Go West</strong>[/align] [align=left]#end[/align] |
[align=left]请注意在现在， Velocity的数值比较约束为整型—其他类型都将求值为false。仅有一个例外是等于'=='，这时Velocity 要求等号两边的对象具有相同的类型。[/align]
[align=left]3.5. 关系和逻辑操作符[/align]
[align=left]Velocity 使用等式操作符来决定两个变量间的关系。这里是一个简单的例子演示如何使用等式操作符：[/align]
| [align=left]#set ($foo = "deoxyribonucleic acid")[/align] [align=left]#set ($bar = "ribonucleic acid")[/align] [align=left] [/align] [align=left]#if ($foo == $bar)[/align] [align=left] In this case it's clear they aren't equivalent. So...[/align] [align=left]#else[/align] [align=left] They are not equivalent and this will be the output.[/align] [align=left]#end[/align] |
| [align=left]## logical AND[/align] [align=left] [/align] [align=left]#if( $foo && $bar )[/align] [align=left] <strong> This AND that</strong>[/align] [align=left]#end[/align] [align=left] [/align] |
[align=left]逻辑OR 的工作方式相同，唯一的例外是其中一个表达式要被求值，以便决定整个表达式是否为真。请看下面的例子：[/align]
[align=left] [/align]
| [align=left]## logical or[/align] [align=left] [/align] [align=left]#if( $foo || $bar )[/align] [align=left] <strong>This or That</strong>[/align] [align=left]#end[/align] |
[align=left]对于逻辑NOT 操作符，只有一个操作数：[/align]
| [align=left]##logical NOT[/align] [align=left] [/align] [align=left]#if( !$foo )[/align] [align=left] <strong>NOT that</strong>[/align] [align=left]#end[/align] [align=left] [/align] |
[align=center] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. 循环[/align]
[align=left]1.1. Foreach 循环[/align]
[align=left] #foreach 元素允许进行循环，例如：[/align]
| [align=left]<ul>[/align] [align=left]#foreach( $product in $allProducts )[/align] [align=left] <li>$product</li>[/align] [align=left]#end[/align] [align=left]</ul>[/align] |
[align=left]$allProducts 变量的内容是一个矢量，一个哈希表或者数组。赋给$product 变量的值是一个Java 对象并且可以从一个类似的变量引用。例如，如果 $product 真是一个Java的产品类，其名称可以通过引用$product.Name 方法来检索(即: $Product.getName())。[/align]
[align=left] [/align]
[align=left]我们假定 $allProducts 是一个哈希表。如果你想检索关键字的值或者在哈希表中的对象，你可以使用以下的代码：[/align]
[align=left] [/align]
| [align=left]<ul>[/align] [align=left]#foreach( $key in $allProducts.keySet() )[/align] [align=left] <li>Key: $key -> Value: $allProducts.get($key)</li>[/align] [align=left]#end[/align] [align=left]</ul>[/align] |
[align=left]Velocity 提供一个更容易的方式或的循环计数，以便你可以做下面类似的工作：[/align]
| [align=left]<table>[/align] [align=left]#foreach( $customer in $customerList )[/align] [align=left] <tr><td>$velocityCount</td><td>$customer.Name</td></tr>[/align] [align=left]#end[/align] [align=left]</table>[/align] |
[align=left]循环计数变量的缺省名称是$velocityCount，在velocity.properties 配置文件中标明。默认情况下，该变量从1开始计数，但是可以在velocity.properties 文件中设为从0或者1开始。下面是velocity.properties 文件中循环变量设置一节: [/align]
| [align=left]# Default name of the loop counter[/align] [align=left]# variable reference.[/align] [align=left]directive.foreach.counter.name = velocityCount[/align] [align=left] [/align] [align=left]# Default starting value of the loop[/align] [align=left]# counter variable reference.[/align] [align=left]directive.foreach.counter.initial.value = 1[/align] |
[align=left]2. 包含[/align]
[align=left]#include 脚本元素允许模板设计人员包含（导入）本地文件，这个文件将插入到#include 指令被定义的地方。文件的内容并不通过模板引擎来渲染。处于安全的原因，被包含的文件只可以放在TEMPLATE_ROOT下。[/align]
[align=left] [/align]
| [align=left]#include( "one.txt" )[/align] |
| [align=left]#include( "one.gif","two.txt","three.htm" )[/align] |
[align=left]被包含的文件并不是一定要用文件名来引用，事实上，最好的办法是使用变量而不是文件名。这在根据规则决定何时提交页面时，决定目标输出是很有用的。[/align]
| [align=left]#include( "greetings.txt", $seasonalstock )[/align] |
[align=left] [/align]
[align=left]3. 解析[/align]
[align=left] #parse 脚本元素允许页面设计员导入包含VTL的本地文件。 Velocity将解析和渲染指定的模板。[/align]
| [align=left]#parse( "me.vm" )[/align] |
[align=left]就象 #include 指令，#parse 可以使用变量而不是一个实在的模板文件。#parse 引用的模板文件必须包含的TEMPLATE_ROOT指定的目录之下。和 #include 指令不一样， #parse 只有一个参数。[/align]
[align=left]VTL 模板templates can have #parse statements referring to templates that in turn have #parse statements. By default set to 10, the parse_directive.maxdepth line of the velocity.properties allows users to customize maximum number of #parse referrals that can occur from a single template. (Note: If the parse_directive.maxdepth property is absent from the velocity.properties file, Velocity will set this default to 10.) Recursion is permitted, for example, if the template dofoo.vm contains the following lines: [/align]
| [align=left]Count down.[/align] [align=left]#set( $count = 8 )[/align] [align=left]#parse( "parsefoo.vm" )[/align] [align=left]All done with dofoo.vm![/align] |
[align=left]It would reference the template parsefoo.vm, which might contain the following VTL: [/align]
| [align=left]$count[/align] [align=left]#set( $count = $count - 1 )[/align] [align=left]#if( $count > 0 )[/align] [align=left] #parse( "parsefoo.vm" )[/align] [align=left]#else[/align] [align=left] All done with parsefoo.vm![/align] [align=left]#end[/align] |
[align=left]After "Count down." is displayed, Velocity passes through parsefoo.vm, counting down from 8. When the count reaches 0, it will display the "All done with parsefoo.vm!" message. At this point, Velocity will return to dofoo.vm and output the "All done with dofoo.vm!" message.[/align]
[align=left] [/align]
[align=left]4. 停止[/align]
[align=left] [/align]
[align=left] #stop 脚本允许模板设计员停止模板引擎的执行，并返回。这通常用作调试。[/align]
| [align=left]#stop[/align] |
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. 宏[/align]
[align=left]#macro 脚本元素允许模板设计者在VTL 模板中定义重复的段。 Velocimacros 不管是在复杂还是简单的场合都非常有用。下面这个Velocimacro，仅用来节省击键和减少排版错误，介绍了一些Velocity宏的概念。[/align]
| [align=left]#macro( d )[/align] [align=left]<tr><td></td></tr>[/align] [align=left]#end[/align] |
[align=left]在例子中，Velocimacro定义为d，它可以象调用其他VTL指令一样的形式来进行调用：[/align]
| [align=left]#d()[/align] |
[align=left]当这个模板被调用时， Velocity 将 #d() 替换为一个单行的空表格。[/align]
[align=left] [/align]
[align=left]Velocimacro 可以带一些参数，也可以不带参数（如上例所示）。但在他被调用时，所带的参数必须和其定义时的参数一样。很多Velocimacros 定义为不止一个参数。下面这个宏带有两个参数，一个颜色，一个数组。[/align]
| [align=left]#macro( tablerows $color $somelist )[/align] [align=left]#foreach( $something in $somelist )[/align] [align=left] <tr><td bgcolor=$color>$something</td></tr>[/align] [align=left]#end[/align] [align=left]#end[/align] |
[align=left]在这个例子中定义的Velocimacro，名为tablerows, 要求两个参数。第一个参数代替$color, 第二个代替$somelist。[/align]
[align=left]可以写进VTL 模板中的东西都可以写进Velocimacro 的主体部分。tablerows 宏其实是一个foreach 语句。在#tablerows 宏的定义中有两个#ende语句，第一个属于#foreach, 第二个结束宏定义。[/align]
| [align=left]#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )[/align] [align=left]#set( $color = "blue" )[/align] [align=left]<table>[/align] [align=left] #tablerows( $color $greatlakes )[/align] [align=left]</table>[/align] |
[align=left]请注意$greatlakes 替换了$somelist。这样，当#tablerows 宏被调用时，将产生以下输出：[/align]
| [align=left]<table>[/align] [align=left] <tr><td bgcolor="blue">Superior</td></tr>[/align] [align=left] <tr><td bgcolor="blue">Michigan</td></tr>[/align] [align=left] <tr><td bgcolor="blue">Huron</td></tr>[/align] [align=left] <tr><td bgcolor="blue">Erie</td></tr>[/align] [align=left] <tr><td bgcolor="blue">Ontario</td></tr>[/align] [align=left]</table>[/align] |
[align=left]Velocimacros 在Velocity 模板语句内定义，这意味着它在同一站点内的其他Velocity 模板中并不有效。定义一个宏，并使其与其他模板共享很具有明显的优点：他减少了在大量的模板内重复定义宏的工作，并减少了出错的机会，并确保对其他宏的改变对其他所有模板有效。[/align]
[align=left]但如果 #tablerows($color $list) 宏是在一个Velocimacros 模板库内定义的，它就可以被其他常规模板所用。当然，它可以用于各种目的，也可重用多次。在表示所有真菌类（fungi）的mushroom.vm 模板中，#tablerows 宏可以被用来列出典型的蘑菇。[/align]
| [align=left]#set( $parts = ["volva","stipe","annulus","gills","pileus"] )[/align] [align=left]#set( $cellbgcol = "#CC00FF" )[/align] [align=left]<table>[/align] [align=left]#tablerows( $cellbgcol $parts )[/align] [align=left]</table>[/align] |
[align=left]我们对mushroom.vm执行请求，Velocity 将在模板库内找到#tablerows 宏 (在velocity.properties 文件中定义)并产生以下输出：[/align]
| [align=left]<table>[/align] [align=left] <tr><td bgcolor="#CC00FF">volva</td></tr>[/align] [align=left] <tr><td bgcolor="#CC00FF">stipe</td></tr>[/align] [align=left] <tr><td bgcolor="#CC00FF">annulus</td></tr>[/align] [align=left] <tr><td bgcolor="#CC00FF">gills</td></tr>[/align] [align=left] <tr><td bgcolor="#CC00FF">pileus</td></tr>[/align] [align=left]</table>[/align] |
[align=left]Velocimacro 参数[/align]
[align=left]Velocimacros 的参数可以是以下的VTL元素：[/align]
[align=left]引用（Reference）: 以 '$' 打头的元素[/align]
[align=left]字面字符串（String literal） : 比如"$foo" 或 'hello' [/align]
[align=left]字面数字: 1, 2 …. [/align]
[align=left]整数范围: [ 1..2] 或 [$foo .. $bar] [/align]
[align=left]对象数组: [ "a", "b", "c"] [/align]
[align=left]布尔真[/align]
[align=left]布尔假[/align]
[align=left] [/align]
[align=left]当把引用作为参数传递给Velocimacros时，请注意引用是按“名字”传递的。这意味着他们的值在每次使用他们的Velocimacro中产生。这个特性允许你在方法调用是传递引用，并在每次使用时进行方法调用。例如，Fo，当调用下面的Velocimacro 时，[/align]
| [align=left]#macro( callme $a )[/align] [align=left] $a $a $a[/align] [align=left] #end[/align] [align=left] [/align] [align=left] #callme( $foo.bar() )[/align] |
[align=left]结果是，在方法bar() 中，引用 $foo 被调用了3次。[/align]
[align=left]咋看时，这个特征让人吃惊，当当你考虑一下Velocimacros的原本动机 – 在VTL模板中避免很多“剪切复制”操作—你就会明白。它允许你将无状态对象，比如在一个颜色表格行内重复产生一些颜色次序的对象，传递给Velocimacro。[/align]
[align=left]如果你需要使用这个特征，你通常可以从方法内取得一个值，作为一个新的引用传递给宏：[/align]
| [align=left] #set( $myval = $foo.bar() )[/align] [align=left] #callme( $myval )[/align] |
[align=left]Velocimacro 属性[/align]
[align=left]在velocity.properties 文件中有数行定义可以用来灵活实现Velocimacros。详细情况请参见开发指南（Developer Guide）。[/align]
[align=left]velocimacro.library –是一个逗号分隔的所有Velocimacro 模板库的列表。默认情况下， Velocity 搜寻一个单一的库VM_global_library.vm.。预先配置的模板路径用来查找Velocimacro 库。[/align]
[align=left] [/align]
[align=left]velocimacro.permissions.allow.inline –这个属性决定Velocimacros 是否可以在常规模板内定义，取值为逻辑True或者False。默认情况下，设置为true，允许设计者在产规模板内定义宏。[/align]
[align=left]velocimacro.permissions.allow.inline.to.replace.global –逻辑true 或者false，允许标明是否允许在常规模板内定义的Velocimacro 代替在模板库中定义并通过velocimacro.library属性在启动时装入的全局宏。默认设置为false。[/align]
[align=left]velocimacro.permissions.allow.inline.local.scope –逻辑true 或者false，默认值为false。控制是否在模板内定义的Velocimacros 仅在定义它的模板内可见。换句话说，如果设置为true，一个模板可以定义仅能被他所用的宏。你可以用它来做一些漂亮的宏，如果一个全局调用另一个全局宏，在局部（inline）范围内，当被一个模板调用时，该模板可以定义一个被第一个全局宏调用的第二个全局宏的私有实现。其他所有模板都不受影响。[/align]
[align=left] [/align]
[align=left]velocimacro.context.localscope –逻辑值true 或者 false，缺省值为false。但设置为true时，所有在Velocimacro 内通过 #set() 进行的修改都将被视为Velocimacro 的本地行为，不会影响到其上下文。[/align]
[align=left]velocimacro.library.autoreload –此属性控制Velocimacro 库的自动载入。缺省值为false。如果设置为true，被调用的Velocimacro得源库将被检查是否改变，并在必要是重新载入。这将使你可以改变和测试Velocimacro 库，而不必重新启动应用服务器或者servlet容器，就象你工作在常规模板一样。这个模时仅在资源载入器的缓存模时被关闭的情况下有效 (如 file.resource.loader.cache = false )。此特征为开发时设计，不要在生产模式时使用。[/align]
[align=left]Velocimacro Trivia [/align]
[align=left]当前， Velocimacros 在其首次在模版中使用前必须首先定义它。这意味着， #macro() 宣称应该在使用Velocimacros之前。[/align]
[align=left]如果你想#parse() 一个包含#macro() 指令的模板，记住这个非常重要。因为#parse() 在运行时发生，解析器在解析时要决定是否模版中一个看起来像VM的元素真是VM，所以解析一系列VM 宣称可能并不能如愿地工作的很好。为避免如此，可以简单地使用velocimacro.library 的办法，使Velocity 在启动时载入VM。[/align]
[align=left] [/align]
[align=left]2. 转义 VTL 指令[/align]
[align=left]VTL 可以通过反斜杠("/")来进行转义，directives can be escaped with the backslash character in a manner similar to valid VTL references. [/align]
| [align=left]## #include( "a.txt" ) renders as <contents of a.txt>[/align] [align=left]#include( "a.txt" )[/align] [align=left] [/align] [align=left]## /#include( "a.txt" ) renders as /#include( "a.txt" )[/align] [align=left]/#include( "a.txt" )[/align] [align=left] [/align] [align=left]## //#include ( "a.txt" ) renders as /<contents of a.txt>[/align] [align=left]//#include ( "a.txt" )[/align] |
[align=left]在转义在一个单一指令内包含多个脚本元素（比如f-else-end语句）的指令时应多加小心。下面是一个典型的VTL if语句；[/align]
| [align=left]#if( $jazz )[/align] [align=left] Vyacheslav Ganelin[/align] [align=left]#end[/align] |
[align=left]如果 $jazz为 true，输出是[/align]
| [align=left]Vyacheslav Ganelin[/align] |
[align=left]如果 $jazz 为false，将没有输出。转义脚本元素将改变输出。考虑下面的情况；[/align]
| [align=left]/#if( $jazz )[/align] [align=left] Vyacheslav Ganelin[/align] [align=left]/#end[/align] |
[align=left]不管 $jazz 是真或假，输出都是[/align]
| [align=left]#if($ jazz )[/align] [align=left] Vyacheslav Ganelin[/align] [align=left] #end[/align] [align=left] [/align] |
[align=left]事实上，因为所有脚本元素都被转义了， $jazz 永远不会被求值。将设反斜杠在被合法转义的脚本元素之前[/align]
| [align=left]//#if( $jazz )[/align] [align=left] Vyacheslav Ganelin[/align] [align=left]//#end[/align] |
[align=left]这时，如果$jazz 为真，输出是[/align]
| [align=left]/ Vyacheslav Ganelin[/align] [align=left]/[/align] |
[align=left]为理解这个情况，请注意在一个新行结束是将在输出中忽略新的一行。因此，经过#if()前的'//' 加工后，#if()块紧跟第一个'/'。最后一个/位于新的一行，因为在'Ganelin'后又一个新行，所以，最后的那个位于#end 之前的//是语句块的一部分。[/align]
[align=left]如果 $jazz 为false，这里将没有输出。注意，在开始破坏了if语句的情况将不能被正确转义：[/align]
| [align=left]///#if( $jazz )[/align] [align=left] Vyacheslave Ganelin[/align] [align=left]//#end[/align] |
[align=left]这里，#if 被转义，但有一个#end 被保留了；所以有多个结束语句将导致解析错误。[/align]
[align=center] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]1. VTL: 格式化[/align]
[align=left]虽然在本指南中的VTL经常显示在新行中或者有空格，但是下面的VTL [/align]
| [align=left]#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )[/align] [align=left]#foreach( $shogun in $imperial )[/align] [align=left] $shogun[/align] [align=left]#end[/align] |
[align=left]和下面的写法同样有效。[/align]
| [align=left]Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.[/align] |
[align=left]Velocity的行为并不受空格的影响，前述的指令也可以写成：[/align]
| [align=left]Send me[/align] [align=left]#set( $foo = ["$10 and ","a cake"] )[/align] [align=left]#foreach( $a in $foo )[/align] [align=left]$a[/align] [align=left]#end[/align] [align=left]please.[/align] |
[align=left]或者[/align]
| [align=left]Send me[/align] [align=left]#set($foo = ["$10 and ","a cake"])[/align] [align=left] #foreach ($a in $foo )$a[/align] [align=left] #end please.[/align] |
[align=left]上面每种写法结果都一样。[/align]
[align=left]2. 其它特征和杂项[/align]
[align=left]2.1. 数学特征[/align]
[align=left]Velocity 有一些内建的数学功能，可以使用set指令用在模版中。下面的共识分别演示了加减乘除运算：[/align]
| [align=left]#set( $foo = $bar + 3 )[/align] [align=left]#set( $foo = $bar - 4 )[/align] [align=left]#set( $foo = $bar * 6 )[/align] [align=left]#set( $foo = $bar / 2 )[/align] |
[align=left]当进行除法运算时，结果将会是整数。When a division operation is performed, the result will be an integer. 余数则可以通过模(%)运算获得。[/align]
| [align=left]#set( $foo = $bar % 5 )[/align] |
[align=left]在Velocity 中，只有整数可以进行数学运算；如果执行非整数的数学运算，将被记录下来，并返回null 。[/align]
[align=left]2.2. 范围操作符[/align]
[align=left]范围操作符可以和#set 和#foreach 语句一起使用。有助于产生一个整数的目标数组，范围操作符有以下的结构：[/align]
| [align=left][n..m][/align] |
[/align]
[align=left] [/align]
[align=left]n 和 m 都必须是整数或者可以产生整数。不管 m 大于或者小于n 都没关系；在m小于n这种情况下，范围可以向下计数。下面是使用范围操作符的例子：[/align]
| [align=left]第一个例子[/align] [align=left]#foreach( $foo in [1..5] )[/align] [align=left]$foo[/align] [align=left]#end[/align] [align=left] [/align] [align=left]第二个例子[/align] [align=left]#foreach( $bar in [2..-2] )[/align] [align=left]$bar[/align] [align=left]#end[/align] [align=left] [/align] [align=left]第三个例子[/align] [align=left]#set( $arr = [0..1] )[/align] [align=left]#foreach( $i in $arr )[/align] [align=left]$i[/align] [align=left]#end[/align] [align=left] [/align] [align=left]第四个例子[/align] [align=left][1..3][/align] |
[align=left] [/align]
[align=left]他们分别产生一下输出[/align]
| [align=left]1 2 3 4 5[/align] [align=left] [/align] [align=left]2 1 0 -1 -2[/align] [align=left] [/align] [align=left]0 1[/align] [align=left] [/align] [align=left] [1..3][/align] |
[align=left]范围操作符和#set 和#foreach 指令一起使用时，只是产生数组。[/align]
[align=left]页面设计人员在设计具有相同尺寸的表格时，有时没有足够的数据来填充，他们会发现范围操作符非常有用。[/align]
[align=left]2.3. 进阶：转义和! [/align]
[align=left]当一个引用被! 字符处于静寂模式，并且! 字符在转义符/ 前出现，应用将用一种特别的方式处理。请注意他和常规转义的不同，下面这种情况/ 先于! 出现: [/align]
| [align=left]#set( $foo = "bar" )[/align] [align=left]$/!foo[/align] [align=left]$/!{foo}[/align] [align=left]$//!foo[/align] [align=left]$///!foo[/align] |
[align=left]这样将被加工成[/align]
| [align=left]$!foo[/align] [align=left]$!{foo}[/align] [align=left]$/!foo[/align] [align=left]$//!foo[/align] |
[align=left] [/align]
[align=left]对比常规转义，/先于 $: [/align]
| [align=left]/$foo[/align] [align=left]/$!foo[/align] [align=left]/$!{foo}[/align] [align=left]//$!{foo}[/align] |
[align=left] [/align]
[align=left]这是结果是：[/align]
| [align=left]/$foo[/align] [align=left]/$!foo[/align] [align=left]/$!{foo}[/align] [align=left]/bar[/align] |
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left] [/align]
[align=left]3. Velocimacro 杂记[/align]
[align=left]本节是关于Velocimacros的一个小型FAQ。本届内容会不时更新，所以请常来检查新的内容，[/align]
[align=left]注 : 本节中， 'Velocimacro' 将简写为'VM'。[/align]
[align=left] [/align]
[align=left]Q:是否可以使用指令directive 或者 VM 作为另一个VM的参数? 例如: #center( #bold("hello") ) [/align]
[align=left]A: 不行。指令不能用作指令的参数，而大多数情况下，作为实际的应用，VM就是指令。[/align]
[align=left]不过也有一些办法。一个简单的做法是使用双引号来加工你的内容。所以，你可以这样：[/align]
| [align=left]#set($stuff = "#bold('hello')" )[/align] [align=left]#center( $stuff )[/align] |
[align=left]甚至可以节省一个步骤：[/align]
| [align=left]#center( "#bold( 'hello' )" )[/align] |
[align=left]请注意，后面这个例子中，参数是在VM内部被求值，不是在调用的那一层次上。换句话说，被传入的VM的参数是整个被传入的，并且在传入的VM内部被求值。所以我们可以这样做：[/align]
| [align=left]#macro( inner $foo )[/align] [align=left] inner : $foo[/align] [align=left]#end[/align] [align=left] [/align] [align=left]#macro( outer $foo )[/align] [align=left] #set($bar = "outerlala")[/align] [align=left] outer : $foo[/align] [align=left]#end[/align] [align=left] [/align] [align=left]#set($bar = 'calltimelala')[/align] [align=left]#outer( "#inner($bar)" )[/align] [align=left] [/align] |
[align=left]这里，输入将会是：[/align]
| [align=left]Outer : inner : outerlala[/align] |
[align=left]因为"#inner($bar)" 的求值发生在#outer()内部，所以在#outer() 内设置的$bar得值会是其使用的值。[/align]
[align=left]这是一个有意的保护特征—参数按名称传递给VM，所以可以将象状态引用的东西传给VM ，比如：[/align]
| [align=left]#macro( foo $color )[/align] [align=left] <tr bgcolor=$color><td>Hi</td></tr>[/align] [align=left] <tr bgcolor=$color><td>There</td></tr>[/align] [align=left]#end[/align] [align=left] [/align] [align=left]#foo( $bar.rowColor() )[/align] |
[align=left]rowColor() 被重复调用而不是一次。为避免如此，可以调用VM外部的方法，然后将值传递给VM. [/align]
| [align=left]#set($color = $bar.rowColor())[/align] [align=left]#foo( $color )[/align] |
[align=left]Q:是否可以通过#parse()注册VM ? [/align]
[align=left]A：当前， Velocimacros 在其首次在模版中使用前必须首先定义它。这意味着， #macro() 宣称应该在使用Velocimacros之前。[/align]
[align=left]如果你想#parse() 一个包含#macro() 指令的模板，记住这个非常重要。因为#parse() 在运行时发生，解析器在解析时要决定是否模版中一个看起来像VM的元素真是VM，所以解析一系列VM 宣称可能并不能如愿地工作的很好。为避免如此，可以简单地使用velocimacro.library 的办法，使Velocity 在启动时载入VM。[/align]
[align=left] [/align]
[align=left]Q. 什么是VM自动载入（Velocimacro Autoreloading）? [/align]
[align=left]A. 这是一个属性，在开发时使用，而不时运行时：[/align]
[align=left] velocimacro.library.autoreload [/align]
[align=left]默认值为false。当设置为true时，连同<type>.resource.loader.cache 属性设置为false（这里<type> 是使用的资源载入器的名称，比如'file') ，Velocity 引擎在你创建VM库文件是将自动载入其改变，这样你就不必将其导入servlet 引擎（或者应用程序）中，或者用其他手段来使其自动重新载入。[/align]
[align=left] [/align]
[align=left]下面是一个简单的设置配置组合：[/align]
| [align=left]file.resource.loader.path = templates[/align] [align=left] file.resource.loader.cache = false[/align] [align=left] velocimacro.library.autoreload = true[/align] |
[align=left]注意在生产状态（运行时）不要使其打开。[/align]
[align=left] [/align]
[align=left]4. 字符串联[/align]
[align=left]开发者常问的一个问题是“我如何进行字符串串联？”是否有类似于JAVA中的'+'操作符？[/align]
[align=left]为了串联VTL中的引用，你不得不将它们“放在一起”。而你想要放置在一起的上下文很重要，下面举例说明。[/align]
[align=left]在常规“笨办法”模板中：[/align]
| [align=left] #set( $size = "Big" )[/align] [align=left] #set( $name = "Ben" )[/align] [align=left] [/align] [align=left] The clock is $size$name.[/align] [align=left] [/align] |
| [align=left] #set( $size = "Big" )[/align] [align=left] #set( $name = "Ben" )[/align] [align=left] [/align] [align=left] #set($clock = "$size$name" )[/align] [align=left] [/align] [align=left] The clock is $clock.[/align] [align=left] [/align] |
[align=left]结果是一样的。作为最后一个例子，当你想混合“静态”字符串到引用中，你可能需要使用“形式引用”：[/align]
| [align=left]#set( $size = "Big" )[/align] [align=left]#set( $name = "Ben" )[/align] [align=left]#set($clock = "${size}Tall$name" )[/align] |
| [align=left]现在，输出将会是'The clock is BigTallBen'。[/align] |
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐
- Velocity用户手册---中文版
- Velocity用户手册
- Velocity用户手册-中文版
- Velocity用户手册---中文版
- Velocity用户手册---中文版
- Velocity用户手册
- Velocity用户手册---中文版(学习修改版)
- 【资料】Velocity 用户指南手册中文版
- Velocity用户手册---中文版(学习修改版)
- Velocity用户手册
- Velocity用户手册---中文版(学习修改版)
- Velocity用户手册---中文版
- Velocity用户手册---中文版(学习修改版)
- Velocity用户手册
- Velocity中文用户手册
- Velocity用户手册---中文版
- Velocity用户手册---中文版
- Velocity User Guide 用户手册
- Velocity用户手册---中文版
- Velocity用户手册---中文版