Velocity模板引擎

一、什么是Velocity

　　Velocity是一个基于Java的模板引擎，其提供了一个Context容器，在java代码里面我们可以往容器中存值，然后在vm文件中使用特定的语法获取。通过Context数据容器+模板内容进行合并，可以输出html、java、sql、xml等一切需要的文本类文件。

　　作为一个模块引擎，除了作为前后端分离的MVC视图层，Velocity还可以用于源代码生成、自动email、xml转换等。

　　Velocity主要分为app、context、runtime、util等部分，作用如下：

• app模块：封装了一些接口，暴露给使用者使用。主要有两个类，分别是Velocity(单例)和VelocityEngine。
• Context模块：封装了模板渲染需要的变量。
• Runtime模块：整个Velocity的核心模块，Runtime模块会将加载的模板解析成语法树，Velocity调用mergeTemplate方法时会渲染整棵树，并输出最终的渲染结果。
• RuntimeInstance类：为整个velocity渲染提供了一个单例模式，拿到了这个实例就可以完成渲染过程。

二、Velocity的使用步骤

　　1、引入依赖：

<!--velocity核心包-->
<dependency>
    <groupId>org.apache.velocity</groupId>
    <artifactId>velocity-engine-core</artifactId>        
    <version>2.2</version>
</dependency>

　　2、编写模板：在resources/vm/下新建.vm文件，.vm文件就是velocity模板文件的扩展名。模板的内容根据你想要生成的文件的类型来决定，随你怎么写都可以。

　　3、加载模板输出文件\流：根据如下步骤编写代码。

• 设置velocity的资源加载器；
• 初始化velocity引擎；
• 创建velocity容器；
• 加载velocity模板文件；
• 合并数据到模板文件；
• 输出合并后的结构流或者文件；
• 释放资源。

 //实例化资源加载器
Properties p = new Properties();

 // 加载classpath目录下的vm文件
p.setProperty("resource.loader.file.class", "org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader");

// 定义字符集
p.setProperty(Velocity.INPUT_ENCODING, Constants.UTF8);

// 初始化Velocity引擎，指定配置Properties
Velocity.init(p);

//创建容器，加入渲染模板需要的变量
VelocityContext velocityContext = new VelocityContext();
velocityContext .put("varName","varValue");

//根据模板名称装载模板对象
Template tpl = Velocity.getTemplate("templateName", Constants.UTF8);

// 渲染模板:输出为字符串时使用
StringWriter sw = new StringWriter();

// 渲染模板:输出到指定文件时使用
FileWriter  fw= new FileWriter("fileName");


//执行数据+模板合并，输出最终结果
  tpl.merge(velocityContext , sw);
  tpl.merge(velocityContext , fw);

//释放资源
sw.close();
fw.close();

三、Velocity的语法

　　Velocity提供了一叫做VTL的模板语言，能够简单明了的进行数据和模板的整合，它有四大类语句，分别为注释、非解析内容、引用和指令。

1、注释：注释包括行注释、块注释、文档注释。这些注释只用于开发者阅读，不会被生成到输出文件/流中。

## 这是一个单行注释

#*
*
*  这是多行注释
*
* *#

#**
*
*  这是文档注释
*
* *#

 2、非解析内容：这部分内容将会被原样显示，即使包含变量占位符也不会被替换。

#[[
.....

这里面的内容将被原样输出，即使存在变量占位符${xxx}也不会被替换。
......

]]#

3、变量引用、属性引用、方法引用：引用是对引擎上下文对象中的属性进行调用，分为常规语法($xxx)和正规语法(${xxx})。

$变量名：若上下文中没有对应的变量，则输出字符串"$变量名"
${变量名}：若上下文中没有对应的变量，则输出字符串"${变量名}"
$!变量名：若上下文中没有对应的变量，则输出空字符串""
$!{变量名}：若上下文中没有对应的变量，则输出空字符串""

$变量名.属性：若上下文中没有对应的变量，则输出字符串"$变量名.属性"
${变量名.属性}：若上下文中没有对应的变量，则输出字符串"${变量名.属性}"
$!变量名.属性：若上下文中没有对应的变量，则输出空字符串""
$!{变量名.属性}：若上下文中没有对应的变量，则输出空字符串""

$变量名.方法([入参1[，入参2]*]?)
${变量名.方法([入参1[，入参2]*]?)}
$!变量名.方法([入参1[，入参2]*]?)
$!{变量名.方法([入参1[，入参2]*]?)}

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

/**
*#set指令用于定义一个变量
**/
#set($变量=值) 

/**
*#if #else 用于条件判断，#end表示结束
**/
#if(判断条件)
..............
#elseif(判断条件)
..............
#else
..............
#end

/**
*#foreach 用于循环变量一个集合； #break用于结束循环，可选；在循环体内可以使用$foreach.index/$foreach.count获取遍历的索引和次数
**/
#foreach($item in $items)
     .............
     [#break]
     .............
#end

5、引用：用于引入资源。

/**
* #include用于引入一个外部资源，参数resourcePath指定资源的路径，该资源不会被解析器解析
*/
#include(resourcePath)

/**
* #parse用于引入一个外部资源，参数resourcePath指定资源的路径，该资源会被解析器解析
*/
#parse(resourcePath)

/**
* #define用于定义重用模块，不可携带参数。定义后可使用 $模块名称 来引用
*/
#define($模块名称)
.....模块内容.....
#end

/**
* #macro用于定义重用模块，可以携带参数。定义后可以使用 #宏名称(实数) 指令进行调用
*/
#macro(宏名称 [可选参数])
.....模块内容.....
#end

/**
* #evaluate用于动态计算，参数express为计算表达式字符串。evaluate方法可以把字符串当作代码进行运行并得出结果
*/
#evaluate(express)

 四、VelocityTools工具类

　　VelocityTools是Velocity模板引擎的一个子项目，用于将Velocity 与 Web开发环境集成的工具包。该工具包包含GenericTools和VelocityView两部分。

　　GenericTools是一组可以在模板中直接调用的工具类库，里面包含了很多工具类，常用的有DateTool、NumberTool、MathTool、DisplayTool、EscapeTool、FieldTool、ContextTool、RenderTool、SortTool、CollectionTool、XmlTool，使用时需要导入依赖：

<!-- velocityTools工具包-->
<dependency>
     <groupId>org.apache.velocity.tools</groupId> 
     <artifactId>velocity-tools-generic</artifactId> 
     <version>3.0</version>
</dependency>

　　Velocityview包含所有cenericTools并添加了用于在Web应用程序(Java EE项目)的视图层中使用Velocity的基础结构和专用工具，里面包含了CookieTool、BrowswerTool、ParameterTool、ViewContextTool等工具类。使用时也需要导入：

<!-- velocityView工具包-->
<dependency>
     <groupId>org.apache.velocity.tools</groupId> 
     <artifactId>velocity-tools-generic</artifactId> 
     <version>3.0</version>
</dependency>
<dependency>
     <groupId>org.apache.velocity.tools</groupId> 
     <artifactId>velocity-tools-view</artifactId> 
     <version>3.0</version>
</dependency>