Velocity 快速入门

Velocity 快速入门

Velocity （简称 VTL）是一个基于 Java 的模版引擎。它允许 web 页面设计者引用 JAVA 代码预定义的方法。Web 设计者可以根据 MVC 模式和 JAVA 程序员并行工作，这意味着 Web 设计者可以单独专注于设计良好的站点，而程序员则可单独专注于编写底层代码。Velocity 将 Java 代码从 web 页面中分离出来，使站点在长时间运行后仍然具有很好的可维护性，并提供了一个除 JSP 和 PHP 之外的可行的被选方案。

注释

单行注释以##开始，并在本行结束。

1
## This is a single line comment.

多行注释，以 # 开始并以 # 结束可以处理这种情况。

1
2
3
4
5
#*
 Thus begins a multi-line comment. Online visitors won't
 see this text because the Velocity Templating Engine will
 ignore it.
*#

注释块 ，可以用来存储诸如文档作者、版本信息等。

1
2
3
4
5
6
7
8
#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
information:
@author
@version 5
*#

引用

VTL 中有三种类型的引用：变量，属性和方法。

变量

变量（Variables）的简略标记是有一个前导 $ 字符后跟一个 VTL 标识符（Identifier.）组成。一个 VTL 标识符必须以一个字母开始(a .. z 或 A .. Z)。

剩下的字符将由以下类型的字符组成：

  • 字母 (a .. z, A .. Z)
  • 数字 (0 .. 9)
  • 连字符(“-“)
  • 下划线 (“_“)

示例：有效变量

1
2
3
4
5
6
7
8
9
## 有效变量变量名
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1

## 给变量赋值
#set( $foo = "bar" )

属性

VTL 引用的第二种元素是属性，而属性具有独特的格式。属性的简略标记识前导符 $ 后跟一个 VTL 标识符，在后跟一个点号(“.”)最后又是一个 VTL 标识符。

示例：有效属性

1
2
$customer.Address
$purchase.Total

方法

方法在 JAVA 代码中定义，并作一些有用的事情，比如运行一个计算器或者作出一个决定。方法是实际上也是引用，由前导符 $ 后跟一个 VTL 标识符，后跟一个 VTL 方法体（Method Body）。 VTL 方法体由一个 VTL 标识符后跟一个左括号，再跟可选的参数列表，最后是右括号。

示例：有效方法

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

赋值

#set 指令用来为引用设置相应的值。值可以被值派给变量引用或者是属性引用，而且赋值要在括号里括起来。

1
2
3
4
5
6
#set( $monkey = $bill ) ## variable reference
#set( $monkey.Friend = "monica" ) ## string literal
#set( $monkey.Blame = $whitehouse.Leak ) ## property reference
#set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference
#set( $monkey.Number = 123 ) ##number literal
#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList

字符串

使用 #set 指令时，括在双引号中的字面字符串将解析和重新解释 。 然而，当字面字符串括在单引号中时，不被解析：

示例：

1
2
3
4
#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh

输出：

1
2
Bar
 $foo

条件

VTL 使用 #If、#elseif、#else 指令做条件语句控制。

示例：

1
2
3
4
5
6
7
8
9
#if( $foo < 10 )
    <strong>Go North</strong>
#elseif( $foo == 10 )
    <strong>Go East</strong>
#elseif( $bar == 6 )
    <strong>Go South</strong>
#else
    <strong>Go West</strong>
#end

逻辑

VTL 支持与（&&）、或（||）、非（!）逻辑判断。

示例：

1
2
3
4
5
6
7
8
9
10
11
#if( $foo && $bar )
   <strong> This AND that</strong>
#end

#if( $foo || $bar )
    <strong>This or That</strong>
#end

#if( !$foo )
 <strong>NOT that</strong>
#end

循环

VTL 通过 #foreach 支持循环

1
2
3
4
5
<ul>
#foreach( $product in $allProducts )
    <li>$product</li>
#end
</ul>

包含

VTL 通过 #include 来导入其他文件。

示例：

1
2
3
4
5
#include( "one.txt" )

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

#include( "greetings.txt", $seasonalstock )

解析

VTL 通过 #parse 导入其他 vm 文件。

1
2
3
4
5
6
7
$count
#set( $count = $count - 1 )
#if( $count > 0 )
    #parse( "parsefoo.vm" )
#else
    All done with parsefoo.vm!
#end

停止

VTL 使用 #stop 停止模板引擎的执行，并返回。这通常用作调试。

1
#stop ##

宏

VTL 使用 #macro 和 #end 配合来定义宏，以此实现自定义指令。

示例一：

1
2
3
4
5
6
7
## 定义宏
#macro( d )
<tr><td></td></tr>
#end

## 使用宏
#d()

示例二：

1
2
3
4
5
6
7
8
9
10
11
12
13
## 定义宏
#macro( tablerows $color $somelist )
  #foreach( $something in $somelist )
    <tr><td bgcolor=$color>$something</td></tr>
  #end
#end

## 使用宏
#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
    #tablerows( $color $greatlakes )
</table>

输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<table>
  <tr>
    <td bgcolor="blue">Superior</td>
  </tr>
  <tr>
    <td bgcolor="blue">Michigan</td>
  </tr>
  <tr>
    <td bgcolor="blue">Huron</td>
  </tr>
  <tr>
    <td bgcolor="blue">Erie</td>
  </tr>
  <tr>
    <td bgcolor="blue">Ontario</td>
  </tr>
</table>

转义

VTL 使用 \ 符号来进行字符转义。

示例一

1
2
3
4
## The following line defines $email in this template:
#set( $email = "foo" )
$email
\$email

输出：

1
2
foo
$email

语义要点

Velocity 有一些语义要点，容易产生歧义，这里归纳一下。

（1）Velocity 的行为并不受空格的影响。

示例：以下三种写法效果一致

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
## 写法一
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.

## 写法二
Send me
#set( $foo = ["$10 and ","a cake"] )
#foreach( $a in $foo )
$a
#end
please.

## 写法三
Send me
#set($foo       = ["$10 and ","a cake"])
                 #foreach           ($a in $foo )$a
         #end please.

参考资料