基于Java的模板框架-Velocity(2)

来源：互联网发布：淘宝客服的重要性编辑：程序博客网时间：2024/04/23 23:34

Hello Velocity World!

当一个变量被赋值后，你可以在你的HTML文档中的任何位置引用它。在下面的例子里，一个值被赋予了$foo并且在后面被引用。

<html><body>#set( $foo = "Velocity" )Hello $foo World!</body><html>

结果是这个web页面打印出"Hello Velocity World!"。

为了提高包含VTL指令的声明的可读性，我们建议你对每一个TVL声明都另起新行，虽然你不是一定要这么做。关于set指令，稍后将进行更加深入阐述。

注释

注释可以用来填写不需要通过模板引擎输出的文本。注释是一种有用的方法，用来向你自己和别人解释你的VTL声明将要干什么的，或者是你找到的其他有益用途。下面是一个VTL注释的例子：

## 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-linecomment, is not visible. This text is not visible; it is alsopart of the multi-line comment. This text still notvisible. *# This text is outside the comment, so it is visible.## This text is not visible.

还有第三种注释，即VTL注释块，可以用来存储任何你想做模板中记录的任何额外信息（比如java文档风格的作者与版本信息）：

#**This is a VTL comment block andmay be used to store such informationas the document author and versioninginformation:@author@version 5*#

引用

在VTL中有三种引用：变量(variables)、属性(properties)和方法(methods)。作为一个使用VTL的设计者，你和你的工程师们必须就引用的命名达成一致，以使你们可以在模板中正确使用他们。

变量（Variables）

变量的简名由一个以"$"符号开头的VTL标识符组成，一个VTL标识符必须以英文字母(a...z 以及A..Z)开头，其它的字符仅限如下几种：

- 英文字母（a..z以及A ..Z)
- 数字(0....9)
- 连字符(-)
- 下划线(_)

这里有一些有效VTL变量名：

$foo$mudSlinger$mud-slinger$mud_slinger$mudSlinger1

当VTL引用了一个变量，比如$foo，这个变量就可以通过模板中的set指令和java代码获取值。例如，在模板被请求的时候，假如java变量$foo拥有了值bar,bar将覆盖页面中所有的$foo实例。或者，通过如下方式赋值：

#set( $foo = "bar" )

在此指令后的所有$foo实例都输出同样的结果。

属性(Proterties)

第二种VTL风味是属性，属性有一个特殊的格式。他的简名由$ 符号开头并紧跟着一个VTL标识符，之后再跟着一个点号(“.”)和另一个VTL标识符。下面是几个有效的VTL属性引用：

$customer.Address$purchase.Total

第一个例子：$customer.Address.它可以有两种意思。它可以认为是，从一个命名为customer的哈希表(hashtable)中查找并返回与键Address关联的值。除此之外，$customer.Address也可以表示一个方法（关于的方法的详细描述在下一节中讨论）；$customer.Address能看成$customer.Address()的简写方式。当你的页面被请求的时候，Velocity将确认这两种可能中哪种更合理，并返回适当的值。

方法(Method)

方法是指在java代码中定义，能够做一些像执行计算或者作出决定之类的有用的事情。方法使用一个以"$"符号开头，后跟一个VTL标识符，后面再跟着一个VTL方法体来声明。一个VTL方法体由一个VTL标识符+左括弧("(")+可选的参数列表+右括弧(")")组成。下面是几个有效方法声明的例子：

$customer.getAddress()$purchase.getTotal()$page.setTitle( "My Home Page" )$person.setAttributes( ["Strange", "Weird", "Excited"] )

前两个例子 -- $customer.getAddress() 和 $purchase.getTotal() -- 看上去很像上面讲属性的小节里使用过的$customer.Address and $purchase.Total。假如你猜到了这些例子一定会以各种风格讲述，那你就对了。

