Velocity入门

Velocity

1、什么是Velocity？

官网：http://velocity.apache.org

Velocity是一个基于Java的模板引擎。它允许任何人使用简单而强大的模板语言来引用Java代码中定义的对象。

当Velocity用于Web开发时，Web设计人员可以与Java程序员并行工作，以根据模型 – 视图 – 控制器（MVC）模型开发Web站点，这意味着网页设计人员可以专注于创建一个看起来很好的站点，程序员可以专注于编写一流的代码。Velocity将Java代码与网页分开，使网站在其生命周期内更加可维护，并为Java Server Pages（JSP）或PHP提供了可行的替代方案。

Velocity的功能远远超出了网络的范围; 例如，它可以用于从模板生成SQL，PostScript和XML。它可以用作生成源代码和报告的独立实用程序，也可以用作其他系统的集成组件。例如，Velocity为各种Web框架提供模板服务，使他们能够根据真正的MVC模型，使视图引擎促进Web应用程序的开发。

2、Velocity提供的project

Velocity Engine——这是实现所有工作的实际模板引擎。（目前的版本是1.7）

Velocity Tools——项目包含使用Velocity引擎构建Web和非Web应用程序的工具和其他有用的基础设施。在此找到例如Struts集成的代码或独立的VelocityViewServlet。（目前的版本是2.0）

3、入门示例

      我的项目是用了Spring Boot的，开始想在Spring.io中直接添加Velocity的依赖，但是找不到依赖包，只能后面导入了。

      我的porm.xml如下：

然后在resource/templates下新建一个news.vm

 
  Hello Lily Velocity 
  

然后在src/main/java下新建一个controller包，在该包中新建一个IndexController类，添加Controller注解，写一个news函数：

@Controller public class IndexController {     @RequestMapping(value= { 
      "/vm"} )     public String news(){         return "news";     } }

然后运行Application，在127.0.0.1:8080中查看：

第一次报错：

看了控制台提示的错误：

因为我开始写的是：

return "news.vm";

但是其实Velocity是会默认给返回值后面再加一个.vm，所以就报错了。

改成return “news”;就可以了。

4、User-guide

官方文档：https://velocity.apache.org/engine/devel/user-guide.html

这个是Velocity的官方用户指南，里面写了很多Veloctiy的语法和使用规范，下面就来试试看吧~

1、注释Comment

单行注释以开始；

多行注释是 #*  *#；

VTL注释块， #    *# ，主要是用来存储类信息和作者版本信息。

2、References 引用

2.1 Variables变量

变量的简写符号由前导“$”字符，后跟VTL 标识符组成。VTL标识符必须以字母、数字和下划线组成，其他字符无效。

当VTL引用变量（如$ foo）时，变量可以从模板中的set指令或Java代码中获取其值。例如，如果Java变量$ foo在请求模板时具有值栏，则bar将替换网页上$ foo的所有实例。

举例：项目要显示用户名。

首先需要importorg.springframework.ui.Model;

news.vm文件：

 
  Hello Lily Velocity     这里是注解     #*     * 这里还是注解     * *#     username: $!{ 
         username} 
  
 

IndexController.java：

@RequestMapping(value= { 
      "/vm"} ) public String news(Model model){     model.addAttribute("username","Lily");     return "news"; }

2.2 Properties属性

属性具有独特的格式，$和.组成：

例子，$customer.Address。它可以有两个含义。这可以意味着，查看标识为客户的哈希表，并返回与地址相关联的值。但是$ customer.Address也可以指一个方法（参考方法的引用将在下一节讨论）;$ customer.Address可以是一个写入$ customer.getAddress（）的缩写方式。当您的页面被请求时，Velocity将确定这两种可能性中的哪一种是有意义的，然后返回适当的值。

项目的实例：首先需要在model包中写一个User类，属性有name和age，并且需要生成对应的setter和getter方法，和构造方法：

然后在Controller中写：

model.addAttribute("user",new User("Dianer",23));

然后在news.vm中写：

User:${ 
   user.name} User:${ 
   user.age}

2.3 Methods方法

以$开头，用.和（）来表示引用方法，方法中间还可以用 ””来填充参数。从Velocity 2.0开始，方法调用现在提供了所有Java基本内置类型之间的隐式转换：数字，布尔和字符串。

