VTL指南

关于该指南About this Guide

这是关于Velocity模版语言的指南。要得到更多的信息，请参阅Velocity 用户手册。This guide is the reference for the Velocity Template Language (VTL). For more information, please also refer to the Velocity User Guide.

参考References

变量Variables

合法的变量规则：Notation:

$ [ ! ][ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ][ } ]

例子：Examples:

• Normal notation（普通的写法，如果mud-Slinger_9 不存在，则会显示mud-Slinger_9 ）: $mud-Slinger_9
• Silent notation（如果mud-Slinger_9 不存在，则不显示任何东西）: $!mud-Slinger_9
• Formal notation（正规的写法，能最正确的区别变量名字）: ${mud-Slinger_9}

  属性Properties

合法的规则：Notation:

$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]* .[a..z, A..Z ][ a..z, A-Z, 0..9, -, ]* [ } ]

例子 Examples:

• Regular Notation: $customer.Address
• Formal Notation: ${purchase.Total}

  方法Methods

合法的规则Notation:

$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]* .[ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]*( [ opional parameter list... ] ) [ } ]

例子：Examples:

• Regular Notation: $customer.getAddress()
• Formal Notation: ${purchase.getTotal()}
• Regular Notation with Parameter List（带有参数的方法的正规调用方式）: $page.setTitle( "My Home Page" )
  VTL属性调用（get和set方法）可以被简写。比如_$object.getMethod()和$object.setMethod()_ 方法都可以简写成_$object.Method_。在使用的时候，我们更偏好使用后者,即简化的写法。使用调用方法这种写法的最大的好处就在于你能向其中传递一些参数。VTL Properties can be used as a shorthand notation for VTL Methods that take get and set. Either $object.getMethod() or $object.setMethod() can be abbreviated as $object.Method. It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.

  语句Directives

#set - 给一个引用赋值Establishes the value of a reference

格式：Format:

#set( $*ref *= [ ", ' ]arg[ ", ' ] )

其中：Usage:

• $ref - 左操作数应该是一个变量的引用或者一个属性的引用。The LHS of the assignment must be a variable reference or a property reference.
• arg - 右操作，如果右操作数是被双引号括起来的话，那么在赋值给左操作数的时候，返回的是右操作数解析出来的值，如果右操作数是被单引号括起来的话，那么就直接赋值给左操作数。如果右操作数的解析的结果为null的话，不会给左操作数赋值。The RHS of the assignment, arg is parsed if enclosed in double quotes, and not parsed if enclosed in single quotes. If the RHS evaluates to null , it is not assigned to the LHS.

例子：Examples:

• 变量的引用：Variable reference: #set( $monkey = "bill" )
• 给属性赋值：String literal: #set( $monkey.Friend = "monica" )
• 属性赋值：Property reference: #set( $monkey.Blame = $whitehouse.Leak )
• 方法引用：Method reference: #set( $monkey.Plan = $spindoctor.weave($web) )
• Number literal: #set( $monkey.Number = 123 )
• Range operator: #set( $monkey.Numbers = [1..3] )
• Object array: #set( $monkey.Say = ["Not", $my, "fault"] )

右操作数也可以是简单的数学表达式，比如：The RHS can also be a simple arithmetic expression, such as:

• Addition: #set( $value = $foo + 1 )
• Subtraction: #set( $value = $bar - 1 )
• Multiplication: #set( $value = $foo * $bar )
• Division: #set( $value = $foo / $bar )
• Remainder: #set( $value = $foo % $bar )

  #if / #elseif / #else - output conditional on truth of statements条件控制语句

格式：Format:

#if( [condition] ) [output] [ #elseif( [condition] ) [output] ]* [ #else [output] ] #end

其中：Usage:

• condition - 如果是一个boolean的话，则根据值是true或者false来判断，如果不是一个boolean，则条件的值不为null则为true。If a boolean, considered true if it has a true false; if not a boolean, considered true if not null.
• output - May contain VTL.

例子：Examples:

• 相等操作Equivalent Operator: #if( $foo == $bar )
• 大于Greater Than: #if( $foo > 42 )
• 小于Less Than: #if( $foo < 42 )
• 不小于Greater Than or Equal To: #if( $foo >= 42 )
• 不大于Less Than or Equal To: #if( $foo <= 42 )
• 相等的值Equals Number: #if( $foo == 42 )
• 相等的字符串Equals String: #if( $foo == "bar" )
• 求反Boolean NOT: #if( !$foo )

  #foreach - Loops through a list of objects遍历一个列表

格式：Format:

#foreach( $ref in arg ) statement #end

其中：Usage:

• $ref - 遍历列表的当前引用。The first variable reference is the item.
• arg - 一个列表(比如一个对象数组，集合，map)，或者数组列表，或者范围操作。May be one of the following: a reference to a list (i.e. object array, collection, or map), an array list, or the range operator.
• 语句statement - 对每次通过遍历得到的一个值得操作。What is output each time Velocity finds a valid item in the list denoted above as arg . This output is any valid VTL and is rendered each iteration of the loop.

下面是省略了处理语句的#foreach()的例子：Examples of the #foreach(), omitting the statement block :

• 引用：Reference: #foreach ( $item in $items )
• 数组：Array list: #foreach ( $item in ["Not", $my, "fault"] )
• 范围：Range operator: #foreach ( $item in [1..3] )

Velocity提供了一个简单的得到循环次数的方法，所以你可以像下面这样操作：Velocity provides an easy way to get the loop counter so that you can do something like the following:

<table>
 #foreach( $customer in $customerList )

<tr>

<td>$velocityCount</td>

<td>$customer.Name</td>

</tr>

#end

</table>
默认的计数的变量是$velocityCount，不过，你也能在velocity.properties文件中进行自己的配置。默认的情况下，计数器是从1开始的，但是这也可以在velocity.properties文件中进行配置，也能从0开始计数。下面是在velocity.properties文件中对计数器的名字和起始值配置的代码片断：The default name for the loop counter variable reference, which is specified in the velocity.properties file, is $velocityCount. By default the counter starts at 1, but this can be set to either 0 or 1 in the velocity.properties file. Here's what the loop counter properties section of the velocity.properties file appears:

# Default name of the loop counter
# variable refernce.

counter.name = velocityCount

# Default starting value of the loop

# counter variable reference.

counter.initial.value = 1

#include -不加解释的合成本地文件Renders local file(s) that are not parsed by Velocity

格式：Format:

#include( arg[, arg2, ... argn] )

• arg - Refers to a valid file under TEMPLATE_ROOT.

例子：Examples:

• String: #include( "disclaimer.txt", "opinion.txt" )
• Variable: #include( $foo, $bar )

什么叫不加解释?就是说velocity只是把这个文件的内容直接合成到指定的位置，而如果在这个文件中也有VTL的语句，是不会翻译的。如果要实现这个功能，要用到下面的#parse。

#parse - 解释的合成本地模版Renders a local template that is parsed by Velocity

格式：Format:

#parse( arg )

• arg - Refers to a template under TEMPLATE_ROOT.

例子：Examples:

• String: #parse( "lecorbusier.vm" )
• Variable: #parse( $foo )

这里允许递归的调用。你可以在velocity.properties中改变parse_directive.maxdepth 的值来确定允许递归的层数。（默认的值为10）Recursion permitted. See parse_directive.maxdepth in velocity.properties to change from parse depth. (The default parse depth is 10.)

#stop - 停止模版引擎Stops the template engine

格式：Format:

#stop

Usage:

这个方法能停止执行当前的模版，很适合用于DEBUG。This will stop execution of the current template. This is good for debugging a template.

#macro - 允许用户定义一个Velocity宏（VM），能重用一些操作。Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required

格式：Format:

#macro( vmname $arg1 [ $arg2 $arg3 ... $argn ] ) [ VM VTL code... ] #end

• vmname - 宏的名字。Name used to call the VM ( #vmname )
• $arg1 $arg2 [ ... ] - 传递给VM的参数列表。参数的个数不限，但调用时候传入的参数必须和定义宏的时候规定的参数个数相同。Arguments to the VM. There can be any number of arguments, but the number used at invocation must match the number specified in the definition.
• [ VM VTL code... ] - 合法的VTL代码。任何能放在模版中的代码都能放在VM里面。Any valid VTL code, anything you can put into a template, can be put into a VM.

如果宏一旦定义，就可以像下面这样调用：Once defined, the VM is used like any other VTL directive in a template.

#vmname( $arg1 $arg2 )
VM可以在下面两个地方定义：VMs can be defined in one of two places:

1. Template library: can be either VMs pre-packaged with Velocity or custom-made, user-defined, site-specific VMs; available from any template
2. Inline: found in regular templates, only usable when velocimacro.permissions.allowInline=true in velocity.properties .

   注释Comments

被注释了的内容不会被合成。Comments are not rendered at runtime.

单行的注释Single Line

Example:

## This is a comment.

多行的注释Multi Line

Example:

#*
This is a multiline comment.
This is the second line
*#

posted on 2007-04-05 23:50 朱岩 阅读(563) 评论(0)  编辑  收藏 所属分类: Velocity文章