velocity API 文档

最新推荐文章于 2022-12-20 08:33:44 发布

VIP文章 Cherry_tly

最新推荐文章于 2022-12-20 08:33:44 发布

阅读量7.2k

点赞数

文章标签： velocity使用手册

本文链接：https://blog.csdn.net/Cherry_tly/article/details/47975791

版权

官方网址：http://velocity.apache.org/engine/devel/user-guide.html

关于本手册

本手册的目的在于：帮助页面设计人员和内容提供者，了解Velocity及其简单但强大的脚本语言（VTL，Velocity模板语言）的语法。本手册中的许多例子，演示的是使用Velocity，在Web页面中，嵌入动态内容，但所有的VTL例子，同样适用于其他任何的页面或模版。

谢谢选择Velocity！

Velocity是什么？

Velocity是一个基于Java的模版引擎。它允许页面设计人员引用Java代码中定义的方法。Web页面设计人员，可以跟Java程序员并行工作：根据MVC模型，以开发Web页面；这意味着。Web页面设计人员能专注于创建更好的页面，而程序员能专注于编写优秀的代码。Velocity分离了Java代码和Web页面，它使得Web页面从长远来看更容易维护，它为JSP或PHP提供了可替代的方案。

Velocity可用来从模版中，生成Web页面，SQL，PostScript和其他输出。它即可作为独立的工具，用来生成源代码和报告；也可作为其他系统的一个集成组件。集成好后，Velocity将为Turbine Web应用框架提供模板服务。 Velocity+Turbine提供的模板服务，将可实现根据一个真正的MVC模型，开发Web应用。

Velocity能为我做什么？

泥品商店的例子

假设你是一个专门销售泥品的在线商店的页面设计人员。让我们就叫它“在线泥品商店”吧。生意蒸蒸日上。客户订购各种类型和质量的泥品。他们用他们的用户名和密码，登陆你们的网站后，可查看他们的订单，购买更多的泥品。现在，非常畅销的古铜色泥品开售了。你们的客户中，一少部分仍然照常购买大红色泥品，虽然它不够畅销，并且常常被摆在页面的角落里，但它仍在销售。每个客户的信息，都被记录在数据库中，因此，有一天，问题就来了，为什么不用Velocity，来标出那些顾客们最感兴趣的特价泥品呢？

Velocity使得为你的在线用户定制Web页面，变的很容易。作为一个在泥品商店的Web页面设计人员，你想创建客户登陆你们的页面后将看到页面。

你会见了你公司的软件工程师，他们都同意用$customer来保存当前登陆的用户的信息，用$mudsOnSpecial保存当前在售泥品的所有种类。$flogger对象包含了帮助促销的方法。接下来，让我们只关注这三个引用对象。记住，你不需要操心软件工程师是怎样从数据库中获取数据的，你只需要知道它能取到。这让你只管你的工作，而让软件工程师只管他们的。

你可以在Web页面中，嵌入如下的VTL语句：

<HTML>
<BODY>
Hello $customer.Name!
<table>
#foreach( $mud in $mudsOnSpecial )
   #if ( $customer.hasPurchased($mud) )
      <tr>
        <td>
          $flogger.getPromo( $mud )
        </td>
      </tr>
   #end
#end
</table>

关于foreach语句的具体细节，将会进行更深入而简短的描述。重要的是，这段简短的脚本，在你的Web页面上起的作用。当一个偏好大红色泥品的客户登陆后，并且大红色泥品还在售的话，它就是客户将会看到的，被显著地展示了出来。如果另外一个购买古铜色泥品很长时间的客户登陆后，古铜色泥品的通知，就会在最前并居中。Velocity的灵活性是极大的，只有你想不到，没有做不到。

在VTL参考手册中，还包含了许多其他的Velocity元素，它们将共同为你提供你创建Web页面时，所需的功能和灵活性。当你熟悉了这些元素后，你将会发挥Velocity的强大功能。

我应该使用什么jar包？

Velocity引擎2.x发布包，有好几个跟Maven有关的jar包，发布在Maven仓库。

Maven用户

在你的POM文件中，包含如下依赖关系：

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity-engine-core</artifactId>
  <version>x.x.x</version>
</dependency>

如果你想将Velocity日志功能关联到Common logging，SLF4J，Log4j或servlet logger，请选择相应的依赖关系：

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity-engine-commons-logging</artifactId>
  <version>x.x.x</version>
</dependency>

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity-engine-slf4j</artifactId>
  <version>x.x.x</version>