上面的User中的get和set方法，实践一下：

method:${ 
   user.getName()} method2:${ 
   user.setName("50")} method3:${ 
   user.getName()}

2.4 Property Lookup Rules 属性查找规则

属性通常引用父对象的方法，确定哪个方法对应所请求的属性，Velocity根据下列命名约定尝试不同的替代方法：

1.    getaddress()

2.    getAddress()

3.    get(“address”)

4.    isAddress()

2.5 Rendering 渲染

将每个引用（无论是变量，属性还是方法）生成的最终值在呈现为最终输出时都将转换为String对象。如果有一个代表$ foo的对象（例如Integer对象），那么Velocity将调用它的.toString()方法来将对象解析成一个String。

2.6 Index Notation 索引符号

      使用表单的符号$foo[0]可以用于访问对象的给定索引。此形式与在给定对象上调用get（Object）方法同义。

$foo[0]        $foo takes in an Integer look up

$foo[$i]       Using another reference as the index   

$foo["bar"]    Passing a string where $foo may be a Map

3、Formal Reference Notation正式参考符号

示例： ${vice}

一般用简写的符号 $vice ，跟上面的意思是一样的。但是由于可能存在歧义，比如Jack is a $vicemaniac ，这个时候就需要用正式的参考符号来消除歧义。

      当引用与模板中的文本直接相邻时，正式符号通常很有用。

4、Quiet Reference Notation安静参考符号

这是 ！ 的区别：

例如：

type="text" name="email" value="$email"/>    type="text" name="email" value="$!email"/>    type="text" name="email" value="$!{ 
         email}"/>

只有第一个框中有 $email ，后面两个是没有的。后面两个框：当初始加载表单并且$ email仍然没有值时，将输出一个空字符串，而不是“$ email”。

5、Strict Reference Mode严格参考符号

Velocity 1.6引入了通过将速度配置属性“runtime.references.strict”设置为true来激活的严格参考模式的概念。这种设置的一般目的是使Velocity在未定义或不明确的情况下更严格地执行，类似于编程语言，这可能更适合于Velocity的某些用途。在这种未定义或不明确的情况下，Velocity会抛出异常。

使用此设置，引用需要被明确地放置到上下文中或者用#set指令定义，否则Velocity将抛出异常。在值为null的上下文中的引用不会产生异常。另外，如果尝试调用引用中没有定义指定方法或属性的对象的方法或属性，那么Velocity将抛出异常。如果尝试在null值上调用方法或属性，这也是正确的。

6、Case Substitution 案例替换

Velocity利用Java的内省和bean特性，将Context中的对象的引用名称以及objects方法解析。可以在模板中几乎任何地方嵌入和评估引用。

以SunMicrosystems定义的Bean规范为基础的Velocity是区分大小写的; 然而，其开发人员尽可能地努力捕捉和纠正用户错误。当方法getFoo（）在模板中引用时$bar.foo，Velocity将首先尝试$getfoo。如果这样做失败，那么会尝试$getFoo。同样，当模板引用时$bar.Foo，Velocity会首先尝试$ getFoo（），然后尝试getfoo（）。

注意：模板中对实例变量的引用未解决。只有引用JavaBean getter / setter方法的属性等同于解析（即$foo.Name解析为Foo类的getName()实例方法，而不是Foo的公共Name实例变量）。

相同的示例有：

$foo.getBar()

 is the same as

$foo.Bar

$data.setUser("jon")

 is the same as

#set( $data.User = "jon" )

$data.getRequest().getServerName()

 is the same as

$data.Request.ServerName

 is the same as

${data.Request.ServerName}

7、Directives指令

指令以#开头。

引用允许模板设计者为网站生成动态内容，而指令 – 易于使用的脚本元素，可用于创造性地操纵Java代码的输出 – 允许网页设计师真正负责网站的外观和内容现场。

7.1、Set

#set指令没有#end语句，这个要特别注意。

#set($user.age=18) age:${ 
   user.getAge()}

7.1.1、Literals文本

