velocity基础.docx

velocity基础.docx

《velocity基础.docx》由会员分享，可在线阅读，更多相关《velocity基础.docx（33页珍藏版）》请在冰豆网上搜索。

velocity基础

Velocity用户手册

英文来源:

http:

//jakarta.apache.org/velocity/docs/user-guide.html

关于这个用户手册

Velocity用户手册是帮助页面设计者和内容提供者认识Velocity和其简单而功能强大的脚本语言――Velocity模板语言（VTL）。

在手册上的许多例子，都是用Velocity插入动态的内容到网页上，但是所有的VLT例子都能应用到其他的页面和模板中。

感谢使用Velocity！

Velocity是什么？

Velocity是一个基于java的模板引擎（templateengine）。

它允许任何人仅仅简单的使用模板语言（templatelanguage）来引用由java代码定义的对象。

当Velocity应用于web开发时，界面设计人员可以和java程序开发人员同步开发一个遵循MVC架构的web站点，也就是说，页面设计人员可以只关注页面的显示效果，而由java程序开发人员关注业务逻辑编码。

Velocity将java代码从web页面中分离出来，这样为web站点的长期维护提供了便利，同时也为我们在JSP和PHP之外又提供了一种可选的方案。

Velocity的能力远不止web站点开发这个领域，例如，它可以从模板（template）产生SQL和PostScript、XML，它也可以被当作一个独立工具来产生源代码和报告，或者作为其他系统的集成组件使用。

Velocity也可以为Turbineweb开发架构提供模板服务（templateservice）。

Velocity+Turbine提供一个模板服务的方式允许一个web应用以一个真正的MVC模型进行开发。

Velocity能为我们作什么？

Mud商店例子

假设你是一家专门出售Mud的在线商店的页面设计人员，让我们暂且称它为“在线MUD商店”。

你们的业务很旺，客户下了各种类型和数量的mud订单。

他们都是通过输入用户名和密码后才登陆到你的网站，登陆后就允许他们查看订单并购买更多的mud。

现在，一种非常流行的mud正在打折销售。

另外有一些客户规律性的购买另外一种也在打折但是不是很流行的BrightRedMud，由于购买的人并不多所以它被安置在页面的边缘。

所有用户的信息都是被跟踪并存放于数据库中的，所以某天有一个问题可能会冒出来：

为什么不使用velocity来使用户更好的浏览他们感兴趣的商品呢？

Velocity使得web页面的客户化工作非常容易。

作为一个website的设计人员，你希望每个用户登陆时都拥有自己的页面。

你会见了一些公司内的软件工程师，你发现他们每个人都同意客户应该拥有具有个性化的信息。

那让我们把软件工程师应该作的事情发在一边，看一看你应该作些什么吧。

你可能在页面内嵌套如下的VTL声明：

Hello$customer.Name!

#foreach（$mudin$mudsOnSpecial）

#if（$customer.hasPurchased（$mud））

#end

#end

foreach的详细用法不久就会进行深入描述。

重要的是，这短小的脚本能在你的网站上出现。

当一个对BrightRedMud很感兴趣的顾客登陆的时候，同时BrightRedMud在热卖中，这时顾客就能显著地看到。

假如一个玩TerracottaMud很久的顾客登陆，TerracottaMud的售卖信息就会出现在前面中间。

Velocity的适用性是很巨大的，限制的只是你的创造性。

VTLReference含有许多其他Velocity元素，这些元素能够共同帮助你，使你的网站更加好。

当你越来越熟悉那些原理，你开始释放Velocity的能力。

Velocity模板语言（VTL）:

说明

VTL意味着提供最简单、最容易并且最整洁的方式合并页面动态内容。

VTL使用references来在website内嵌套动态内容，一个变量就是一种类型的reference。

变量是某种类型的refreence，它可以指向java代码中的定义，或者从当前页面内定义的VTLstatement得到值。

