Velocity用户指南中文版

导读：

　　什么是Velocity？

　　Velocity是基于Java的模板引擎。它允许Web页面开发者引用Java代码中定义的方法。Web设计者可以和Java程序开发者并行开发遵循MVC模式的Web站点。这意味着，Web设计者可以将精力放在好的Web站点设计上，而Java程序开发者可以将精力放在编写代码上。Velocity将Java代码从Web页面中分离，使Web站点更具长期可维护性，并提供了一种替代JSP或PHP的方案。

　　VTL(Velocity Template Language)介绍

　　VTL提供一种简单、容易和干静的方法将动态内容合并到Web页面。VTL使用引用(references)将动态内容插入到Web页面中。变量是一种引用，可以指向Java代码中的定义内容，或者由Web页面中的VTL语句来获得值。下面是一个可以插入到HTML文档的VTL语句的例子：

　　#set( $a = "Velocity" )

　　VTL语句以#开头，并包含指令(set)。变量以$开头，用引号引起。引号可以是单引号，也可以是双引号。前者引用具体的String值；后者可以包含Velocity引用，例如”hello, $name”， $name会用其当前的值替换。上面的例子是将值Velocity赋值给变量a。

　　当变量被赋值后，就可以在HTML文档的任何地方引用，下面是Hello Velocity World!的例子：

　　

　　

　　#set( $foo = "Velocity" )

　　Hello $foo World!

　　

　　

　　注释

　　VTL支持单行注释（以##开始）和多行注释（包括在#*和*#之间），下面是一个例子：

　　This text is visible. ## This text is not visible.

　　This text is visible.

　　This text is visible. #* This text, as part of a multi-line comment,

　　is not visible. This text is not visible; it is also part of the

　　multi-line comment. This text still not visible. *# This text is outside

　　the comment, so it is visible.

　　## This text is not visible.

　　引用

　　VTL有3种类型的引用：变量、属性和方法。作为一个设计者，必须和Java工程师在VTL引用的名称（标识符）上一致，以便在模板中使用它们。引用是作为String对象处理的。

　　（1）变量

　　变量的格式：$VTL标识符

　　VTL标识符以字母开始，由字母、数字、横划线(-)或下划线(_)组成。变量或者从模板中的set指令获得值（如前面的例子），或者Java代码（同名变量）中获得值。Velocity只处理已定义的变量引用，对于没有定义的变量引用，Velocity原样返回。例如下面的例子：

　　#set( $foo = "gibbous" )

　　$moon = $foo

　　输出结果是：$moon = gibbous

　　（2）属性

　　属性的格式：$VTL标识符. VTL标识符

　　下面是属性引用的例子：

　　$customer.Address

　　$purchase.Total

　　拿第一例子来说，有两种意思：

　　 返回Hashtable对象customer中键值为Address的值

　　 $customer.getAddress()方法引用的缩写（JavaBean属性的getter方法）

　　至于是哪种情况，Velocity会做决定，返回合适的值。

　　（3）方法

　　方法的格式：$VTL标识符(参数列表)

　　下面是方法引用的例子：

　　$customer.getAddress()

　　$purchase.getTotal()

　　$page.setTitle( "My Home Page" )

　　$person.setAttributes( ["Strange", "Weird", "Excited"] )

　　前面两个例子可以缩写成属性引用（如属性引用的例子）。属性引用和方法引用的主要区别是方法引用可以指定参数列表。

　　（4）正式引用符号：{}

　　正式引用符号在使用变量引用含糊的地方进行区分。看下面的例子：

　　#set( $vice = "klepto" )

　　Jack is a $vicemaniac.

　　输出结果是：Jack is a $vicemaniac.（$vicemaniac没有定义，原样输出）

　　#set( $vice = "klepto" )

　　Jack is a ${vice}maniac.

　　输出结果是：Jack is a kleptomaniac.（使用正式引用符号将$vice和其它文本区分开）

　　（5）Quit引用符号：!

　　看下面的例子：

　　

　　初始时，$email没有值，所以文本框中会显示值$email，而更希望是空白。下面是使用Quit引用符号的例子：

　　

　　当$email没有值时，Velocity会用空串替代$email。

　　（6）特殊字符转义

　　对于$、#等特殊字符要正常显示，可以使用/进行转义，//转义为/。下面是一个例子：

　　#set( $email = "foo" )

　　$email

　　/$email

　　//$email

　　///$email

　　输出结果是：

　　foo

　　$email

　　/foo

　　/$email

　　指令(Directives)

