Velocity开发指南

Integer、Long等简单数据类型的装箱类型；

String类型；

Object子类；

Object[] 数组类型，从1.6开始Velocity将数组类型视为 java.util.List 类型看待，因此模板中可调用 size() 、 get(int index) 和 isEmpty() 的变量方法；

java.util.Collection子类；

java.util.Map子类；

java.util.Iterator对象；

java.util.Enumeration对象。

2. 属性（就是引擎上下文对象的属性的属性）

$变量名.属性, 常规写法
${变量名.属性}, 正规写法
$!变量名.属性, 常规写法
$!{变量名.属性}, 正规写法复制代码

属性搜索规则：

Velocity采用一种十分灵活的方式搜索变量的属性， 具体如下：

// 假如引用$var.prop，那么Velocity将对prop进行变形，然后在$var对象上尝试调用
// 变形和尝试的顺序如下

1. $var.getprop()

2. $var.getProp()

3. $var.get("prop")

4. $var.isProp()

// 对于$var.Prop则如下

1. $var.getProp()

2. $var.getprop()

3. $var.get("Prop")

4. $var.isProp()

因此获取 java.util.Map 对象的键值时可以简写为 $map.key ，Velocity会自动转为 $map.get("key") 来搜索！

3. 方法（就是引擎上下文对象的属性的方法）

$变量名.方法([入参1[, 入参2]*]?), 常规写法
${变量名.方法([入参1[, 入参2]*]?)}, 正规写法
$!变量名.方法([入参1[, 入参2]*]?), 常规写法
$!{变量名.方法([入参1[, 入参2]*]?)}, 正规写法复制代码

引用方法实际就是方法调用操作，关注点返回值、入参和副作用的情况如下：

1. 方法的返回值将输出到最终结果中

1. 入参的数据类型

$变量 或 $属性，数据类型参考第一小节；
范围操作符(如：[1..2]或[$arg1..$arg2])，将作为java.util.ArrayList处理
字典字面量(如：{a:"a",b:"b"})，将作为java.util.Map处理
数字字面量(如：1)，将自动装箱或拆箱匹配方法定义中的int或Integer入参复制代码

1. 副作用

// 若操作如java.util.Map.put方法，则会修改Java代码部分中的Map对象键值对
$map.put("key", "new value")复制代码

指令

指令主要用于定义重用模块、引入外部资源、流程控制。指令以 # 作为起始字符。

#set：向引擎上下文对象添加属性或对已有属性进行修改

格式： #set($变量 = 值) ，具体示例如下：

#set($var1 = $other)
#set($var1.prop1 = $other)
#set($var = 1)
#set($var = true)
#set($var = [1,2])
#set($var = {a:"a", b:"b"})
#set($var = [1..3])
#set($var = [$arg1..$arg2])
#set($var = $var1.method())
#set($var = $arg1 + 1)
#set($var = "hello")
#set($var = "hello $var1") // 双引号可实现字符串拼接（coffeescript也是这样哦！），假设$var1为fsjohnhuang，则$var为hello fsjohnhuang
#set($var = 'hello $var1') // 单引号将不解析其中引用，假设$var1为fsjohnhuang，则$var为hello $var1复制代码

作用域明显是全局有效的。

#if：条件判断

格式：

#if(判断条件)
  .........
#elseif(判断条件)
  .........
#else
  .........
#end复制代码

通过示例了解判断条件：

#if($name)   //$name不为false、null和undefined则视为true
$name
#elseif($job == "net") // ==和!=两边的变量将调用其toString()，并对比两者的返回值
Net工程师
#elseif($age <= 16) // 支持<=,>=,>,<逻辑运算符
未成年劳工
#elseif(!$married) // 支持!逻辑运算符
未婚
#elseif($age >= 35 && !$married) // 支持&&,||关系运算符
大龄未婚青年
#end复制代码

#foreach：循环

格式：

#foreach($item in $items)
    ..........
#end复制代码

$item 的作用范围为#foreach循环体内。

$items 的数据类型为 Object[]数组 、 [1..2] 、 [1,2,3,4] 、 {a:"a",b:"b"} 和含 public Iterator iterator() 方法的对象，具体如下：

