關(guān)于該指南About this Guide
這是關(guān)于Velocity模版語(yǔ)言的指南。要得到更多的信息，請(qǐng)參閱Velocity 用戶(hù)手冊(cè)。This guide is the reference for the Velocity Template Language (VTL). For more information, please also refer to the Velocity User Guide.
參考References
變量Variables
合法的變量規(guī)則：Notation:
$ [ ! ][ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ][ } ]
例子：Examples:
- Normal notation（普通的寫(xiě)法，如果mud-Slinger_9 不存在，則會(huì)顯示mud-Slinger_9 ）: $mud-Slinger_9
- Silent notation（如果mud-Slinger_9 不存在，則不顯示任何東西）: $!mud-Slinger_9
- Formal notation（正規(guī)的寫(xiě)法，能最正確的區(qū)別變量名字）: ${mud-Slinger_9}
屬性Properties
合法的規(guī)則：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
合法的規(guī)則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（帶有參數(shù)的方法的正規(guī)調(diào)用方式）: $page.setTitle( "My Home Page" )
VTL屬性調(diào)用（get和set方法）可以被簡(jiǎn)寫(xiě)。比如_$object.getMethod()和$object.setMethod()_ 方法都可以簡(jiǎn)寫(xiě)成_$object.Method_。在使用的時(shí)候，我們更偏好使用后者,即簡(jiǎn)化的寫(xiě)法。使用調(diào)用方法這種寫(xiě)法的最大的好處就在于你能向其中傳遞一些參數(shù)。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.
語(yǔ)句Directives
#set - 給一個(gè)引用賦值Establishes the value of a reference
格式：Format:
#set( $*ref *= [ ", ' ]arg[ ", ' ] )
其中：Usage:
- $ref - 左操作數(shù)應(yīng)該是一個(gè)變量的引用或者一個(gè)屬性的引用。The LHS of the assignment must be a variable reference or a property reference.
- arg - 右操作，如果右操作數(shù)是被雙引號(hào)括起來(lái)的話(huà)，那么在賦值給左操作數(shù)的時(shí)候，返回的是右操作數(shù)解析出來(lái)的值，如果右操作數(shù)是被單引號(hào)括起來(lái)的話(huà)，那么就直接賦值給左操作數(shù)。如果右操作數(shù)的解析的結(jié)果為null的話(huà)，不會(huì)給左操作數(shù)賦值。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"] )
右操作數(shù)也可以是簡(jiǎn)單的數(shù)學(xué)表達(dá)式，比如：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條件控制語(yǔ)句
格式：Format:
#if( [condition] ) [output] [ #elseif( [condition] ) [output] ]* [ #else [output] ] #end
其中：Usage:
- condition - 如果是一個(gè)boolean的話(huà)，則根據(jù)值是true或者false來(lái)判斷，如果不是一個(gè)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遍歷一個(gè)列表
格式：Format:
#foreach( $ref in arg ) statement #end
其中：Usage:
- $ref - 遍歷列表的當(dāng)前引用。The first variable reference is the item.
- arg - 一個(gè)列表(比如一個(gè)對(duì)象數(shù)組，集合，map)，或者數(shù)組列表，或者范圍操作。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.
- 語(yǔ)句statement - 對(duì)每次通過(guò)遍歷得到的一個(gè)值得操作。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.
下面是省略了處理語(yǔ)句的#foreach()的例子：Examples of the #foreach(), omitting the statement block :
- 引用：Reference: #foreach ( $item in $items )
- 數(shù)組：Array list: #foreach ( $item in ["Not", $my, "fault"] )
- 范圍：Range operator: #foreach ( $item in [1..3] )
Velocity提供了一個(gè)簡(jiǎn)單的得到循環(huán)次數(shù)的方法，所以你可以像下面這樣操作：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>
默認(rèn)的計(jì)數(shù)的變量是$velocityCount，不過(guò)，你也能在velocity.properties文件中進(jìn)行自己的配置。默認(rèn)的情況下，計(jì)數(shù)器是從1開(kāi)始的，但是這也可以在velocity.properties文件中進(jìn)行配置，也能從0開(kāi)始計(jì)數(shù)。下面是在velocity.properties文件中對(duì)計(jì)數(shù)器的名字和起始值配置的代碼片斷：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 )
什么叫不加解釋?就是說(shuō)velocity只是把這個(gè)文件的內(nèi)容直接合成到指定的位置，而如果在這個(gè)文件中也有VTL的語(yǔ)句，是不會(huì)翻譯的。如果要實(shí)現(xiàn)這個(gè)功能，要用到下面的#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 )
這里允許遞歸的調(diào)用。你可以在velocity.properties中改變parse_directive.maxdepth 的值來(lái)確定允許遞歸的層數(shù)。（默認(rèn)的值為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:
這個(gè)方法能停止執(zhí)行當(dāng)前的模版，很適合用于DEBUG。This will stop execution of the current template. This is good for debugging a template.
#macro - 允許用戶(hù)定義一個(gè)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的參數(shù)列表。參數(shù)的個(gè)數(shù)不限，但調(diào)用時(shí)候傳入的參數(shù)必須和定義宏的時(shí)候規(guī)定的參數(shù)個(gè)數(shù)相同。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.
如果宏一旦定義，就可以像下面這樣調(diào)用：Once defined, the VM is used like any other VTL directive in a template.
#vmname( $arg1 $arg2 )
VM可以在下面兩個(gè)地方定義：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
被注釋了的內(nèi)容不會(huì)被合成。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
*#