下面是一个VTLstatement的例子，它可以被嵌套到HTML代码中：

#set（$a="Velocity"）

和所有的VTLstatement一样，这个statement以＃字符开始并且包含一个directive：

set。

当一个在线用户请求你的页面时，Velocity模板引擎将查询整个页面以便发现所有＃字符，然后确定哪些是VTLstatement，哪些不需要VTL作任何事情。

＃字符后紧跟一个directive：

set时，这个setdirective使用一个表达式（使用括号封闭）――一个方程式分配一个值给变量。

变量被列在左边，而它的值被列在右边，最后他们之间使用＝号分割。

在上面的例子中，变量是$a，而它的值是Velocity。

和其他的references一样以$字符开始，而值总是以双引号封闭。

Velocity中仅有String可以被赋值给变量。

使用$字符开始的references用于得到什么；使用#字符开始的directives用于作些什么。

在上面的例子中,#set是分配一个值给变量。

变量$a在模板中输出"Velocity"。

HelloVelocityWorld!

一旦某个变量被分配了一个值，那么你就可以在HTML文件的任何地方引用它。

在下面的例子中，一个值被分配给$foo变量，并在其后被引用。

#set（$foo="Velocity"）

Hello$fooWorld!

上面的实现结果是在页面上打印“HelloVelocityWorld！

”

为了使包含VTLdirectives的statement更具有可读性，我们鼓励你在新行开始每个VTLstatement，尽管你不是必须这么作。

Set的用法将在后面详细描述。

注释

注释是那些描述文本不出现在模板引擎输出里面。

注释一个主要用处是提醒自己和解释出现在VTL中的声明，或是其他用途。

下面是一个在VLT中的注释例子。

##Thisisasinglelinecomment.

单行注释以##开始，结束在这行的结尾。

如果你要写几行注释，这没有必要写几个单行注释。

多行注释，以#*开始*#结束，可以解决这个问题。

Thisistextthatisoutsidethemulti-linecomment.

Onlinevisitorscanseeit.

#*

Thusbeginsamulti-linecomment.Onlinevisitorswon't

seethistextbecausetheVelocityTemplatingEnginewill

ignoreit.

*#

Hereistextoutsidethemulti-linecomment;itisvisible.

这里有几个例子关于单行和多行注释如何工作。

Thistextisvisible.##Thistextisnot.

Thistextisvisible.

Thistextisvisible.#*Thistext,aspartofamulti-linecomment,

isnotvisible.Thistextisnotvisible;itisalsopartofthe

multi-linecomment.Thistextstillnotvisible.*#Thistextisoutside

thecomment,soitisvisible.

##Thistextisnotvisible.

这里有第三种类型的注释，VLT注释块，可能用于存放文档的作者名称和版本信息。

#**

ThisisaVTLcommentblockand

maybeusedtostoresuchinformation

asthedocumentauthorandversioning

information:

@author

@version5

*#

References

在VTL中有三种类型的references：

变量（variables）、属性（properties）、方法（methods）。

作为一个使用VTL的页面设计者，你和你的工程师必须就references的名称达成共识，以便你可以在你的template中使用它们。

所有的reference被作为一个String对象处理。

如果有一个对象$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的值是bar，在这个模板被请求时，在网页上bar会替代所有$foo。

选择地，假如包括了下面的声明：

#set（$foo="bar"）

按照这样的设置，输出就会跟之前的一样。

属性

第二种有趣的VTLreference就是属性，而且属性有一种与众不同的格式。

非正式变量是由“$”开头，接着是VTL标识符，再接着就是字符（“.”）和其他的VLT标识符。

这里是一些在VLT中有效属性的定义：

$customer.Address

$purchase.Total

在第一个例子中$customer.Address有两种含义。

它可以表示：

查找hashtable对象customer中以Address为关键字的值；也可以表示调用customer对象的getAddress（）方法。