　　引用允许模板设计者为Web站点生成动态内容，而指令使巧妙处理Java代码的脚本元素容易使用。

　　（1）#set

　　格式：#set( LHS = RHS )

　　 LHS可以是变量引用或属性引用

　　 RHS可以是引用、字符串、数字、ArrayList或Map

　　下面的例子展示了上面的每种RHS类型：

　　#set( $monkey = $bill ) ## variable reference

　　#set( $monkey.Friend = "monica" ) ## string literal

　　#set( $monkey.Blame = $whitehouse.Leak ) ## property reference

　　#set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference

　　#set( $monkey.Number = 123 ) ##number literal

　　#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList

　　#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) ## Map

　　对于ArrayList和Map，可以使用对应的Java方法访问其中的元素值：

　　$monkey.Say.get(0)

　　$monkey.Map.get("bannana")

　　$monkey.Map.banana ## same as above

　　 RHS可以是简单的算术表达式

　　#set( $value = $foo + 1 ) ## Addition

　　#set( $value = $bar - 1 ) ## Subtraction

　　#set( $value = $foo * $bar ) ## Multiplication

　　#set( $value = $foo / $bar ) ## Division

　　#set( $value = $foo % $bar ) ## Remainder

　　算术表达式只支持整型。/的结果为整数；如果非整型数值，返回null

　　 如果RHS的结果为null，是不会赋值给LHS的

　　看下面的例子：

　　#set( $criteria = ["name", "address"] )

　　#foreach( $criterion in $criteria )

　　#set( $result = $query.criteria($criterion) )

　　#if( $result )

　　Query was successful

　　#end

　　#end

　　上面使用$result检查是否执行成功是有问题的。如果第一次执行成功，$result不为null，则后面的执行不管是否成功，检查条件总是成立。改进的方法是在每次执行前初始化为false：

　　#set( $criteria = ["name", "address"] )

　　#foreach( $criterion in $criteria )

　　#set( $result = false )

　　#set( $result = $query.criteria($criterion) )

　　#if( $result )

　　Query was successful

　　#end

　　#end

　　 String文字可以使用双引号或单引号括起。两者的主要区别是双引号中的引用会替换成相应的值，而单引号中的引用原样输出

　　#set( $directoryRoot = "www" )

　　#set( $templateName = "index.vm" )

　　#set( $template = "$directoryRoot/$templateName" )

　　$template

　　输出结果是：www/index.vm

　　如果使用单引号：

　　#set( $template = '$directoryRoot/$templateName’ )

　　输出结果是：$directoryRoot/$templateName

　　 使用双引号可以实现字符串的串联，如下面的例子：

　　#set( $size = "Big" )

　　#set( $name = "Ben" )

　　#set($clock = "${size}Tall$name" )

　　The clock is $clock.

　　（2）#if / #elseif / #else

　　#if指令在条件成立时，显示#if和#end之间的内容，否则显示#else和#end之间的内容。下面是一个例子：

　　#if( $foo )

　　 Velocity!

　　#end

　　条件成立有两种情况：

　　 如果$foo是boolean，则$foo要为true；

　　 否则，$foo不为null

　　#if指令中可以使用的关系和逻辑符号包括：

　　 <、<=、==、>=、>

　　 &&(and)、||(or)、!(not)

　　（3）循环：foreach

　　下面是一个例子：

　　

• 
  
  　　#foreach( $product in $allProducts )
  
  　　
• $product
• 
  
  　　#end
  
  　　

　　$allProducts的内容可以是Vector、Hashtable或ArrayList，每次取出一个值赋值给$product；返回的值是一个Java对象，可以用来引用具体的方法。下面的例子假设$allProducts是Hashtable对象：

　　

• 
  
  　　#foreach( $key in $allProducts.keySet() )
  
  　　
• Key: $key -> Value: $allProducts.get($key)
• 
  
  　　#end
  
  　　

　　Velocity提供了访问循环计数变量的简单方法：

　　







　　#foreach( $customer in $customerList ) 　　

$velocityCount

$customer.Name

　　#end 　　

　　$velocityCount是Velocity表示循环计数的内部变量，缺省开始值为1。该设置在velocity.properties文件中定义：

　　# Default name of the loop counter

　　# variable reference.

　　directive.foreach.counter.name = velocityCount

　　# Default starting value of the loop

　　# counter variable reference.

　　directive.foreach.counter.initial.value = 1

　　可以在#foreach指令中使用范围操作符[n..m]，其中n和m必须是整型：

　　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

　　输出结果是：

　　First example:

　　1 2 3 4 5

　　Second example:

　　2 1 0 -1 -2