java.util.Collection子类，Velocity会调用其iterator方法获取Iterator对象
java.util.Map子类，Velocity会调用value()获取Collection对象，然后调用调用其iterator方法获取Iterator对象
java.util.Iterator对象，直接将该Iterator对象添加到上下文对象中时，由于Iterator对象为只进不退的操作方式，因此无法被多个#foreach指令遍历
java.util.Enumeration对象，直接将该Enumeration对象添加到上下文对象中时，由于Iterator对象为只进不退的操作方式，因此无法被多个#foreach指令遍历复制代码

内置属性$foreach.count ，用于指示当前循环的次数，从0开始。可以通过配置项 directive.foreach.maxloops 来限制最大的循环次数，默认值为-1（不限制）。

示例——使用Vector和Iterator的区别：

模板：

#macro(show)
#foreach($letter in $letters)
$letter
#end
#end
#show()复制代码

java代码：

Vector<String> v = new Vector<String>();
v.add("a");
v.add("b");
VelocityContext ctx = new VelocityContext();
ctx.put("letters",v);
Template t = Velocity.getTemplate("模板路径");
StringWriter sw = new StringWriter();
t.merge(ctx,sw);
System.out.println(sw.toString());
// 结果
// a
// b
// a
// b

ctx.put("letters",v.iterator());
// 结果
// a
//复制代码

#break：跳出循环

#foreach($item in $items)
#if($item == "over")
#break;
#end
$item
#end复制代码

#stop：中止模板解析操作

#set($cmd="stop")
$cmd
#if($cmd == "stop")
#stop
#end
$cmd  // 该语句将不执行复制代码

#include引入外部资源

（引入的资源不被引擎所解析）

格式： #include(resource[ otherResource]*)

resource、otherResource可以为单引号或双引号的字符串，也可以为$变量，内容为外部资源路径。注意为相对路径，则以引擎配置的文件加载器加载路径作为参考系，而不是当前模板文件的路径为参考系。

#parse引入外部资源

（引入的资源将被引擎所解析）

格式： #parse(resource)

resource可以为单引号或双引号的字符串，也可以为$变量，内容为外部资源路径。注意为相对路径，则以引擎配置的文件加载器加载路径作为参考系，而不是当前模板文件的路径为参考系。

由于#parse指令可能会引起无限递归引入的问题，因此可通过配置项 directive.parse.max.depth来限制最大递归引入次数，默认值为10.

#macro：定义重用模块（可带参数）

定义格式：

#macro(宏名 [$arg[ $arg]*]?)
   .....
#end复制代码

调用格式：

#宏名([$arg[ $arg]]?)复制代码

示例1——定义与调用位于同一模板文件时，无需遵守先定义后使用的规则：

#log("What a happy day")
#macro(log $msg)
log message: $msg
#end复制代码

示例2——定义与调用位于不同的模板文件时，需要遵守先定义后使用的规则：

## 模板文件macro.vm#macro(log $msg)
log message: $msg
#end
## 模板文件main.vm
#parse("macro.vm")
#log("What a happy day")复制代码

原理解析：Velocity引擎会根据模板生成语法树并缓冲起来然后再执行，因此宏定义和调用位于同一模板文件时，调用宏的时候它已经被引擎识别并初始化了（类似js中的hosit）。

若定义与调用位于不同的模板文件中时，由于 #parse 是引擎解析模板文件时才被执行来引入外部资源并对其中的宏定义进行初始化，因此必须遵循先定义后使用的规则。

我们可配置全局宏库，配置方式如下：

Properties props = new Properties();
// velocimacro.library的值为模板文件的路径，多个路径时用逗号分隔
// velocimacro.library的默认值为VM_global_library.vm 
props.setProperty("velocimacro.library", "global_macro1.vm,global_macro2.vm");
VelocityEngine ve = new VelocityEngine(props);复制代码

另外#macro还有另一种传参方式——$!bodyContent

#macro(say)
$!bodyContent
#end
#@say()Hello World#end
// 结果为Hello World复制代码

#define：定义重用模块（不带参数）

#define($log)
hello log!
#end
$log复制代码

可视为弱版#macro，一般不用，了解就好了。

#evaluate：动态计算

示例：

#set($name = "over")
#evalute("#if($name=='over')over#{else}not over#end") // 输出over复制代码

一般不用，了解就好了。

转义符　