当你的页面被请求时，Velocity将确定以上两种方式选用那种，然后返回适当的值。

方法

一个方法就是被定义在java中的一段代码，并且它有完成某些有用工作的能力，例如一个执行计算和判断条件是否成立、满足等。

方法是一个由$开始并跟随VTL标识符组成的References，一般还包括一个VTL方法体。

一个VTL方法体包括一个VLT标识接着一个左括号（“（”），接着是参数列表，再接着是右括号（“）”）。

这里是一些在VTL中有效的方法定义：

$customer.getAddress（）

$purchase.getTotal（）

$page.setTitle（"MyHomePage"）

$person.setAttributes（["Strange","Weird","Excited"]）

前两个例子$customer.getAddress（）和$purchase.getTotal（）看起来挺想上面的属性$customer.Address和$purchase.Total。

如果你觉得他们之间有某种联系的话，那你是正确的。

VTL属性可以作为VTL方法的缩写。

$customer.Address属性和使用$customer.getAddress（）方法具有相同的效果。

如果可能的话使用属性的方式是比较合理的。

属性和方法的不同点在于你能够给一个方法指定一个参数列表。

非正式定义能够用下面的方法：

$sun.getPlanets（）

$annelid.getDirt（）

$album.getPhoto（）

我们期待那些方法返回属于太阳系的行星的名称，喂养我们的蚯蚓，或者从相册里面取出一张照片。

只有长符号为下面的方法服务。

$sun.getPlanet（["Earth","Mars","Neptune"]）

##Can'tpassaparameterlistwith$sun.Planets

$sisyphus.pushRock（）

##VelocityassumesImean$sisyphus.getRock（）

$book.setTitle（"HomagetoCatalonia"）

##Can'tpassaparameterlist

正式reference标记

非正式references用于上述的例子中。

但是同样有正式的references，如下面所示：

${mudSlinger}

${customer.Address}

${purchase.getTotal（）}

在几乎所有场合你都可以使用非正式references，但是在某些场合，只能使用正式reference才能正确处理。

设想你创建一个句子：

$vice作为句子的名词。

目标是为了使某些人选择不同的词，产生下面两种结果之一：

"Jackisapyromaniac."或者"Jackisakleptomaniac."。

使用非正式定义不太适合用于这种情况。

看一下下面的例子：

Jackisa$vicemaniac.

本来变量是$vice现在却变成了$vicemaniac，这样Veloctiy就不知道您到底要什么了。

所以，应该使用正是格式书写

Jackisa${vice}maniac.

现在Velocity就知道reference是$vice，而不是$vicemaniac。

正式定义经常用于模板中refernces与文本连接在一起的情况。

Quietreferencenotation

当Velocity遇到没有定义的reference，通常它会直接输出reference。

例如：

假如下面的reference出现在一个VTL模板中：

当form最初加载的时候，变量$email没有值，但你想出现一个空白的文本框设定值为“$email”。

使用quietreferencenotation可以使Velocity正常显示，你需要用$!

email，代替$email。

所以上面的例子，会改成下面：

email"/>

这样文本框的初始值就不会是email而是空值了。

正式和quiet格式的referencenotation也可一同使用，像下面这样：

{email}"/>

Gettingliteral

Velocity使用特殊字符$和#来帮助它工作，所以如果要在template里使用这些特殊字符要格外小心。

本节将讨论$字符。

货币字符

这是没有问题的：

"Iboughta4lb.sackofpotatoesatthefarmer'smarketforonly$2.50!

"，VTL中使用$2.5这样的货币标识是没有问题得的，VTL不会将它错认为是一个reference，因为VTL中的reference总是以一个大写或者小写的字母开始。

EscapingvalidVTLreference

某些情况使用Velocity可能会觉得很烦恼。

逃避特殊符是处理出现在你的模板中VTL特殊符有效方法，就是使用反斜杠（“\”）。