</dependency>

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity-engine-log4j</artifactId>
  <version>x.x.x</version>
</dependency>

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity-engine-servlet</artifactId>
  <version>x.x.x</version>
</dependency>

其他用户

首先，下载Velocity引擎发布包

如果你想快速启动你的应用，简单地将velocity-x.x.x.jar放在你的classpath下：它包含了所有Velocity引擎类（不含例子）。也可将jar包放在lib子目录下。

其他的jar包是些细粒度的jar包，它们包含了你可能会需要的功能。

velocity-engine-core-x.x.x.jar：主要的Velocity库。总是要包含它的。
velocity-engine-commons-logging-x.x.x.jar：它包含了绑定Commons Logging，因此，所有的日志信息将会发送给它。跟Commons Logging一起使用（放在lib目录下）。
velocity-engine-slf4j-x.x.x.jar：它包含了绑定SLF4J，因此，所有的日志信息将会发送给它。跟SLF4J一起使用（放在lib目录下）。
velocity-engine-log4j-x.x.x.jar：它包含了绑定Log4j，因此，所有的日志信息将会发送给它。跟Log4j一起使用（放在lib目录下）。
velocity-engine-servlet-x.x.x.jar：它包含了绑定servlet logger。在servlet容器中使用。

你总会用到的额外的jar包，是Commons Collections和Commons Lang，也放在lib目录下。

Velocity模板语言(VTL)：介绍

Velocity模版语言，旨在提供一个简单、普通、清晰的方式，来把动态的内容合并到Web页面中。即便是一个只具有一点甚至没有编程经验的页面开发员，也能迅速地掌握使用VTL并合并动态内容到Web页面的方法。

VTL使用引用（reference），来将动态内容嵌入到Web页面中，变量是引用的一种。变量能引用在Java代码中定义的一些对象，也能在Web页面内从VTL语句中获取其值。下面是一个可嵌入到HTML文档中的VTL语句的例子：

#set( $a = "Velocity" )

和所有的VTL语句一样，这个VTL语句，以#符号开头，并且包含一个指令：set。当一个在线的用户，请求这个Web页面时，Velocity模版引擎，会全面搜索你的Web页面，以查找所有的#符号，然后确定哪个标识了VTL语句的开头，哪个什么也不做。

#符号后面跟着一个指令，set。set指令，使用了一个表达式（包含在括号里）——一个把值赋给变量的等式。变量都是列在左边，值放在右边；两者被=号分开。

在上面的例子中，变量是$a，值是Velocity。该变量象所有引用一样，以$符号开头。字符串的值总是放在引号内，无论是单引号还是双引号。单引号保证被引用的值赋值给引用。双引号允许你使用Velocity引用和指令来插入值，比如"Hello $name"，这里的$name将被当前值所代替，然后，字符串字面量才被赋值给=号左边。

下面的规则，能让你更好地理解Velocity是怎样工作的：引用以$开头，用来得到东西。指令以#开头，用来做些事情。

在上面的例子中，#set用来给变量赋值。变量$a用来在模板中输出"Velocity"。

Hello Velocity World!

当一个变量被赋予了值，你可以在你的HTML文档中的任何位置引用它。在下面的例子中，变量$foo被赋了值，之后被引用。

<html>
<body>
#set( $foo = "Velocity" )
Hello $foo World!
</body>
<html>

结果是显示了“Hello Velocity World！”的Web页面。

为了让包含VTL指令的语句，更易读，我们建议你，每个VTL语句另起一行，虽然这并不是必须的。set指令，后面会详细介绍。

Comments注释

注释允许包含一些描述性的文本，它们并不会在模版引擎中输出。注释能有效地提醒你自己，或解释给别人，你的VTL语句在做什么，或者其他你发现有用的任何目的。下面是一个注释的例子：

## 这是单行注释

单行注释以##开头，到行尾为止。如果你想写多行注释，那么，你没有必要写成很多单行的注释。以#*开头，以*#结束的多行注释，刚好可用于这个场景。

这是多行注释以外的文本，在线用户能看见它。
#*
 这些是多行注释，在线用户看不见它，

 因为Velocity模板引擎会忽略掉它。
*#
这里的文本在多行注释以外；它是可见的。

下面是些演示单行注释和多行注释是如何工作的例子：

这里是可见的。 ## 这里不可见。
这里是可见的。 
这里是可见的。 #* 这里是多行注释的一部分，不可见。
这里也不可见；它也是多行注释的一部分。这

