velocity中文手册.doc

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

2、和干静的方法将动态内容合并到Web 页面。 VTL 使用引用 (references) 将动态内容插入到 Web 页面中。变量是一种引用， 可以指向 Java 代码中的定义内容，或者由 Web 页面中的 VTL 语句来获得值。下面是一个可以插入到 HTML 文档的 VTL 语句的例子：#set( $a = Velocity )VTL 语句以 #开头，并包含指令 (set) 。变量以 $ 开头，用引号引起。引号可以是单引号，也可以是双引号。前者引用具体的 String 值；后者可以包含 Velocity 引用，例如 ”hello, $name ，” $name 会用其当前的值替换。上面的例子是将

3、值 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 comm

4、ent,is not visible. This text is not visible; it is also part of themulti-line comment. This text still not visible. *# This text is outsidethe comment, so it is visible.# This text is not visible.引用VTL 有 3 种类型的引用：变量、属性和方法。作为一个设计者，必须和Java工程师在 VTL 引用的名称（标识符）上一致，以便在模板中使用它们。引用是作为 String对象处理的。（ 1）变量变量的格

5、式： $VTL 标识符VTL 标识符以字母开始，由字母、数字、横划线 (-) 或下划线 (_)组成。变量或者从模板中的 set 指令获得值（如前面的例子），或者 Java 代码（同名变量）中获得值。Velocity 只处理已定义的变量引用， 对于没有定义的变量引用， Velocity 原样返回。例如下面的例子：#set( $foo = gibbous )$moon = $foo输出结果是： $moon = gibbous（ 2）属性属性的格式： $VTL 标识符 . VTL 标识符下面是属性引用的例子：$customer.Address$purchase.Total拿第一例子来说，有两种意思：

6、返回 Hashtable对象 customer 中键值为 Address 的值$customer.getAddress()方法引用的缩写（JavaBean 属性的 getter 方法）至于是哪种情况， Velocity 会做决定，返回合适的值。（ 3）方法方法的格式： $VTL 标识符 (参数列表 )下面是方法引用的例子：$customer.getAddress()$purchase.getTotal()$page.setTitle( My Home Page )$person.setAttributes( Strange, Weird, Excited )前面两个例子可以缩写成属性引用 （如

7、属性引用的例子） 。属性引用和方法引用的主要区别是方法引用可以指定参数列表。（ 4）正式引用符号： 正式引用符号在使用变量引用含糊的地方进行区分。看下面的例子：#set( $vice = klepto )Jack is a $vicemaniac.输出结果是： Jack is a $vicemaniac.（$vicemaniac没有定义，原样输出）#set( $vice = klepto )Jack is a $vicemaniac.输出结果是： Jack is a kleptomaniac. （使用正式引用符号将 $vice 和其它文本区分开）（ 5） Quit 引用符号： !看下面的例子：

8、初始时， $email 没有值，所以文本框中会显示值 $email ，而更希望 是空白。下面是使用 Quit 引用符号的例子：当 $email 没有值时， Velocity 会用空串替代 $email 。（ 6）特殊字符转义对于 $、#等特殊字符要正常显示，可以使用 进行转义， 转义为 。下面是一个例子：#set( $email = foo )$email$email$email$email输出结果是：foo$emailfoo$email指令 (Directives)引用允许模板设计者为Web 站点生成动态内容，而指令使巧妙处理Java 代码的脚本元素容易使用。（ 1 ）#set格式： #se

9、t( 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#

10、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 aboveRHS 可以是简单的算术表达式#set( $value = $f

11、oo + 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( $criter

12、ion 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( $

13、result = $query.criteria($criterion) )#if( $result )Query was successful#end#endString文字可以使用双引号或单引号括起。两者的主要区别是双引号中的引用会替换成相应的值，而单引号中的引用原样输出#set( $directoryRoot = www )#set( $templateName = index.vm )#set( $template = $directoryRoot/$templateName )$template输出结果是： www/index.vm如果使用单引号：#set( $template =

14、$directoryRoot/$templateName )输出结果是： $directoryRoot/$templateName使用双引号可以实现字符串的串联，如下面的例子：#set( $size = Big )#set( $name = Ben )#set($clock = $sizeTall$name )The clock is $clock.（ 2 ）#if / #elseif / #else#if 指令在条件成立时， 显示 #if 和#end 之间的内容， 否则显示 #else 和 #end 之间的内容。 下面是一个例子：#if( $foo )Velocity!#end条件成立有两种

15、情况：如果 $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对象：#

16、foreach( $key in $allProducts.keySet() )Key: $key - Value: $allProducts.get($key)#endVelocity提供了访问循环计数变量的简单方法：#foreach( $customer in $customerList )$velocityCount$customer.Name#end$velocityCount是 Velocity表示循环计数的内部变量，缺省开始值为1。该设置在perties文件中定义：# Default name of the loop counter# variable re

17、ference. = 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#endSecond example:#foreach( $bar in 2.-2 )$bar#endTh

18、ird example:#set( $arr = 0.1 )#foreach( $i in $arr )$i#end输出结果是：First example:12345Second example:210-1-2Third example:0 1（ 4 ）#include#include指令导入本地文件到#include指令定义的地方。导入的文件内容不会被模板引擎解析。出于安全考虑，导入的文件应该放在TEMPLATE_ROOT目录下。一次可以导入多个文件，文件名之间用逗号分隔；并且通常使用变量引用来替代文件名。下面是一个例子：#include( greetings.txt, $seasonals

19、tock )（ 5 ）#parse#parse 指令允许导入一个包含VTL 的本地文件，并由模板引擎进行解析。#parse 指令导入的文件必须放在 TEMPLATE_ROOT目录下，并且一次只能导入一个文件。允许在Velocity模板中嵌套执行 #parse 指令。最大深度由perties文件中的 parse_directive.maxdepth定义。下面是一个例子：Count down.#set( $count = 8 )#parse( parsefoo.vm )All done with dofoo.vm!包含的 parsefoo.vm文件如下：$count#set

20、( $count = $count - 1 )#if( $count 0 )#parse( parsefoo.vm )#elseAll done with parsefoo.vm!#end输出结果是：Count down.876543210All done with parsefoo.vm!All done with dofoo.vm!（ 6 ）#stop#stop 指令停止模板引擎的执行并返回。这在Debug 时很有用。（ 7 ）#macro#macro 指令允许定义一段重复使用的VTL 模板（称 Velocimacros）。Velocimacros可以有 0 或多个参数。下面是一个例子：#

21、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 )输出结果为：SuperiorMichiganHuron

22、ErieOntarioVelocimacros可以在 VTL 模板中定义为inline ，这样对其它的VTL 模板是无效的；要使Velocimacros在所有 VTL 模板中共享，可以将Velocimacros定义在 Velocimacros模板库（全局）中。Velocimacros属性在 perties文件中定义，提供实现Velocimacros的灵活性：velocimacro.library = VM_global_library.vmvelocimacro.permissions.allow.inline = truevelocimacro.permissions

23、.allow.inline.to.replace.global = falsevelocimacro.permissions.allow.inline.local.scope = falsevelocimacro.context.localscope = falsevelocimacro.library.autoreload = falsevelocimacro.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