通过 \ 对 $ 和 #进行转义，导致解析器不对其进行解析处理。

#set($test='hello')
$test ## 结果：hello
\$test ## 结果：$test
\\$test ## 结果：\hello
\\\$test ## 结果：\$test

$!test ## 结果：hello
$\!test ## 结果：$!test
$\\!test ## 结果：$\!test
$\\\!test ## 结果：$\\!test复制代码

模板实践

内容引自：www.cnblogs.com/fsjohnhuang… 肥仔

示例结果是生成如下的html表单：

<form action="./submit">
<div>
  <label for="title">标题：</label>
  <input type="text" id="title" name="title"/>
</div>
<div>
  <label for="brief">摘要：</label>
  <input type="text" id="brief" name="brief"/>
</div>
<div>
  <label for="sex">性别：</label>
  <select id="sex" name="sex">
    <option value="0">男</option>
    <option value="1">女</option>
  </select>
</div>
<div>
  <label for="job">职业：</label>
  <select id="job" name="job">
    <option value="0">Java工程师</option>
    <option value="1">Net工程师</option>
  </select>
</div>
</form>复制代码

引入依赖项——velocity-1.7-dep.jar

模板文件frm.vm

##表单模板
##@author fsjohnhuang
##@version 1.0
## 引入外部模板文件
#parse('macro.vm')
## 主逻辑
<form action="$action">
#foreach($input in $inputs)
#input($input.title $input.id)
#end
#foreach($select in $selects)
#select($select.title $select.id $select.items)
#end
</form>复制代码

模板文件macro.vm

## 生成input表单元素区域的宏
#macro(input $title $id)
<div>
  <label for="$id">$title</label>
  <input type="text" id="$id" name="$id"/>
</div>
#end
## 生成select表单元素区域的宏
#macro(select $title $id $items)
<div>
  <label for="$id">$title</label>
  <select id="$id" name="$id">
## VTL指令紧贴左侧才能确保结果的排版正常（不会有多余空格）
#foreach($key in $items.keySet())
    <option value="$key">$items.get($key)</option>
#end
  </select>
</div>
#end复制代码

Java代码

public static void main(String[] args) {
        // 初始化模板引擎
        Properties props = new Properties();
        props.put("file.resource.loader.path", ".\\vm");
        VelocityEngine ve = new VelocityEngine(props);
        // 配置引擎上下文对象
        VelocityContext ctx = new VelocityContext();
        ctx.put("action", "./submit");
        ArrayList<HashMap<String, String>> inputs = new ArrayList<HashMap<String,String>>();
        HashMap<String, String> input1 = new HashMap<String, String>();
        input1.put("id", "title");
        input1.put("title", "标题：");
        inputs.add(input1);
        HashMap<String, String> input2 = new HashMap<String, String>();
        input2.put("id", "brief");
        input2.put("title", "摘要：");
        inputs.add(input2);
        ctx.put("inputs", inputs);
        ArrayList<HashMap<String, Object>> selects = new ArrayList<HashMap<String,Object>>();
        HashMap<String, Object> select1 = new HashMap<String, Object>();
        selects.add(select1);
        select1.put("id", "sex");
        select1.put("title", "性别：");
        HashMap<Integer, String> kv1 = new HashMap<Integer, String>();
        kv1.put(0, "男");
        kv1.put(1, "女");
        select1.put("items", kv1);
        HashMap<String, Object> select2 = new HashMap<String, Object>();
        selects.add(select2);
        select2.put("id", "job");
        select2.put("title", "职业：");
        HashMap<Integer, String> kv2 = new HashMap<Integer, String>();
        kv2.put(0, "Java工程师");
        kv2.put(1, "Net工程师");
        select2.put("items", kv2);
        ctx.put("selects", selects);
        // 加载模板文件
        Template t = ve.getTemplate("test.vm");
        StringWriter sw = new StringWriter();
        // 渲染模板
        t.merge(ctx, sw);
        System.out.print(sw.toString());
    }复制代码

参考文章

开发指南原文地址：

velocity.apache.org/engine/deve…

用户指南原文地址：

velocity.apache.org/engine/deve…

中文翻译开发指南地址：

ifeve.com/velocity-gu…

肥仔 john优秀网文地址：

www.cnblogs.com/fsjohnhuang…