里仍然不可见。 *# 这里在多行注释外面了，因此是可见的。

## 这里不可见。

这是第三种类型的注释，VTL注释块，它用来保存你想在模板中跟踪的各种额外信息（比如文档作者和版本信息）：

#**
这是VTL注释块，可用户保存这些信息，比如作者和版本信息：
@author
@version 5
*#

References引用

在VTL中，有三种类型的引用：变量，属性和方法。作为一个使用VTL的设计者，你和你的工程师，必须在引用的名字上，达成一致的标准，这样你才能在模板中正确地使用它们。

变量
简单来说，变量就是以$开头，后跟一个VTL标示符。一个VTL标示符是以一个字母开头，后跟下列字符：

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

下面是VTL中一些合法的变量引用的例子：

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

当VTL引用了一个变量，比如$foo，则该变量能从模板中的set指令，或者从Java代码中得到值。比如，一个Java变量$foo有个值bar，则当模版被请求的时候，bar会代替页面中所有的$foo变量。此外，如果我包含了语句：

#set( $foo = "bar" )

那么该指令后面的所有的$foo实例同样会被替换。

属性

VTL引用的第二种类型是属性（properties），属性都有其特殊的格式。它是由如下几部分组成：以符号$开头，跟着一个VTL标示符，接着是一个逗号和另一个VTL标示符。下面是一些在VTL中的合法属性引用的例子：

$customer.Address
$purchase.Total

第一个例子中，$customer.Address，它有两个意思。它可以表示，在哈希表（$customer）中查找，并返回关键字Address关联的值；另外，$customer.Address也代表一个方法（其代表的方法，将在下一节中介绍）。$customer.Address，也可作为$customer.getAddress()的简写。当你的页面被请求时，Velocity会决定这两种情况的哪一种是最合理的，并返回适当的值。

方法
在Java代码中定义的方法，能做一些有用的事情，比如执行计算或者作出某种决定。方法是这样的引用：以符号$开头，后跟一个合法的标示符，跟着是一个VTL方法体。一个VTL方法体是由一个合法的VTL标示符，跟着一个左括号，跟着一个可选的参数列表，跟着一个右括号等组成的。下面是一些在VTL中的合法的VTL方法引用的例子：

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

前面的两个例子——$customer.getAddress()和$purchase.getTotal()——可能看起来跟上述的属性章节中的$customer.Address和$purchase.Total很相似。如果你猜这些例子在某种方式上肯定有相关性，那么你猜对了。

VTL属性可作为VTL方法的简写。属性$customer.Address和方法$customer.getAddress()的作用，完全一样。通常，在能用属性时，优先用属性。属性和方法的主要区别，是可以为方法指定一个参数列表。

下列的方法，可以简写：

$sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()

我们希望这些方法，返回太阳系中所有行星的名称，喂养我们的蚯蚓，或者从相册里获取照片。下面的方法，只能用完整的方式。

$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## 不能传递参数列表给$sun.Planets

$sisyphus.pushRock()
## Velocity假定我的意思是$sisyphus.getRock()

$book.setTitle( "Homage to Catalonia" )
## 不能传递参数

作为Velocity 1.6，所有数组引用，目前都被作为固定长度的列表。这就意味着，你对数组引用，可调用java.util.List方法。因此，如果你有一个数组引用（让我们假设，这个数组有3个元素，是String[]类型的），你能这样做：

$myarray.isEmpty()
$myarray.size()
$myarray.get(2)
$myarray.set(1, 'test')

Velocity 1.6也新增支持了可变参数的方法。一个方法像public void setPlanets(String... planets)或者public void setPlanets(String[] planets)（如果你用JDK5以前的版本），当在模板中调用它时，现在它能接受任何数量的参数。

$sun.setPlanets('Earth', 'Mars', 'Neptune')
$sun.setPlanets('Mercury')
$sun.setPlanets()
## 只能传递空的，0长度的数组

属性查找规则

如前面所说，属性常

最低0.47元/天解锁文章

Cherry_tly

关注

0
点赞
踩
6

收藏

觉得还不错? 一键收藏
0
评论
velocity API 文档

官方网址：http://velocity.apache.org/engine/devel/user-guide.html关于本手册本手册的目的在于：帮助页面设计人员和内容提供者，了解Velocity及其简单但强大的脚本语言（VTL，Velocity模板语言）的语法。本手册中的许多例子，演示的是使用Velocity，在Web页面中，嵌入动态内容，但所有的VTL例子，同样适用于其他任何
复制链接

扫一扫