Velocity教程

简介

Apache Velocity 是一个基于java的模板引擎（template engine）。它允许任何人仅仅简单的使用模板语言（template language）来引用由java代码定义的对象。

应用场景

1. Web 应用：开发者在不使用 JSP 的情况下，可以用 Velocity 让 HTML 具有动态内容的特性
2. 源代码生成：Velocity 可以被用来生成 Java 代码、SQL 或者 PostScript
3. 自动 Email：很多软件的用户注册、密码提醒或者报表都是使用 Velocity 来自动生成的
4. 转换 xml

语法概要

在 Velocity 中所有的关键字都是以#开头的，而所有的变量则是以$开头。下面为具体语法规则。

注释

单行注释

 这是单行注释 

多行注释

#* Thus begins a multi-line comment. Online visitors won’t see this text because the Velocity Templating Engine will ignore it. *# 

文档格式

# This is a VTL comment block and may be used to store such information as the document author and versioning information: @version 1.1 @author xiao *# 

变量

在Velocity中也有变量的概念，使用$符声明变量，可以声明变量也可以对变量进行赋值(变量是弱类型的)。另外还可以使用$取出在VelocityContext容器中存放的值

#set(${!name} = "velocity") string #set(${!foo} = $bar) variable reference #set($foo =“hello”) string #set($foo.name = $bar.name) property reference #set($foo.name = $bar.getName($arg)) method reference #set($foo = 123) number #set($foo = [“foo”,$bar]) ArrayList 

注意变量定义语句为#set( $)，获取时需要加

模板文件可以使用name或name或{name}定义变量，建议使用后者，name和name和names 的两个变量，如果不选用大括号的话，引擎就没有办法正确识别$names 这个变量。

需要注意，上面代码中 $!的写法，使用$vari获取变量时，如果变量不存在，Velocity引擎会将其原样输出，通过使用$!的形式可以将不存在的变量变成空白输出.推荐使用$!{}写法

循环

在Velocity中可以使用循环语法遍历集合，语法结构如下：

#foreach($item in $list) $item $velocityCount #end 

其中，$item代表遍历的每一项，velocityCount是Velocity提供的用来记录当前循环次数的计数器，默认从1开始计数，可以在velocity.properties文件中修改其初始值

语句的嵌套

#foreach ($element in $list) inner foreach 内循环 #foreach ($element in $list) This is $element. $velocityCount 
inner
 #end inner foreach 内循环结束 outer foreach This is $element. $velocityCount 
outer
 #end 

语句中也可以嵌套其他的语句，如#if…#else…#end等。

条件控制语法

在Velocity中可以使用条件语法对流程进行控制

#if(condition) ...dosonmething... #elseif(condition) ...dosomething... #else ...dosomething... #end 

例如

#if($iAmVariable == "goo00d!") #set($iAmVariable = "goodddd!") $!iAmVariable #else #set($iAmVariable = "goonnnnnn") $!iAmVariable #end 

宏

在Velocity中也有宏的概念，可以将其作为函数来理解，使用#macro声明宏

①宏的定义

#macro(宏的名称 $参数1 $参数2 …) 语句体(即函数体) #end 

②宏的调用

#宏的名称($参数1 $参数2 …) 说明：参数之间用空格隔开。 

举例

 声明宏 #macro(sayHello $name) hello $name #end 使用宏 #sayHello("NICK") 

关系和逻操作符

Velocity 也具有逻辑AND, OR 和 NOT 操作符。

 example for AND #if($foo && $bar)This and that #end 

例子中#if() 指令仅在$foo和$bar 都为真的时候才为真。如果$foo 为假，则表达式也为假；并且 $bar 将不被求值。如果 $foo为真，Velocity模板引擎将继续检查$bar的值，如果 $bar 为真，则整个表达式为真。并且输出This AND that 。如果 $bar 为假，将没有输出因为整个表达式为假。

#stop

停止执行模板引擎并返回,把它应用于debug是很有帮助的。

#include与#parse

#include和#parse的作用都是引入本地文件, 为了安全的原因，被引入的本地文件只能在

TEMPLATE_ROOT目录下。

区别：

1. 与#include不同的是，#parse只能指定单个对象。而#include可以有多个

   如果您需要引入多个文件，可以用逗号分隔就行：

   #include (“one.gif”, “two.txt”, “three.htm” )

   在括号内可以是文件名，但是更多的时候是使用变量的：

   #include ( “greetings.txt”, $seasonalstock )

2. #include被引入文件的内容将不会通过模板引擎解析；

   而#parse引入的文件内容Velocity将解析其中的velocity语法并移交给模板，意思就是说

   相当与把引入的文件copy到文件中。

   #parse是可以递归调用的，例如：如果dofoo.vm包含如下行：

   那么在parsefoo.vm模板中，你可以包含如下VTL：

   $count

   #set($count = $count – 1)

   #end的显示结果为：

Count down. 8 7 6 5 4 3 2 1 0 All done with parsefoo.vm! All done with dofoo.vm! 

注意：在vm中使用#parse来嵌套另外一个vm时的变量共享问题。如：

->a.vm 里嵌套 b.vm；

->a.vm 里定义了变量 $param；

->b.vm 里可以直接使用$param，无任何限制。

但需要特别注意的是，如果b.vm里同时定义有变量$param，则b.vm里将使用b.vm里定义的值。

转义字符’’的使用

如果reference被定义，两个’\’意味着输出一个’\’，如果未被定义，刚按原样输出。

如：

#set($email = “foo” )

$email

$emai

l\$email

\$email

输出：

foo

$email

\foo

$email

如果$email 未定义

$email

$email

\$email

\$email

输出：

$email

$email

\$email

\$email

内置对象

Velocity内置了一些对象，在vm模版里可以直接调用，列举如下：

$request、$response、$session，另外，模板内还可以使用 $msg内的消息工

具访问 Struts 的国际化资源，达到简便实现国际化的方法。

数组访问

对数组的访问在Velocity中存在问题，因为Velocity只能访问对象的方法，而数组

又是一个特殊的Array，所以虽然数组可以进行循环列举，但却不能定位访问特定

位置的元素，如 strs[2]，数组对固定位置元素的访问调用了Array的反射方法

get(Object array, int index)，而Velocity没能提供这样的访问，所以数组要么改成

List等其他类容器的方式来包装，要么就通过公用Util类的方式来提供，传入数组

对象和要访问的位置参数，从而达到返回所需值的目的。