　　Third example:

　　0 1

　　（4）#include

　　#include指令导入本地文件到#include指令定义的地方。导入的文件内容不会被模板引擎解析。出于安全考虑，导入的文件应该放在TEMPLATE_ROOT目录下。一次可以导入多个文件，文件名之间用逗号分隔；并且通常使用变量引用来替代文件名。下面是一个例子：

　　#include( "greetings.txt", $seasonalstock )

　　（5）#parse

　　#parse指令允许导入一个包含VTL的本地文件，并由模板引擎进行解析。#parse指令导入的文件必须放在TEMPLATE_ROOT目录下，并且一次只能导入一个文件。允许在Velocity模板中嵌套执行#parse指令。最大深度由velocity.properties文件中的parse_directive.maxdepth定义。下面是一个例子：

　　Count down.

　　#set( $count = 8 )

　　#parse( "parsefoo.vm" )

　　All done with dofoo.vm!

　　包含的parsefoo.vm文件如下：

　　$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!

　　（6）#stop

　　#stop指令停止模板引擎的执行并返回。这在Debug时很有用。

　　（7）#macro

　　#macro指令允许定义一段重复使用的VTL模板（称Velocimacros）。

　　 Velocimacros可以有0或多个参数。下面是一个例子：

　　#macro( tablerows $color $somelist )

　　#foreach( $something in $somelist )

　　$something

　　#end

　　#end

　　这个叫tablerows的Velocimacro带2个参数：一个color和一个array。下面的代码包含对

　　tablerows的调用：

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

　　#set( $color = "blue" )

　　



　　#tablerows( $color $greatlakes ) 　　

　　输出结果为：

　　











　　

Superior

　　

Michigan

　　

Huron

　　

Erie

　　

Ontario

　　

　　 Velocimacros可以在VTL模板中定义为inline，这样对其它的VTL模板是无效的；要使Velocimacros在所有VTL模板中共享，可以将Velocimacros定义在Velocimacros模板库（全局）中。

　　 Velocimacros属性在velocity.properties文件中定义，提供实现Velocimacros的灵活性：

　　velocimacro.library = VM_global_library.vm

　　velocimacro.permissions.allow.inline = true

　　velocimacro.permissions.allow.inline.to.replace.global = false

　　velocimacro.permissions.allow.inline.local.scope = false

　　velocimacro.context.localscope = false

　　velocimacro.library.autoreload = false

　　velocimacro.library：定义逗号分隔的Velocimacros全局模板库，缺省是VM_global_library.vm，可以增加自定义的模板库；

　　velocimacro.permissions.allow.inline：指定是否允许在VTL模板中定义Velocimacros，缺省是true（允许）；

　　velocimacro.permissions.allow.inline.to.replace.global：指定是否允许inline定义的Velocimacros替换同名的全局Velocimacros，缺省是false（不允许）；

　　velocimacro.permissions.allow.inline.local.scope：指定inline定义是否是定义的模板中可见，缺省是false；

　　velocimacro.context.localscope：指定context内容是否是本地范围的，缺省是false；如果设为true，则使用#set指令对context做的修改只在本地范围有效，不会永久性的影响context；

　　velocimacro.library.autoreload：指定是否自动装载Velocimacros模板库，缺省是false；如果设为true，则在调用Velocimacros模板库中的Velocimacro时，会检查模板库是否更新，并在需要时重新装载；使用前提是file.resource.loader.cache = false；该属性应该在开发时使用，而不是产品阶段；

　　 Velocimacros必须在第一次使用之前进行定义。因此#parse指令包含inline定义的Velocimacros的模板会有问题，简单的解决方法就是将Velocimacros定义到模板库中，以便Velocity启动时装载。

　　 引用作为Velocimacros的参数时，是使用by name形式的，这意味在Velocimacros内部每次使用时才会获得其值

　　 Velocimacros的不能作为参数传递给另一个Velocimacros，如：

　　#center( #bold("hello") ) ##invalid

　　你可以采用下面的形式达到同样的目的：

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

　　下面是一个嵌套调用的例子：

　　#macro( inner $foo )

　　inner : $foo

　　#end

　　#macro( outer $foo )

　　#set($bar = "outerlala")

　　outer : $foo

　　#end

　　#set($bar = 'calltimelala')

　　#outer( "#inner($bar)" )

　　输出的结果是：Outer : inner : outerlala

　　因为参数以by name形式传递，在#outer内部先设置$bar的值，再调用#inner。



本文转自

http://soa.5d6d.com/redirect.php?fid=9&tid=5&goto=nextoldset