velocity基础.docx

1、velocity基础Velocity用户手册英文来源: http:/jakarta.apache.org/velocity/docs/user-guide.html关于这个用户手册Velocity用户手册是帮助页面设计者和内容提供者认识Velocity和其简单而功能强大的脚本语言Velocity模板语言（VTL）。在手册上的许多例子，都是用Velocity插入动态的内容到网页上，但是所有的VLT例子都能应用到其他的页面和模板中。感谢使用 Velocity！Velocity是什么？Velocity是一个基于java的模板引擎（template engine）。它允许任何人仅仅简单的使用模板语言（

2、template language）来引用由java代码定义的对象。当Velocity应用于web开发时，界面设计人员可以和java程序开发人员同步开发一个遵循MVC架构的web站点，也就是说，页面设计人员可以只关注页面的显示效果，而由java程序开发人员关注业务逻辑编码。Velocity将java代码从web页面中分离出来，这样为web站点的长期维护提供了便利，同时也为我们在JSP和PHP之外又提供了一种可选的方案。Velocity的能力远不止web站点开发这个领域，例如，它可以从模板（template）产生SQL和PostScript、XML，它也可以被当作一个独立工具来产生源代码和报告，

3、或者作为其他系统的集成组件使用。Velocity也可以为Turbine web开发架构提供模板服务（template service）。Velocity+Turbine提供一个模板服务的方式允许一个web应用以一个真正的MVC模型进行开发。Velocity能为我们作什么？Mud 商店例子假设你是一家专门出售Mud的在线商店的页面设计人员，让我们暂且称它为“在线MUD商店”。你们的业务很旺，客户下了各种类型和数量的mud订单。他们都是通过输入用户名和密码后才登陆到你的网站，登陆后就允许他们查看订单并购买更多的mud。现在，一种非常流行的mud正在打折销售。另外有一些客户规律性的购买另外一种也在打

4、折但是不是很流行的Bright Red Mud，由于购买的人并不多所以它被安置在页面的边缘。所有用户的信息都是被跟踪并存放于数据库中的，所以某天有一个问题可能会冒出来：为什么不使用velocity来使用户更好的浏览他们感兴趣的商品呢？Velocity使得web页面的客户化工作非常容易。作为一个web site的设计人员，你希望每个用户登陆时都拥有自己的页面。你会见了一些公司内的软件工程师，你发现他们每个人都同意客户应该拥有具有个性化的信息。那让我们把软件工程师应该作的事情发在一边，看一看你应该作些什么吧。你可能在页面内嵌套如下的VTL声明：Hello $customer.Name!#forea

5、ch( $mud in $mudsOnSpecial ) #if ( $customer.hasPurchased($mud) ) $flogger.getPromo( $mud ) #end#endforeach 的详细用法不久就会进行深入描述。重要的是，这短小的脚本能在你的网站上出现。当一个对Bright Red Mud 很感兴趣的顾客登陆的时候，同时Bright Red Mud在热卖中，这时顾客就能显著地看到。假如一个玩Terracotta Mud很久的顾客登陆，Terracotta Mud 的售卖信息就会出现在前面中间。Velocity的适用性是很巨大的，限制的只是你的创造性。 VTL

6、 Reference 含有许多其他Velocity元素，这些元素能够共同帮助你，使你的网站更加好。当你越来越熟悉那些原理，你开始释放Velocity的能力。Velocity模板语言(VTL):说明VTL意味着提供最简单、最容易并且最整洁的方式合并页面动态内容。VTL使用references来在web site内嵌套动态内容，一个变量就是一种类型的reference。变量是某种类型的refreence，它可以指向java代码中的定义，或者从当前页面内定义的VTL statement得到值。下面是一个VTL statement的例子，它可以被嵌套到HTML代码中：#set( $a = Veloci

7、ty )和所有的VTL statement一样，这个statement以字符开始并且包含一个directive：set。当一个在线用户请求你的页面时，Velocity 模板引擎将查询整个页面以便发现所有字符，然后确定哪些是VTL statement，哪些不需要VTL作任何事情。字符后紧跟一个directive：set时，这个set directive使用一个表达式（使用括号封闭）一个方程式分配一个值给变量。变量被列在左边，而它的值被列在右边，最后他们之间使用号分割。在上面的例子中，变量是$a，而它的值是Velocity。和其他的references一样以$字符开始，而值总是以双引号封闭。Vel

