velocity 手册 1
1. 关于<o:p></o:p>
<o:p></o:p>
Velocity 用户指南旨在帮助页面设计者和内容提供者了解Velocity 和其简单而又强大的脚本语言（Velocity Template Language (VTL)）。本指南中有很多示例展示了用Velocity来讲动态内容嵌入到网站之中，但是所有的VTL examples 都同演示用于所有的页面和模版。<o:p></o:p>
感谢选择Velocity!<o:p></o:p>
<o:p></o:p>
2. 什么是Velocity?<o:p></o:p>
Velocity 是一个基于Java的模版引擎。它允许web 页面设计者引用JAVA代码预定义的方法。Web 设计者可以根据MVC模式和JAVA程序员并行工作，这意味着Web设计者可以单独专注于设计良好的站点，而程序员则可单独专注于编写底层代码。 Velocity 将Java 代码从web页面中分离出来，使站点在长时间运行后仍然具有很好的可维护性，并提供了一个除JSP和PHP之外的可行的被选方案。 <o:p></o:p>
Velocity可用来从模板产生web 页面，SQL, PostScript以及其他输出。他也可用于一个独立的程序以产生源代码和报告，或者作为其它系统的一个集成组件。这个项目完成后，Velocity将为Turbine web 应用程序框架提供模板服务。Velocity+Turbine 方案提供的模板服务将允许web 应用按真正的mvc模式进行开发。<o:p></o:p>
<o:p></o:p>
3. Velocity 可以做什么? <o:p></o:p>
3.1. Mud Store 示例 <o:p></o:p>
假设你是一个专门销售泥浆（MUD） 的在线商店的页面设计者。我们称他为"The Online Mud Store"。生意很好。客户订购各种各样的类型和数量的泥浆。他们使用他们的用户名和密码登陆到商店中来，就可以浏览他们的订货和购买其他东西。现在， 赤土陶泥正在促销，这是一种很常用的泥巴。一少部分顾客很有规律的购买一种亮红土Bright Red Mud，这也是促销产品，但是不太常用，因此被移到页面的边缘。所有顾客的信息都在数据库中被跟踪，因此有一天问题出现了： 为什么不使用Velocity来定位目标客户，这些客户对某种类型的产品特别感兴趣？ <o:p></o:p>
Velocity 使针对访问者个性的WEB页面客户化（个性化）非常容易。作为一个在线泥巴商店的站点设计者，以想在客户以登陆进展点后就看到它们想看的页面。 <o:p></o:p>
你遇到你公司的软件工程师，每个人都认为$customer 将保持当前登陆进入的客户信息，而$mudsOnSpecial 将士当前所有促销的泥巴。$flogger 对象包含有助于促销的方法。对于当前的任务，让我们仅关注这三个问题。记住，你不需要担心软件工程师如何从数据库中取得顾客信息，但你必须知道他们可以。这样可以使你专注于你的工作而软件工程师则忙于他们自己的工作。<o:p></o:p>
你可以在你的页面中嵌入如下的VTL语句：<o:p></o:p>
| <HTML><o:p></o:p> <BODY><o:p></o:p> Hello $customer.Name!<o:p></o:p> <table><o:p></o:p> #foreach( $mud in $mudsOnSpecial )<o:p></o:p> #if ( $customer.hasPurchased($mud) )<o:p></o:p> <tr><o:p></o:p> <td><o:p></o:p> $flogger.getPromo( $mud )<o:p></o:p> </td><o:p></o:p> </tr><o:p></o:p> #end<o:p></o:p> #end<o:p></o:p> </table><o:p></o:p> |
<o:p></o:p>
foreach 语句的细节将进一步细说，但重要的是这个短小的脚本居然可以在你的站点上运行。当有一个倾向于亮红土的顾客登陆进来时，亮红土正在促销，这就是这个顾客所 看到的，并且促销显示非常显著。如果另外一个长期购买赤陶土的顾客登陆进来，赤陶土促销的提示信息则应该在前面中间位置。Velocity是非常灵活的， 受限的只是你的创造力。 <o:p></o:p>
写在VTL参考文档中的是其他Velocity 元素，他们一起给你很强大的能力和灵活性以创建很好的站点。待你更加了解这些元素，就可以开始释放Velocity的强大动力。 <o:p></o:p>
4. Velocity模板语言(VTL): 介绍<o:p></o:p>
Velocity模板语言(VTL)旨在为Web页面结合动态内容提供最容易、简单和简洁的方法。即使有一点或者没有编程经验的页面设计者也可以很快能为页面提供动态内容。 <o:p></o:p>
VTL 使用引用（references ）来将动态内容嵌入web页面，每个变量就是某一个类型的引用。变量实际上是一个可以调用定义在java代码中的内容的引用，或者它可以从页面内的VTL语句得出自身的值。下面是一个例子，说明可以嵌入到HTML文档中的VTL语句。<o:p></o:p>
| <o:p></o:p> #set( $a = "Velocity" ) <o:p></o:p> <o:p></o:p> |
<o:p></o:p>
这个VTL语句，就像所有的VTL语句一样，以 # 字符开始，并跟着一个指令set。 当一个在线访问这请求页面时， Velocity 模伴引擎在页面内搜索所有# 字符，然后决定是哪一个标记了VTL语句的开始，哪个标记不需要VTL做什么动作。<o:p></o:p>
<o:p></o:p>
# 字符后面紧跟一个指令 set.。set 指令使用一个括在括号内的表达式---一个等式将一个值指派给一个变量。变量在等号的左边而值在等号的右边。<o:p></o:p>
<o:p></o:p>
在上面的示例中，变量是 $a 值是Velocity。 这个变量就象其他引用一样，以一个$字符开始。值通常在引号之中，对Velocity来说一般没有类型冲突的问题，因为只有字符串 (基于文本的信息)可以传递给变量。<o:p></o:p>
<o:p></o:p>
下面的主要规则可能有助于理解Velocity 是如何工作的：引用以$开头用于取得什么东西，而指令以# 开始用于做什么事情。<o:p></o:p>
在上面的例子中，#set 用于将一个值指派给一个变量。而变量$a 则可以用来在模板中输出"Velocity" 。 <o:p></o:p>
5. Hello Velocity World!<o:p></o:p>
一旦一个值被赋给一个变量，便可以在HTML中随处引用它。在下面的示例中，先给变量$foo 赋值然后引用它。<o:p></o:p>
| <html><o:p></o:p> <body><o:p></o:p> #set( $foo = "Velocity" )<o:p></o:p> Hello $foo World!<o:p></o:p> </body><o:p></o:p> <html><o:p></o:p> |
<o:p></o:p>
这个页面的结果是输出"Hello Velocity World!"。 <o:p></o:p>
为了使包含VTL 指令的语句具有可读性，我们鼓励每个VTL语句在一个新行开始，虽然并不一定要这样做。 set 将随后深入解释。<o:p></o:p>
<o:p></o:p>
6. 注释<o:p></o:p>
可以用注释加入描述性文本，他们并不在模板引擎中输出。注释可以有助于你的记忆或者想其他人解释你的VTL语句正在做什么。<o:p></o:p>
| ## This is a single line comment.<o:p></o:p> |
<o:p></o:p>
单行注释以## 开始，并在本行结束。如果需要加入多行注释，并不需要加入很多的单行注释。多行注释，以#* 开始并以*#结束可以处理这种情况。<o:p></o:p>
| This is text that is outside the multi-line comment.<o:p></o:p> Online visitors can see it.<o:p></o:p> <o:p></o:p> #*<o:p></o:p> Thus begins a multi-line comment. Online visitors won't<o:p></o:p> see this text because the Velocity Templating Engine will<o:p></o:p> ignore it.<o:p></o:p> *#<o:p></o:p> <o:p></o:p> Here is text outside the multi-line comment; it is visible.<o:p></o:p> |
<o:p></o:p>
<o:p></o:p>
下面事一些例子说明单行注释和多行注释如何工作。<o:p></o:p>
| This text is visible. ## This text is not.<o:p></o:p> This text is visible.<o:p></o:p> This text is visible. #* This text, as part of a multi-line comment,<o:p></o:p> is not visible. This text is not visible; it is also part of the<o:p></o:p> multi-line comment. This text still not visible. *# This text is outside<o:p></o:p> the comment, so it is visible.<o:p></o:p> ## This text is not visible.<o:p></o:p> |
<o:p></o:p>
还有第三种注释， VTL 注释块，可以用来存储诸如文档作者、版本信息等。<o:p></o:p>
<o:p></o:p>
| #**<o:p></o:p> This is a VTL comment block and<o:p></o:p> may be used to store such information<o:p></o:p> as the document author and versioning<o:p></o:p> information:<o:p></o:p> @author<o:p></o:p> @version 5<o:p></o:p> *#<o:p></o:p> |
<o:p></o:p>
7. 引用<o:p></o:p>
VTL中有三种类型的引用：变量，属性和方法。作为使用VTL的设计者，你和你的工程师必须在饮用的特定命名上取得一致，以便在你的模板中正确的使用他们。<o:p></o:p>
<o:p></o:p>
有关引用的所有参数都处理为字符串对象。Everything coming to and from a reference is treated as a String object. 假如有一个对象表示$foo (比如说是整型对象)，Velocity 将调用其toString() 方法来将此对象转换为一个字符串。<o:p></o:p>
7.1. 变量Variables<o:p></o:p>
变量的简略标记是有一个前导"$"字符后跟一个 VTL 标识符（Identifier.）组成。一个VTL 标识符必须以一个字母开始(a .. z或 A .. Z)。剩下的字符将由以下类型的字符组成： <o:p></o:p>
字母 (a .. z, A .. Z) <o:p></o:p>
数字 (0 .. 9) <o:p></o:p>
连字符("-") <o:p></o:p>
下划线 ("_") <o:p></o:p>
下面是一些有效的变量引用:<o:p></o:p>
| $foo<o:p></o:p> $mudSlinger<o:p></o:p> $mud-slinger<o:p></o:p> $mud_slinger<o:p></o:p> $mudSlinger1<o:p></o:p> |
<o:p></o:p>
当VTL 引用一个变量时，比如$foo，变量可以从模板的set 指令取得值，也可以从<o:p></o:p>
Java 代码中取得。例如，如果Java 变量 $foo 在模板被请求的时候具有值bar ，则bar 将替换页面中的所有$foo 的实例。或者，如果包含下面的语句： <o:p></o:p>
| #set( $foo = "bar" )<o:p></o:p> |
<o:p></o:p>
紧跟指令后的所有$foo 的实例的输出将会一样值。<o:p></o:p>
7.2. 属性<o:p></o:p>
VTL引用的第二种元素是属性，而属性具有独特的格式。属性的简略标记识前导符$ 后跟一个VTL 标识符，在后跟一个点号(".")最后又是一个VTL 标识符。这是一些有效的示例： <o:p></o:p>
| $customer.Address<o:p></o:p> $purchase.Total<o:p></o:p> |
<o:p></o:p>
请看第一个例子， $customer.Address.。他有两种意思。 它可以意味着，查询由customer 标是的哈希表并按关键字Address返回值。但是 $customer.Address 也可能引用一个方法（下述，$customer.Address 可能是$customer.getAddress().的缩写。当一个页面被请求时，Velocity 将决定这两种可能到底是哪一个，然后返回相应的值。 <o:p></o:p>
7.3. 方法<o:p></o:p>
方法在JAVA代码中定义，并作一些有用的事情，比如运行一个计算器或者作出一个决定。方法是实际上也是引用，由前导符"$"后跟一个VTL 标识符，后跟一个VTL 方法体（Method Body）。 VTL 方法体由一个VTL 标识符后跟一个左括号，再跟可选的参数列表，最后是右括号。下面是一些有效的方法示例：<o:p></o:p>
<o:p></o:p>
| $customer.getAddress()<o:p></o:p> $purchase.getTotal()<o:p></o:p> $page.setTitle( "My Home Page" )<o:p></o:p> $person.setAttributes( ["Strange", "Weird", "Excited"] )<o:p></o:p> |
<o:p></o:p>
前面两个例子-- $customer.getAddress() 和 $purchase.getTotal() – 看起来有点象上面属性一节中所用的样子， $customer.Address 和 $purchase.Total.。如果你想这些例子在某些方面相关，那你就对了。<o:p></o:p>
<o:p></o:p>
VTL 属性可以为VTL方法用作简略标记。属性$customer.Address 具有和方法$customer.getAddress() 完全一样的效果。属性和方法的主要不同点是方法中可以添加参数列表。<o:p></o:p>
简略标记可以用在下面的方法中：<o:p></o:p>
| sun.getPlanets()<o:p></o:p> $annelid.getDirt()<o:p></o:p> $album.getPhoto()<o:p></o:p> |
<o:p></o:p>
我们或许希望方法可以为我们放回属于太阳系的行星的名字，喂养我们的蚯蚓，或者从相册中返回一张照片。下面只有长的那个标记是可以工作的方法：<o:p></o:p>
| $sun.getPlanet( ["Earth", "Mars", "Neptune"] )<o:p></o:p> ## 不能将参数列表传递给$sun.Planets<o:p></o:p> <o:p></o:p> $sisyphus.pushRock()<o:p></o:p> ## Velocity 假定我意思是$sisyphus.getRock()<o:p></o:p> <o:p></o:p> $book.setTitle( "Homage to Catalonia" )<o:p></o:p> ## 不能传递一个参数列表<o:p></o:p> <o:p></o:p> |
7.4. 形式引用符Formal Reference Notation<o:p></o:p>
引用的简略符号如上所述，但是另外还有一种引用的形式符号，示例如下：<o:p></o:p>
| ${mudSlinger}<o:p></o:p> ${customer.Address}<o:p></o:p> ${purchase.getTotal()}<o:p></o:p> |
<o:p></o:p>
在大多数情况下，我们将使用引用的简略符号，但在一些情况下，也需要拥戴哦形式引用符以便正确处理。 <o:p></o:p>
假定你正在纸片上构件一个句子，将使用$vice 作为句子中名词的词根。我们的目标是允许人们选择词根，然后产生以下两种结果之一：<o:p></o:p>
"Jack is a pyromaniac."<o:p></o:p>
或者 "Jack is a kleptomaniac."。<o:p></o:p>
在这种情况下，使用简略符号是不太充分的。考虑到下面的例子：<o:p></o:p>
| Jack is a $vicemaniac.<o:p></o:p> |
<o:p></o:p>
<o:p></o:p>
这里有个不确定性， Velocity 假定 $vicemaniac，（而不是 $vice） 是一个你想要使用的标识符。 找不到$vicemaniac的值，他将返回$vicemaniac。使用形式符号便可解决这个问题：<o:p></o:p>
| Jack is a ${vice}maniac<o:p></o:p> |
现在Velocity 知道 $vice（而不是 $vicemaniac） 是一个引用。形式符号常用在饮用咋模板中和文本直接邻近的地方。<o:p></o:p>
<o:p></o:p>
7.5. 安静引用符Quiet Reference Notation<o:p></o:p>
当 Velocity 遇到一个位定义的引用时，其通常行为是输出这个引用的映像。比如，假设下面的引用出现在模板中的一部分：<o:p></o:p>
| <input type="text" name="email" value="$email"/><o:p></o:p> |
当表单初次装入时，变量引用$email 无值，你宁愿是一个空白域而不是具有值"$email"。使用安静引用符可以绕过Velocity的常规行为，在VTL中不用$email 而是用$!email 符号。 所以，上面的例子将会看起来像下面的样子：<o:p></o:p>
| <input type="text" name="email" value="$!email"/><o:p></o:p> |
现在，当表单初次装入时， $email 仍然没有值，但是将输出空字符串而不是"$email"。<o:p></o:p>
<o:p></o:p>
形式和安静引用符可以一起使用，如下所示：<o:p></o:p>
| <input type="text" name="email" value="$!{email}"/><o:p></o:p> |
1. 取得语义Getting literal<o:p></o:p>
VTL 特别的字符，比如$ 和 #， 来做这个工作，因此在模板中使用这些自负的时候必须格外小心。本节讲述$ 的转义。<o:p></o:p>
1.1. 货币<o:p></o:p>
我们写下句子 "I bought a 4 lb. sack of potatoes at the farmer's market for only $2.50!" ，这并没有什么问题。但如前所述，VTL标识符总是以大写或是小写字母开始，所以$2.50 在引用中将不能出错。<o:p></o:p>
1.2. 转义有效的VTL 引用<o:p></o:p>
问题将会出现，因为Velocity 将有一个潜在的冲突。转义特殊字符是处理VTL模板种特殊字符的最好的办法，者可以用一个反斜线来进行。<o:p></o:p>
| foo<o:p></o:p> $email<o:p></o:p> \foo<o:p> |