Velocity用户手册

亚瑟王 2022-04-19 574 Java

Velocity 是什么？

Velocity 是一个基于 java 的模板引擎（template engine）。它允许任何人仅仅简单的使用模板语言（template language）来引用由 java 代码定义的对象。当 Velocity 应用于 web 开发时，界面设计人员可以和 java 程序开发人员同步开发一个遵循 MVC 架构的 web 站点，也就是说，页面设计人员可以只关注页面的显示效果，而由 java 程序开发人员关注业务逻辑编码。Velocity 将 java 代码从 web 页面中分离出来，这样为 web 站点的长期维护提供了便利，同时也为我们在 JSP 和 PHP 之外又提供了一种可选的方案。Velocity 的能力远不止 web 站点开发这个领域，例如，它可以从模板（template）产生 SQL 和 PostScript、XML，它也可以被当作一个独立工具来产生源代码和报告，或者作为其他系统的集成组件使用。Velocity 也可以为Turbine web 开发架构提供模板服务（template service）。Velocity+Turbine提供一个模板服务的方式允许一个 web 应用以一个真正的 MVC 模型进行开发。

Velocity 能为我们作什么？

Mud 商店例子

假设你是一家专门出售 Mud 的在线商店的页面设计人员，让我们暂且称它为“在线 MUD 商店”。你们的业务很旺，客户下了各种类型和数量的 mud 订单。他们都是通过输入用户名和密码后才登陆到你的网站，登陆后就允许他们查看订单并购买更多的 mud。现在，一种非常流行的 mud 正在打折销售。另外有一些客户规律性的购买另外一种也在打折但是不是很流行的 Bright Red Mud，由于购买的人并不多所以它被安置在页面的边缘。所有用户的信息都是被跟踪并存放于数据库中的，所以某天有一个问题可能会冒出来：为什么不使用 velocity 来使用户更好的浏览他们感兴趣的商品呢？Velocity 使得 web 页面的客户化工作非常容易。作为一个 web site 的设计人员，你希望每个用户登陆时都拥有自己的页面。你会见了一些公司内的软件工程师，你发现他们每个人都同意客户应该拥有具有个性化的信息。那让我们把软件工程师应该做的事情发在一边，看一看你应该做些什么吧。

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

<HTML>

<BODY>

Hello $customer.Name! <table>

#foreach( $mud in $mudsOnSpecial )

#if ( $customer.hasPurchased($mud) )

<tr>

<td>

$flogger.getPromo( $mud )

</td>

</tr>

#end

</table>

foreach 的详细用法不久就会进行深入描述。重要的是，这短小的脚本能在你的网站上出现。当一个对 Bright Red Mud 很感兴趣的顾客登陆的时候，同时Bright Red Mud 在热卖中，这时顾客就能显著地看到。假如一个玩 Terracotta Mud很久的顾客登陆，Terracotta Mud 的售卖信息就会出现在前面中间。Velocity的适用性是很巨大的，限制的只是你的创造性。VTL Reference 含有许多其他 Velocity 元素，这些元素能够共同帮助你，使你的网站更加好。当你越来越熟悉那些原理，你开始释放 Velocity 的能力。

Velocity 模板语言(VTL):说明

VTL 意味着提供最简单、最容易并且最整洁的方式合并页面动态内容。VTL使用 references 来在 web site 内嵌套动态内容，一个变量就是一种类型的reference。变量是某种类型的 reference，它可以指向 java 代码中的定义，或者从当前页面内定义的 VTL statement 得到值。下面是一个 VTL statement 的例子，它可以被嵌套到 HTML 代码中：

#set( $a = "Velocity" )

和所有的 VTL statement 一样，这个 statement 以＃字符开始并且包含一个directive：set。当一个在线用户请求你的页面时，Velocity 模板引擎将查询整个页面以便发现所有＃字符，然后确定哪些是 VTL statement，哪些不需要 VTL做任何事情。

＃字符后紧跟一个 directive：set 时，这个 set directive 使用一个表达式（使用括号封闭）――一个方程式分配一个值给变量。变量被列在左边，而它的值被列在右边，最后他们之间使用＝号分割。在上面的例子中，变量是$a，而它的值是 Velocity。和其他的 references一样以$字符开始，而值总是以双引号封闭。Velocity 中仅有 String 可以被赋值给变量。

使用$字符开始的 references 用于得到什么；使用#字符开始的 directives用于做些什么。在上面的例子中,#set 是分配一个值给变量。变量$a 在模板中输出 "Velocity"。

Hello Velocity World!

一旦某个变量被分配了一个值，那么你就可以在 HTML 文件的任何地方引用它。在下面的例子中，一个值被分配给$foo 变量，并在其后被引用。

#set( $foo = "Velocity" )

Hello $foo World!

</body>

<html>

上面的实现结果是在页面上打印“Hello Velocity World！”为了使包含 VTL directives 的 statement 更具有可读性，我们鼓励你在新行开始每个 VTL statement，尽管你不是必须这么做。Set 的用法将在后面详细描述。

注释

注释是那些描述文本不出现在模板引擎输出里面。注释一个主要用处是提醒自己和解释出现在 VTL 中的声明，或是其他用途。下面是一个在 VLT 中的注释例子。

## This is a single line comment.

单行注释以##开始，结束在这行的结尾。如果你要写几行注释，这没有必要写几个单行注释。多行注释，以#*开始*#结束，可以解决这个问题。

This is text that is outside the multi-line comment.

Online visitors can see it.

Thus begins a multi-line comment. Online visitors won't

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 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.

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

#**

This is a VTL comment block and

may be used to store such information

as the document author and versioning

information:

@author @version 5

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" )按照这样的设置，输出就会跟之前的一样。

属性

第二种有趣的 VTL reference 就是属性，而且属性有一种与众不同的格式。非正式变量是由“$”开头，接着是 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( "My Home Page" )

$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()

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