模板引擎velocity


本文基于 Velocity 1.7 版本撰写。

概述

什么是Velocity?

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

当Velocity应用于web开发时,界面设计人员可以和java程序开发人员同步开发一个遵循MVC架构的web站点,也就是说,页面设计人员可以只 关注页面的显示效果,而由java程序开发人员关注业务逻辑编码。Velocity将java代码从web页面中分离出来,这样为web站点的长期维护提 供了便利,同时也为我们在JSP和PHP之外又提供了一种可选的方案。

Velocity的能力远不止web站点开发这个领域,例如,它可以从模板(template)产生SQL和PostScript、XML,它也可以被当作一个独立工具来产生源代码和报告,或者作为其他系统的集成组件使用。Velocity也可以为Turbine web开发架构提供模板服务(template service)。Velocity+Turbine提供一个模板服务的方式允许一个web应用以一个真正的MVC模型进行开发。

安装

如果你的项目是 maven 项目,添加依赖到 pom.xml 中即可。

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity</artifactId>
  <version>1.7</version>
</dependency>

非maven项目,可以去官网下载 jar 包:<u>官网下载地址</u>

Velocity 编程模型

HelloWorld 示例

先展示一个最简单的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.创建一个上下文对象 */
        VelocityContext context = new VelocityContext();

        /* 3.添加你的数据对象到上下文 */
        context.put("name", "Victor Zhang");
        context.put("project", "Velocity");

        /* 4.选择一个模板 */
        Template template = velocityEngine.getTemplate("template/hello.vm");

        /* 5.将你的数据与模板合并,产生输出内容 */
        StringWriter sw = new StringWriter();
        template.merge(context, sw);
        System.out.println("final output:\n" + sw);
    }
}

hello.vm

在你的 resources (一般路径为src/main/resources) 目录下创建 template/helloVelocity.vm 文件。

文件内容如下:

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

编程模型

通过HelloWorld示例,不难总结出Velocity的编程模型,大致如下:

  1. 初始化 Velocity 。
  2. 创建一个上下文对象。
  3. 添加你的数据对象到上下文。
  4. 选择一个模板。
  5. 将你的数据与模板合并,产生输出内容。

使用Properties定制Velocity

properties 文件

在HelloWorld示例中,第一步初始化过程中,设值了两个 java.util.Properties 参数。

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();

这两个参数是用来在初始化 Velocity 模板引擎时,对它进行定制。

显然,如果每次都要逐一设值定制参数是很麻烦的。所以,可以将 java.util.Properties 参数统一置于properties 文件中,然后加载进来。

这样做的好处有两点:

  • 减少大量配置代码
  • 配置文件可以被多个引擎模板复用

velocity.properties

在你的 resources (一般路径为src/main/resources) 目录下创建 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 定制参数

Velocity 常见的定制参数可以在 org.apache.velocity.runtime.RuntimeConstants 中找到。你可以设值日志、事务句柄、宏、加载资源方式等等重要配置。

更多详情见:<u>Velocity 官方开发者指南</u>

Velocity 语法

注释

单行注释

## 开头。

## 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.
*#

引用

在 Velocity 中有三种类型的引用:变量,属性和函数。

变量(Variables)

和我们所熟知的其他编程语言一样,Velocity 也可以在模板文件中有变量的概念。

变量以 $ 开头,首字母必须是英文字母。变量允许的字符为以下几种类型:

  • 字母(a .. z, A .. Z)

  • 数字(0 .. 9)

  • 连字符("-")

  • 下划线("_")

有效范例:

$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1

变量定义

可以使用 #set 来为变量定义。

#set( $foo = "bar" )

属性(Properties)

属性以 $ 开头,标识符间以 . 分隔。

有效范例:

$customer.Address
$purchase.Total

函数(Methods)

有效范例:

## 无参数
$customer.getAddress()
$purchase.getTotal()
## 单个参数
$page.setTitle( "My Home Page" )
## 参数列表
$person.setAttributes( ["Strange", "Weird", "Excited"] )

Velocity 1.6 开始支持重载函数。

$sun.setPlanets('Earth', 'Mars', 'Neptune')
$sun.setPlanets('Mercury')
$sun.setPlanets()

条件语句

条件语句必须以 #if 开始,以 #end 结尾。

用法与Java中的条件语句极其相似,看看例子就能懂。

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

注意:Velocity中的 == 的语义与Java略有不同,其中 == 只能用于测试对象的相等性。在Velocity中,等效运算符可以用于直接比较数字,字符串或对象。当对象具有不同的类时,通过为每个对象调用 toString() 然后比较来获得字符串表示。

#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 中的条件语句也可以使用与、或、非。

#if( $foo && $bar )
    **This AND That**
#end
#if( $foo || $bar )
    **This OR That**
#end
#if( !$foo )
    **NOT that**
#end

循环

#foreach 用来控制一个循环语句。

#foreach 支持遍历一个 Vector、Hashtable 或 Array 对象。

<ul>
#foreach( $key in $allProducts.keySet() )
    <li>Key: $key -> Value: $allProducts.get($key)</li>
#end
</ul>

可以使用 #break 跳出循环。$foreach.count 表示循环次数。

## list first 5 customers only
#foreach( $customer in $customerList )
    #if( $foreach.count > 5 )
        #break
    #end
    $customer.Name
#end

五、宏

Velocity 中的宏可以理解为函数定义。定义的语法如下:

#macro(macroName arg1 arg2 …)
...
#end

调用这个宏的语法是:

#macroName(arg1 arg2 …)

这里的参数之间使用空格隔开,下面是定义和使用 Velocity 宏的例子:

#macro(sayHello $name)
hello $name
#end
#sayHello(“velocity”)

输出的结果为 hello velocity

六、#parse 和 #include

#parse 和 #include 指令的功能都是在外部引用文件,而两者的区别是,#parse 会将引用的内容当成类似于源码文件,会将内容在引入的地方进行解析,#include 是将引入文件当成资源文件,会将引入内容原封不动地以文本输出。分别看以下例子:

foo.vm 文件:

#set($name =“velocity”)

parse.vm:

#parse(“foo.vm”)

输出结果为:velocity

include.vm:

#include(“foo.vm”)

输出结果为:#set($name =“velocity”)

以上内容包含了部分 Velocity 的语法,详细的语法内容可以参考 Velocity 的官方文档。

参考

<u>Velocity 官网</u>

范例
范例源码

邮件模板效果图.png

推荐阅读更多精彩内容