当使用#set指令时，将会解析和呈现包含在双引号字符中的字符串文字。但是，当字符串文字包含在单引号字符中时，将不会被解析。另外，Velocity提供 #[[don’t parse me!]]# ，使[[]]中间的内容不被解析。

举例：

#set( $directoryRoot = "www" )

#set( $templateName = "index.vm" )

#set( $template = "$directoryRoot/$templateName" )

$template

输出为：www/index.vm

7.2、Conditionals条件语句

7.2.1、If / ElseIf / Else

 #if( $user )     Velocity! #end

#set($foo=10) #if( $foo < 10 )     Go North #elseif( $foo == 10 )     Go East #elseif( $bar == 6 )     Go South #else     Go West

Velocity会对if后的($foo)进行评估，确定是否为真：

$ foo是一个具有真实值的布尔值（true/ false）

$ foo的是一个字符串或一个集合，其不为空和不为空

$ foo是等于零的数字

$ foo是一个不为空的对象（字符串，数字或集合除外）

使用if elseif 的时候，Velocity引擎会在发现第一个为真的表达式时停止。

7.2.2、Relational and LogicalOperators 关系和逻辑运算符

Velocity的运算符有== ，&&，|| ，！ ，跟Java差不多，但是略有不同的是，Java的==只能判断对象是否相等，而Velocity是可以直接比较数字、字符串、对象是否相等的，当对象不同时，会调用toString()方法来比较。

7.3、Loops循环

7.3.1、Foreach Loop

Velocity使用foreach循环。对象可以是Vector，HashMap或者是Array。

（1）当对象是Array时：

Controller:

List 
  
    colors = Arrays. 
   asList( 
  new String[]{ 
  "RED", "GREEN", "BLUE"}); model.addAttribute("colors", colors);

news.vm

#foreach ($color in $colors)     Color $!{ 
   foreach.index}/$!{ 
   foreach.count}: $!{ 
   color} #end

（2）当对象是map时：

Controller:

Map 
   
   ,  
   String> map =  
   new  
   HashMap 
     
     ,  
     String>() 
     ; for  
     ( 
     int  
     i =  
     0 
     ;  
     i <  
     4 
     ;  
     ++i) {     map.put(String.valueOf(i) 
     ,  
     String.valueOf(i * i)) 
     ;  
     } model.addAttribute( 
     "map" 
     ,  
     map) 
     ; 
     
  

news.vm：

#foreach($key in $map.keySet())     Number $!{ 
   foreach.index}/$!{ 
   foreach.count}: $!{ 
   key} $map.get($key) #end

7.4、Include 包含

#include脚本元素允许模板设计者导入本地文件，然后将其插入到其中的位置的#include指令定义。该文件的内容不会通过模板引擎呈现。

示例：在templates下新建一个hello.vm

Title  
   
   $! 
  titleLily 
  

然后在news.vm中include进去：

#set($title = "FastNews") Include: #include("hello.vm")

运行的结果显示，这里的set并不会填充到hello.vm中。

7.5、Parse解析

#parse脚本元素允许模板设计者导入包含VTL的本地文件。Velocity将解析VTL并渲染指定的模板。像#include指令一样，# parse可以使用变量而不是模板。#parse引用的任何模板必须包含在TEMPLATE_ROOT下。与#include指令不同，# parse只会使用一个参数。

#parse("hello.vm")

运行结果显示：这里就可以将title填充。

7.6、Break

#break指令停止当前执行范围的任何进一步渲染。“执行范围”本质上是内容的任何指令（即#foreach，#parse，#evaluate，#define，#macro或＃@ somebodymacro）或任何“根”范围（即template.merge（…） Velocity.evaluate（…）或velocityEngine.evaluate（…））。与#stop不同，#break只会停止最内层，即时范围，而不是全部。

7.7、Stop

停止模板的任何进一步的渲染和执行。

7.8、Evaluate 评估

#evaluate指令可用于动态评估VTL。这允许模板评估在渲染时创建的字符串。这样的字符串可能用于国际化模板或从数据库中包含模板的部分。

示例：

#set($source1 = "abc")  #set($select = "1")  #set($dynamicsource = "$source$select")  $dynamicsource is now the string '$source1'  #evaluate($dynamicsource)

显示的是abc而不是abc1.