VTL属性能作为VTL方法的简写使用，属性$customer.Address与方法$customer.getAddress()执行结果完全相同，通常更多地是使用属性。属性和方法的主要区别是在方法中你可以指定自己的参数列表。

下列方法也可以使用简写：

$sun.getPlanets()$annelid.getDirt()$album.getPhoto()

我们可以认为这些方法可以返回属于太阳的行星的名字、喂养我们的蚯蚓，或者获得一张来自影集的照片。下列方法只有非简写才能工作：

$sun.getPlanet( ["Earth", "Mars", "Neptune"] )## 使用 $sun.Planets 不能输入一个参数列表$sisyphus.pushRock()## Velocity 把以为我要的是 $sisyphus.getRock()$book.setTitle( "Homage to Catalonia" )## 简写不能指定参数

从Velocity1.6开始，所有具有固定长度的数组引用现在都经过了“魔法”处理。这就意味着你可以对任何数组引用调用java.util.List的方法。那么，假如你有一个指向一个数组(让我们认为它是一个有三个值的String[])的引用，你可以这么做：

$myarray.isEmpty()$myarray.size()$myarray.get(2)$myarray.set(1, 'test')

此外，新的Velocity1.6支持的"vararg"方法。一个方法，像public void setPlants(String ... planets)或者甚至如public void setPlanets(String[] planets)(假如你使用JDK5之前的版本),现在在模板中调用的时候可以接受任意多个参数。

$sun.setPlanets('Earth', 'Mars', 'Neptune')$sun.setPlanets('Mercury')$sun.setPlanets()## Will just pass in an empty, zero-length array

属性查找规则

前面曾提到过，属性通常指向父对象的方式。Velocity在计算对一个请求使用哪个方法方面很机灵。它会基于几个确定的命名规则去尝试多种选择。恰当的查找顺序依赖于这个属性名称是否使用大写字母开头。对于小写字母开头的名称，比如$customer.address,顺序为：

1.getaddress()

2.getAddress()

3.get("address")

4.isAddress()

而对于大写字母开头的属性名字，像$customer.Address,稍微有点不同：

1.getAddress()

2.getaddress()

3.get("Address")

4.isAddress()

渲染

每一个引用（无论是变量、属性，或者方法）当它被渲染成最终输出的时候，产生的最后值都是字符串对象。假如有一个对象代表着$foo（比如一个整数对象Integer object），然后Velocity将调用它的.toString()方法来把对象转换成一个字符串。

正式引用符号

上面例子中使用的都是引用的简写方式，但也有正式的引用符号，下面是几个范例。

${mudSlinger}${customer.Address}${purchase.getTotal()}

几乎所有的案例中你都是使用引用的简写符号，但在一些特殊的案例中为了正确执行必须使用正式符号。

假设你没事正在构建一个句子，这个句子的名词中，$vice是作为一个基区字使用的。目的是允许有人选择基区词来构建下列两种结果之一："Jack is a pyromaniac."与"Jack is a Kleptomaniac."。对这个任务使用使用简写是不适当的。考虑下面的例子：

Jack is a $vicemaniac.

现在Velocity只知道$vice是一个引用，而不知道$vicemaniac。当模板中的引用直接和文本相邻时，正式引用通常更有用。

静引用符号

当Velocity遇到一个未定义的引用是，它正常的行为是输出该引用的“形象”。例如，假如下面的引用出现在VTL模板中：

当表单开始加载的时候，变量$email还没有值，但你却希望得到的是一个空白文本框，而不是一个值为"$email"的文本框。使用“静引用符号”来规避Velocity的常规行为，即把$email替换成$!email。所以上面的例子应写成下面的样子：

现在当表啊开始加载的时候，并且$email仍旧没有值，一个空洞字符串替代了"$email"输出。

正式引用符号和静引用符号可以一起使用，如下所示：

（未完待续）

原文地址：[http://velocity.apache.org/engine/devel/user-guide.html#Hello_Velocity_World]