《Velocity用户手册》-第八章

第8章 引用References

VTL中有三种类型的引用：变量，属性和方法。作为VTL的使用者，你必须做到一些特定名称的命名一致性，以便在模板中正常使用。

8.1 变量Variables

变量的简略标记是由一个前导"$"字符后面跟一个 VTL 标识符（Identifier）组成。一个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 的实例的都将会输出定义的值。

8.2 属性Properties

VTL引用的第二种元素是属性，而属性具有独特的格式。属性的简略标记是前导符$后跟一个VTL标识符，加一个点号(".")后再跟一个VTL 标识符。以下为例子：

$customer.Address
$purchase.Total

首先看第一个例子，$customer.Address它有两种意思。它可以表示查询有customer 标识的哈希表然后返回关键字为Address的值。但是$customer.Address也可能是调用一个方法（如何调用方法的参考例子将会在下个章节讨论）$customer.Address 可能是$customer.getAddress()的缩写。当页面请求时，Velocity将判断是上述哪种情况，然后返回相应的值。

8.3 方法Methods

方法在JAVA代码中所定义，并实现一些功能，比如运行一个计算器或者进行判断。方法实际上也是一种引用，由前导符"$"后跟一个VTL 标识符，然后再跟一个VTL 方法体（Method Body）。VTL 方法体由一个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()

我们可能想要从太阳系中取出所有行星的名字，喂蚯蚓，或者从相册中获取照片。下面的方法中，只有最长的那个方法是可以运行的：

 $sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## 不能将参数列表传递给 $sun.Planets
 $sisyphus.pushRock()
## Velocity 会认为$sisyphus.getRock()
 $book.setTitle( "Homage to Catalonia" )
## 不能传递一个参数列表

在Velocity1.6中，所有的数列引用都可以很神奇的用固定长度的列表来表示。这样的话，你可以使用调用java.util.List方法来表示数列。假设你对一个数列进行引用（假设数列String[ ]中有3个值），你可以这样做：

$myarray.isEmpty()

$myarray.size()

$myarray.get(2)

$myarray.set(1, 'test')

在Velocity 1.6中，开始有了支持vararg的方法。比如下面的方法： public void setPlanets(String... planets)或者public void setPlanets(String[] planets)（JDK1.5版本之前），现在你就可以在模版中无限的传入参数了。

$sun.setPlanets('Earth', 'Mars', 'Neptune')

$sun.setPlanets('Mercury')

$sun.setPlanets()
## 将会将列表置空,返回一个长度为0的数组

8.4 属性查找规则Property Lookup Rules

之前也已经提过，属性也可以表示对象的方法。Velocity基于不同的命名规则采用合适的策略，可以依据请求的属性项，来找出所匹配的方法。当前查找是依据属性值的首字母的大小写进行排序的。比如属性值的首字母是小写的： $customer.address，排列如下

1. getaddress()
2. getAddress()
3. get("address")
4. isAddress()

比如属性值的首字母是大写的，比如：$customer.Address会有略微的不同：

1.         getAddress()

2.         getaddress()

3.         get("Address")

4.         isAddress()

8.5 转换Rendering

有关引用的所有参数（无论是变量，属性，方法）都转换成字符串，假如一个$foo对象（整型），Velocity将会调用.toString()方法将此对象转换成字符串。

8.6 索引符号Index Notation

像$foo[0]这样的标识，可以从对象中取得需要索引的值。这样的方式其实和调用get(Object)方法是一样的，等同于$foo.get(0)，这样本质上提供了一种简便的方法。以下是用这种简便方法的例子。

$foo[0]       ## $foo 用数字索引查找
$foo[$i]      ## 通过其它引用索引
$foo["bar"]   ## $foo 可能为一个Map，通过一个字符串在Map表里查找

自从Velocity 包装过的数组可以通过get(Integer)方法从对象中获取特定的元素后，使得这类语法可以在Java数组中使用。

       这类语法随处可见，.get 也是可用的，以下为示例：

$foo.bar[1].junk
$foo.callMethod()[1]
$foo["apple"][4]

引用同样可以通过索引符号来赋值：以下为示例：

#set($foo[0] = 1)
#set($foo.bar[1] = 3)
#set($map["apple"] = "orange")

指定的元素会被赋值。Velocity首先会找到元素调用‘set’方法，然后再进行赋值。

8.7 正式引用符号Formal Reference Notation

以上是引用中的简洁表达符的介绍，下面来介绍引用中正式表达符。示例如下：

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

多数情况下，简洁表达符足以满足使用了，但是在特定情况下，还是需要使用正式表达符。

       假设你要造一个句子，句子中一定要包括$vice这个基础词，要实现的目标是用户可以使用这个基础词，生成"Jack is a pyromaniac." 或者"Jack is a kleptomaniac."的其中一句，若使用简洁表达符将会比较难以实现，看看下面的例子：

Jack is a $vicemaniac.

这样就出现问题了，Velocity将会去找的是$vicemaniac，而不是我们设定的基础词 $vice，这样就会找不到相应的值，直接就返回$vicemaniac了。使正式引用符就可以解决这样的问题。

Jack is a ${vice}maniac.

这样Velocity就知道你要找的是 $vice，而不是$vicemaniac，正式表达符一般用于在模版中存在相互连接的文本字段。

8.8 隐藏引用符号Quiet Reference Notation

当Velocity遇到一个不能识别的引用时，一般就会直接输出这个引用的写法。假设，下面的例子是一个VTL模版中的一个段落。

<input type="text" name="email" value="$email"/>

当模版被加载，如果变量$email 值为空，你希望输出的是空白内容而不是"$email"这样一串字符。这时，可以使用隐藏使用符号，只要将$email 改成$!email就可以了。例子如下：

<input type="text" name="email" value="$!email"/>

这样的话，当模版被加载后，如果 $email 是空值的话，输出的话将是空白内容。

正式引用符号和隐藏引用符号可以一起使用，如下：

<input type="text" name="email" value="$!{email}"/>