#set（$email="foo"）

$email

假如Velocity在你的模板中遇到$email，它会搜索上下文，得到相应的值。

这里的输出是foo，因为$email被定义了。

假如$email没有被定义，输出会是$email。

设想$email被定义了（例如，它的值是foo），而且你想输出$email。

这里有几种方法能达到目的，但是最简单的是使用逃避符。

##Thefollowinglinedefines$emailinthistemplate:

#set（$email="foo"）

$email

\$email

\\$email

\\\$email

将显示为：

foo

$email

\foo

\$email

注意到“\”屏蔽了左边的“$”。

屏蔽左边规则，使得\\\$email显示为\\$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那章节会更详细描述。

Casesubstitution

现在你已经对reference比较熟悉了，你可以将他们高效的应用于你的template了。

Velocity利用了很多java规范以方便了设计人员的使用。

例如：

$foo

$foo.getBar（）

##isthesameas

$foo.Bar

$data.getUser（"jon"）

##isthesameas

$data.User（"jon"）

$data.getRequest（）.getServerName（）

##isthesameas

$data.Request.ServerName

##isthesameas

${data.Request.ServerName}

那些例子说明了同样的references用法。

Velocity利用Java的instrospection和beanfeatures解决reference的名称对于对象和对象方法的问题。

它可以出入你的模板中和求出references的值。

Velocity是模仿Sun微系统中的Bean规范定义的，因而它是很灵活的。

然而，它的开发者已经很努力地捕捉和纠正可能出现的错误。

当方法getFoo（）在模板中被$bar.foo调用时，Velocity首先尝试$getfoo。

如果失败，它会继续尝试$getFoo。

同样地，当模板查询$bar.Foo，Velocity会先尝试$getFoo（）,然后再尝试$getfoo（）。

但是，注意VTL中不会将reference解释为对象的实例变量。

例如：

$foo.Name将被解释为Foo对象的getName（）方法，而不是Foo对象的Name实例变量。

Directives

Reference允许设计者使用动态的内容，而directive使得你可以应用java代码来控制你的显示逻辑，从而达到你所期望的显示效果。

#set

#set标志是用于对一个reference赋值。

值会赋给一个变量或者一个属性，而且赋值会在括号里出现：

#set（$primate="monkey"）

#set（$customer.Behavior=$primate）

左边（LHS）一定是一个变量或者一个属性。

右边（RHS）可以是下面中的一个类型：

●变量

●字符串

●属性

●方法

●数字

●数组

这些例子显示上述的每一种类型：

#set（$monkey=$bill）##variablereference

#set（$monkey.Friend="monica"）##stringliteral

#set（$monkey.Blame=$whitehouse.Leak）##propertyreference

#set（$monkey.Plan=$spindoctor.weave（$web））##methodreference

#set（$monkey.Number=123）##numberliteral

#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（$result=$query.criteria（"name"））

Theresultofthefirstqueryis$result

#set（$result=$query.criteria（"address"））

Theresultofthesecondqueryis$result

如果$query.criteria（“name”）返回一个“bill”，而$query.criteria（“address”）返回的是null，则显示的结果如下：

Theresultofthefirstqueryisbill

Theresultofthesecondqueryisbill

这容易使新手糊涂：

创建一个#foreach循环，企图想通过一个属性或者一个方法#set一个reference，然后马上就用#if测试。

例如：

#set（$criteria=["name","address"]）

#foreach（$criterionin$criteria）

#set（$result=$query.criteria（$criterion））

#if（$result）

Querywassuccessful

#end

#end

在上面的例子中，程序将不能智能的根据$result的值决定查询是否成功。

在$result被#set后（addedtothecontext），它不能被设置回null（removedfromthecontext）。

打印的结果将显示两次查询结果都成功了，但是实际上有一个查询是失败的。

为了解决以上问题我们可以通过预先定义的方式：

#set（$criteria=