8、ocity中仅有String可以被赋值给变量。使用$字符开始的references用于得到什么；使用#字符开始的directives用于作些什么。在上面的例子中,#set是分配一个值给变量。变量$a 在模板中输出 Velocity。Hello Velocity World!一旦某个变量被分配了一个值，那么你就可以在HTML文件的任何地方引用它。在下面的例子中，一个值被分配给$foo变量，并在其后被引用。#set( $foo = Velocity )Hello $foo World!上面的实现结果是在页面上打印“Hello Velocity World！”为了使包含VTL directives的

9、statement更具有可读性，我们鼓励你在新行开始每个VTL statement，尽管你不是必须这么作。Set的用法将在后面详细描述。注释 注释是那些描述文本不出现在模板引擎输出里面。注释一个主要用处是提醒自己和解释出现在VTL中的声明，或是其他用途。下面是一个在VLT中的注释例子。# This is a single line comment.单行注释以#开始，结束在这行的结尾。如果你要写几行注释，这没有必要写几个单行注释。多行注释，以#*开始*#结束，可以解决这个问题。This is text that is outside the multi-line comment.Online v

10、isitors can see it.#* Thus begins a multi-line comment. Online visitors wont see this text because the Velocity Templating Engine will ignore it.*#Here is text outside the multi-line comment; it is visible.这里有几个例子关于单行和多行注释如何工作。This text is visible. # This text is not.This text is visible.This text i

11、s visible. #* This text, as part of a multi-line comment,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.这里有第三种类型的注释，VLT注释块，可能用于存放文档的作者名称和版本信息。#*This is a

12、VTL comment block andmay be used to store such informationas the document author and versioninginformation:authorversion 5*#References在VTL中有三种类型的references：变量(variables)、属性(properties)、方法(methods)。作为一个使用VTL的页面设计者，你和你的工程师必须就references的名称达成共识，以便你可以在你的template中使用它们。所有的 reference被作为一个String对象处理。如果有一个对象$

13、foo是一个Integer对象，那么Velocity将调用它的toString()方法将这个对象转型为String类型。变量非正式变量是由“$”开头，接着是VTL标识符。VLT标识符必须以字母(a.z,A.Z)开头。剩下的部分限于以下几种： 字母(a.z,A.Z) 数字(0.9) 连字符(“-”) 下划线(“_”)这里是几个在VTL中有效的变量reference。$foo$mudSlinger$mud-slinger$mud_slinger$mudSlinger1当VLT定义一个变量，例如$foo，变量能或者通过模板中的set 方法，或者通过Java 代码获得值。例如，Java 变量 $foo

14、 的值是 bar ，在这个模板被请求时，在网页上 bar 会替代所有 $foo 。选择地，假如包括了下面的声明：#set( $foo = bar )按照这样的设置，输出就会跟之前的一样。属性第二种有趣的VTL reference就是属性，而且属性有一种与众不同的格式。非正式变量是由“$”开头，接着是VTL标识符，再接着就是字符(“.”)和其他的VLT标识符。这里是一些在VLT中有效属性的定义：$customer.Address$purchase.Total在第一个例子中$customer.Address有两种含义。它可以表示：查找hashtable对象customer中以Address为关键字

15、的值；也可以表示调用customer对象的getAddress()方法。当你的页面被请求时，Velocity将确定以上两种方式选用那种，然后返回适当的值。方法一个方法就是被定义在java中的一段代码，并且它有完成某些有用工作的能力，例如一个执行计算和判断条件是否成立、满足等。方法是一个由$开始并跟随VTL标识符组成的References，一般还包括一个VTL方法体。一个VTL方法体包括一个VLT标识接着一个左括号(“(”)，接着是参数列表，再接着是右括号(“)”)。这里是一些在VTL中有效的方法定义：$customer.getAddress()$purchase.getTotal()$page

16、.setTitle( My Home Page )$person.setAttributes( Strange, Weird, Excited )前两个例子$customer.getAddress()和$purchase.getTotal()看起来挺想上面的属性$customer.Address 和 $purchase.Total。如果你觉得他们之间有某种联系的话，那你是正确的。VTL属性可以作为VTL方法的缩写。$customer.Address属性和使用$customer.getAddress()方法具有相同的效果。如果可能的话使用属性的方式是比较合理的。属性和方法的不同点在于你能够给一个

17、方法指定一个参数列表。非正式定义能够用下面的方法：$sun.getPlanets()$annelid.getDirt()$album.getPhoto()我们期待那些方法返回属于太阳系的行星的名称，喂养我们的蚯蚓，或者从相册里面取出一张照片。只有长符号为下面的方法服务。$sun.getPlanet( Earth, Mars, Neptune )# Cant pass a parameter list with $sun.Planets$sisyphus.pushRock()# Velocity assumes I mean $sisyphus.getRock()$book.setTitle(

