# Velocity Cheat Sheet

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

# 注释

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

## This is a single line comment.

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

#*
 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:
@author
@version 5
*#

# 引用

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

# 变量

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

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

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

示例:有效变量

## 有效变量变量名
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1

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

# 属性

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

示例:有效属性

$customer.Address
$purchase.Total

# 方法

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

示例:有效方法

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

# 赋值

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

#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 指令时,括在双引号中的字面字符串将解析和重新解释 。 然而,当字面字符串括在单引号中时,不被解析:

示例:

#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh

输出:

Bar
 $foo

# 条件

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

示例:

#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 支持与(&&)、或(||)、非(!)逻辑判断。

示例:

#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 支持循环

<ul>
#foreach( $product in $allProducts )
    <li>$product</li>
#end
</ul>

# 包含

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

示例:

#include( "one.txt" )

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

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

# 解析

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

$count
#set( $count = $count - 1 )
#if( $count > 0 )
    #parse( "parsefoo.vm" )
#else
    All done with parsefoo.vm!
#end

# 停止

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

#stop ##

#

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

示例一:

## 定义宏
#macro( d )
<tr><td></td></tr>
#end

## 使用宏
#d()

示例二:

## 定义宏
#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>

输出:

<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 使用 \ 符号来进行字符转义。

示例一

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

输出:

foo
$email

# 语义要点

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

(1)Velocity 的行为并不受空格的影响

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

## 写法一
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.

# 参考资料