關于該指南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:
- Template library: can be either VMs pre-packaged with Velocity or custom-made, user-defined, site-specific VMs; available from any template
- 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
*#