18、Homage to Catalonia )# Cant pass a parameter list正式reference标记非正式references用于上述的例子中。但是同样有正式的references，如下面所示：$mudSlinger$customer.Address$purchase.getTotal()在几乎所有场合你都可以使用非正式references，但是在某些场合，只能使用正式reference 才能正确处理。设想你创建一个句子：$vice 作为句子的名词 。目标是为了使某些人选择不同的词，产生下面两种结果之一：Jack is a pyromaniac. 或者 Jack is

19、a kleptomaniac.。使用非正式定义不太适合用于这种情况。看一下下面的例子：Jack is a $vicemaniac.本来变量是$vice现在却变成了$vicemaniac，这样Veloctiy就不知道您到底要什么了。所以，应该使用正是格式书写Jack is a $vicemaniac.现在Velocity就知道reference 是$vice，而不是$vicemaniac。正式定义经常用于模板中refernces与文本连接在一起的情况。Quiet reference notation当Velocity遇到没有定义的reference，通常它会直接输出reference。例如：假如

20、下面的reference出现在一个VTL模板中：当 form 最初加载的时候，变量$email 没有值，但你想出现一个空白的文本框设定值为“$email”。使用quiet reference notation可以使Velocity正常显示，你需要用$!email ，代替$email。所以上面的例子，会改成下面：这样文本框的初始值就不会是email而是空值了。正式和quiet格式的reference notation也可一同使用，像下面这样：Getting literalVelocity使用特殊字符$和#来帮助它工作，所以如果要在template里使用这些特殊字符要格外小心。本节将讨论$字符。货

21、币字符 这是没有问题的：I bought a 4 lb. sack of potatoes at the farmers market for only $2.50!，VTL中使用$2.5这样的货币标识是没有问题得的，VTL不会将它错认为是一个reference，因为VTL中的reference总是以一个大写或者小写的字母开始。Escaping valid VTL reference 某些情况使用Velocity可能会觉得很烦恼。逃避特殊符是处理出现在你的模板中VTL特殊符有效方法，就是使用反斜杠(“”)。#set( $email = foo )$email假如Velocity在你的模板中遇到

22、 $email ，它会搜索上下文，得到相应的值。这里的输出是 foo ，因为 $email 被定义了。假如 $email 没有被定义，输出会是 $email 。设想 $email 被定义了(例如，它的值是 foo )，而且你想输出 $email 。这里有几种方法能达到目的，但是最简单的是使用逃避符。# The following line defines $email in this template:#set( $email = foo )$email$email$email$email将显示为：foo$emailfoo$email注意到 “” 屏蔽了左边的 “$”。屏蔽左边规则，使得 $e

23、mail 显示为 $email 。那些例子与 $email没有定义相比较。$email$email$email$email将显示为：$email$email$email$email注意Velocity处理 定义了的references 与没有定义的不一样。这里 set $foo 的值为 gibbous。#set( $foo = gibbous )$moon = $foo输出会是：$moon = gibbous ,$moon 按照字面上输出因为它没有定义，gibbous 替代 $foo 输出。避开VTL的 directives 还有其他方法，在 Directives 那章节会更详细描述。Case

24、 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那些例子

25、说明了同样的references 用法。Velocity 利用Java的 instrospection 和 bean features解决 reference 的名称对于对象和对象方法的问题。它可以出入你的模板中和求出 references 的值。Velocity 是模仿Sun微系统中的Bean规范定义的，因而它是很灵活的。然而，它的开发者已经很努力地捕捉和纠正可能出现的错误。当方法 getFoo() 在模板中 被 $bar.foo调用时，Velocity首先尝试 $getfoo。如果失败，它会继续尝试 $getFoo。同样地，当模板查询 $bar.Foo，Velocity会先尝试 $getF

26、oo(),然后再尝试 $getfoo()。但是，注意VTL中不会将reference解释为对象的实例变量。例如：$foo.Name将被解释为Foo对象的getName（）方法，而不是Foo对象的Name实例变量。DirectivesReference允许设计者使用动态的内容，而directive使得你可以应用java代码来控制你的显示逻辑，从而达到你所期望的显示效果。#set #set标志是用于对一个reference赋值。值会赋给一个变量或者一个属性，而且赋值会在括号里出现：#set( $primate = monkey )#set( $customer.Behavior = $primat

27、e )左边(LHS) 一定是一个变量或者一个属性。右边(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

28、( $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，这对初学

29、者来讲可能是比较费解的。例如：#set( $result = $query.criteria(name) )The result of the first query is $result#set( $result = $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 billThe r

30、esult of the second query is bill这容易使新手糊涂：创建一个#foreach循环，企图想通过一个属性或者一个方法 #set一个reference，然后马上就用 #if 测试。例如：#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 =