本文基于 Velocity 1.7 版本撰寫。
概述
什么是Velocity？
Velocity是一個(gè)基于java的模板引擎（template engine）。它允許任何人僅僅簡(jiǎn)單的使用模板語(yǔ)言（template language）來(lái)引用由java代碼定義的對(duì)象。
當(dāng)Velocity應(yīng)用于web開(kāi)發(fā)時(shí)，界面設(shè)計(jì)人員可以和java程序開(kāi)發(fā)人員同步開(kāi)發(fā)一個(gè)遵循MVC架構(gòu)的web站點(diǎn)，也就是說(shuō)，頁(yè)面設(shè)計(jì)人員可以只 關(guān)注頁(yè)面的顯示效果，而由java程序開(kāi)發(fā)人員關(guān)注業(yè)務(wù)邏輯編碼。Velocity將java代碼從web頁(yè)面中分離出來(lái)，這樣為web站點(diǎn)的長(zhǎng)期維護(hù)提 供了便利，同時(shí)也為我們?cè)贘SP和PHP之外又提供了一種可選的方案。
Velocity的能力遠(yuǎn)不止web站點(diǎn)開(kāi)發(fā)這個(gè)領(lǐng)域，例如，它可以從模板（template）產(chǎn)生SQL和PostScript、XML，它也可以被當(dāng)作一個(gè)獨(dú)立工具來(lái)產(chǎn)生源代碼和報(bào)告，或者作為其他系統(tǒng)的集成組件使用。Velocity也可以為Turbine web開(kāi)發(fā)架構(gòu)提供模板服務(wù)（template service）。Velocity+Turbine提供一個(gè)模板服務(wù)的方式允許一個(gè)web應(yīng)用以一個(gè)真正的MVC模型進(jìn)行開(kāi)發(fā)。
安裝
如果你的項(xiàng)目是 maven 項(xiàng)目，添加依賴到 pom.xml 中即可。
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity</artifactId>
<version>1.7</version>
</dependency>
非maven項(xiàng)目，可以去官網(wǎng)下載 jar 包：<u>官網(wǎng)下載地址</u>
Velocity 編程模型
HelloWorld 示例
先展示一個(gè)最簡(jiǎn)單的HelloWorld示例。
VelocityHelloWorld.java
import org.apache.velocity.Template;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.VelocityEngine;
import java.io.StringWriter;
/**
* Velocity 的 HelloWorld 示例
*
* @author Victor Zhang
* @date 2016/12/22.
*/
public class VelocityHelloWorld {
public static void main(String args[]) {
/* 1.初始化 Velocity */
VelocityEngine velocityEngine = new VelocityEngine();
velocityEngine.setProperty(VelocityEngine.RESOURCE_LOADER, "file");
velocityEngine.setProperty(VelocityEngine.FILE_RESOURCE_LOADER_PATH, "D:/01_Workspace/Project/zp/javaparty/src/toolbox/template/src/main/resources");
velocityEngine.init();
/* 2.創(chuàng)建一個(gè)上下文對(duì)象 */
VelocityContext context = new VelocityContext();
/* 3.添加你的數(shù)據(jù)對(duì)象到上下文 */
context.put("name", "Victor Zhang");
context.put("project", "Velocity");
/* 4.選擇一個(gè)模板 */
Template template = velocityEngine.getTemplate("template/hello.vm");
/* 5.將你的數(shù)據(jù)與模板合并，產(chǎn)生輸出內(nèi)容 */
StringWriter sw = new StringWriter();
template.merge(context, sw);
System.out.println("final output:\n" + sw);
}
}
hello.vm
在你的 resources (一般路徑為src/main/resources) 目錄下創(chuàng)建 template/helloVelocity.vm 文件。
文件內(nèi)容如下：
Hello World! The first velocity demo.
Name is $name.
Project is $project
輸出
final output:
Hello World! The first velocity demo.
Name is Victor Zhang.
Project is Velocity
編程模型
通過(guò)HelloWorld示例，不難總結(jié)出Velocity的編程模型，大致如下：
- 初始化 Velocity 。
- 創(chuàng)建一個(gè)上下文對(duì)象。
- 添加你的數(shù)據(jù)對(duì)象到上下文。
- 選擇一個(gè)模板。
- 將你的數(shù)據(jù)與模板合并，產(chǎn)生輸出內(nèi)容。
使用Properties定制Velocity
properties 文件
在HelloWorld示例中，第一步初始化過(guò)程中，設(shè)值了兩個(gè) java.util.Properties 參數(shù)。
VelocityEngine velocityEngine = new VelocityEngine();
velocityEngine.setProperty(VelocityEngine.RESOURCE_LOADER, "file");
velocityEngine.setProperty(VelocityEngine.FILE_RESOURCE_LOADER_PATH, "D:/01_Workspace/Project/zp/javaparty/src/toolbox/template/src/main/resources");
velocityEngine.init();
這兩個(gè)參數(shù)是用來(lái)在初始化 Velocity 模板引擎時(shí)，對(duì)它進(jìn)行定制。
顯然，如果每次都要逐一設(shè)值定制參數(shù)是很麻煩的。所以，可以將 java.util.Properties 參數(shù)統(tǒng)一置于properties 文件中，然后加載進(jìn)來(lái)。
這樣做的好處有兩點(diǎn)：
- 減少大量配置代碼
- 配置文件可以被多個(gè)引擎模板復(fù)用
velocity.properties
在你的 resources (一般路徑為src/main/resources) 目錄下創(chuàng)建 template/velocity.properties 文件。
resource.loader = file
file.resource.loader.path = D:/01_Workspace/Project/zp/javaparty/src/toolbox/template/src/main/resources
初始化部分的代碼替換如下：
Properties p = new Properties();
try {
p.load(VelocityDemo.class.getResourceAsStream("/template/velocity.properties"));
} catch (IOException e) {
e.printStackTrace();
}
VelocityEngine velocityEngine = new VelocityEngine();
velocityEngine.init(p);
輸出
效果與HelloWorld的示例是一樣的。
Velocity 定制參數(shù)
Velocity 常見(jiàn)的定制參數(shù)可以在 org.apache.velocity.runtime.RuntimeConstants 中找到。你可以設(shè)值日志、事務(wù)句柄、宏、加載資源方式等等重要配置。
更多詳情見(jiàn)：<u>Velocity 官方開(kāi)發(fā)者指南</u>
Velocity 語(yǔ)法
注釋
單行注釋
以 ## 開(kāi)頭。
## This is a single line comment.
多行注釋
以 #* 開(kāi)頭，以 *# 結(jié)尾。
#*
Thus begins a multi-line comment. Online visitors won't
see this text because the Velocity Templating Engine will
ignore it.
*#
引用
在 Velocity 中有三種類型的引用：變量，屬性和函數(shù)。
變量(Variables)
和我們所熟知的其他編程語(yǔ)言一樣，Velocity 也可以在模板文件中有變量的概念。
變量以 $ 開(kāi)頭，首字母必須是英文字母。變量允許的字符為以下幾種類型：
字母(a .. z, A .. Z)
數(shù)字(0 .. 9)
連字符("-")
下劃線("_")
有效范例：
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
變量定義
可以使用 #set 來(lái)為變量定義。
#set( $foo = "bar" )
屬性(Properties)
屬性以 $ 開(kāi)頭，標(biāo)識(shí)符間以 . 分隔。
有效范例：
$customer.Address
$purchase.Total
函數(shù)(Methods)
有效范例：
## 無(wú)參數(shù)
$customer.getAddress()
$purchase.getTotal()
## 單個(gè)參數(shù)
$page.setTitle( "My Home Page" )
## 參數(shù)列表
$person.setAttributes( ["Strange", "Weird", "Excited"] )
Velocity 1.6 開(kāi)始支持重載函數(shù)。
$sun.setPlanets('Earth', 'Mars', 'Neptune')
$sun.setPlanets('Mercury')
$sun.setPlanets()
條件語(yǔ)句
條件語(yǔ)句必須以 #if 開(kāi)始，以 #end 結(jié)尾。
用法與Java中的條件語(yǔ)句極其相似，看看例子就能懂。
#if( $foo )
<strong>Velocity!</strong>
#end
注意：Velocity中的 == 的語(yǔ)義與Java略有不同，其中 == 只能用于測(cè)試對(duì)象的相等性。在Velocity中，等效運(yùn)算符可以用于直接比較數(shù)字，字符串或?qū)ο蟆．?dāng)對(duì)象具有不同的類時(shí)，通過(guò)為每個(gè)對(duì)象調(diào)用 toString() 然后比較來(lái)獲得字符串表示。
#set ($foo = "north")
#set ($bar = "north")
#if( $foo == $bar )
**Go North**
#elseif( $foo == "east" )
**Go East**
#elseif( $bar == "south" )
**Go South**
#else
**Go West**
#end
Velocity 中的條件語(yǔ)句也可以使用與、或、非。
#if( $foo && $bar )
**This AND That**
#end
#if( $foo || $bar )
**This OR That**
#end
#if( !$foo )
**NOT that**
#end
循環(huán)
#foreach 用來(lái)控制一個(gè)循環(huán)語(yǔ)句。
#foreach 支持遍歷一個(gè) Vector、Hashtable 或 Array 對(duì)象。
<ul>
#foreach( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key)</li>
#end
</ul>
可以使用 #break 跳出循環(huán)。$foreach.count 表示循環(huán)次數(shù)。
## list first 5 customers only
#foreach( $customer in $customerList )
#if( $foreach.count > 5 )
#break
#end
$customer.Name
#end
五、宏
Velocity 中的宏可以理解為函數(shù)定義。定義的語(yǔ)法如下：
#macro(macroName arg1 arg2 …)
...
#end
調(diào)用這個(gè)宏的語(yǔ)法是：
#macroName(arg1 arg2 …)
這里的參數(shù)之間使用空格隔開(kāi)，下面是定義和使用 Velocity 宏的例子：
#macro(sayHello $name)
hello $name
#end
#sayHello(“velocity”)
輸出的結(jié)果為 hello velocity
六、#parse 和 #include
#parse 和 #include 指令的功能都是在外部引用文件，而兩者的區(qū)別是，#parse 會(huì)將引用的內(nèi)容當(dāng)成類似于源碼文件，會(huì)將內(nèi)容在引入的地方進(jìn)行解析，#include 是將引入文件當(dāng)成資源文件，會(huì)將引入內(nèi)容原封不動(dòng)地以文本輸出。分別看以下例子：
foo.vm 文件：
#set($name =“velocity”)
parse.vm：
#parse(“foo.vm”)
輸出結(jié)果為：velocity
include.vm：
#include(“foo.vm”)
輸出結(jié)果為：#set($name =“velocity”)
以上內(nèi)容包含了部分 Velocity 的語(yǔ)法，詳細(xì)的語(yǔ)法內(nèi)容可以參考 Velocity 的官方文檔。
參考
范例
范例源碼
