Velocity用戶手冊(cè)
英文源文件：http://jakarta.apache.org/velocity/user-guide.html
目錄
1. About this Guide
2. What is Velocity?
3. What can Velocity do for me?
1. The Mud Store example
4. Velocity Template Language (VTL): An Introduction
5. Hello Velocity World!
6. Comments
7. References
1. Variables
2. Properties
3. Methods
8. Formal Reference Notation
9. Quiet Reference Notation
10. Getting literal
1. Currency
2. Escaping Valid VTL References
11. Case Substitution
12. Directives
1. Set
2. String Literals
3. If-Else Statements
1. Relational and Logical Operators
4. Foreach Loops
5. Include
6. Parse
7. Stop
8. Velocimacros
2. Escaping VTL Directives
3. VTL: Formatting Issues
4. Other Features and Miscellany
1. Math
2. Range Operator
3. Advanced Issues: Escaping and !
4. Velocimacro Miscellany
5. String Concatenation
5. Feedback
Velocity是什么？
Velocity是一個(gè)基于java的模板引擎（template engine）。它允許任何人僅僅簡(jiǎn)單的使用模板語(yǔ)言（template language）來(lái)引用由java代碼定義的對(duì)象。
當(dāng)Velocity應(yīng)用于web開(kāi)發(fā)時(shí)，界面設(shè)計(jì)人員可以和java程序開(kāi)發(fā)人員同步開(kāi)發(fā)一個(gè)遵循MVC架構(gòu)的web站點(diǎn)，也就是說(shuō)，頁(yè)面設(shè)計(jì)人員可以只關(guān)注頁(yè)面的顯示效果，而由java程序開(kāi)發(fā)人員關(guān)注業(yè)務(wù)邏輯編碼。Velocity將java代碼從web頁(yè)面中分離出來(lái)，這樣為web站點(diǎn)的長(zhǎng)期維護(hù)提供了便利，同時(shí)也為我們在JSP和PHP之外又提供了一種可選的方案。
Velocity的能力遠(yuǎn)不止web站點(diǎn)開(kāi)發(fā)這個(gè)領(lǐng)域，例如，它可以從模板（template）產(chǎn)生SQL和PostScript、XML，它也可以被當(dāng)作一個(gè)獨(dú)立工具來(lái)產(chǎn)生源代碼和報(bào)告，或者作為其他系統(tǒng)的集成組件使用。Velocity也可以為Turbine web開(kāi)發(fā)架構(gòu)提供模板服務(wù)（template service）。Velocity+Turbine提供一個(gè)模板服務(wù)的方式允許一個(gè)web應(yīng)用以一個(gè)真正的MVC模型進(jìn)行開(kāi)發(fā)。
Velocity能為我們作什么？
The Mud Store Example
假設(shè)你是一家專門出售Mud的在線商店的頁(yè)面設(shè)計(jì)人員，讓我們暫且稱它為"在線MUD商店"。你們的業(yè)務(wù)很旺，客戶下了各種類型和數(shù)量的mud訂單。他們都是通過(guò)輸入用戶名和密碼后才登陸到你的網(wǎng)站，登陸后就允許他們查看訂單并購(gòu)買更多的mud。現(xiàn)在，一種非常流行的mud正在打折銷售。另外有一些客戶規(guī)律性的購(gòu)買另外一種也在打折但是不是很流行的Bright Red Mud，由于購(gòu)買的人并不多所以它被安置在頁(yè)面的邊緣。所有用戶的信息都是被跟蹤并存放于數(shù)據(jù)庫(kù)中的，所以某天有一個(gè)問(wèn)題可能會(huì)冒出來(lái)：為什么不使用velocity來(lái)使用戶更好的瀏覽他們感興趣的商品呢？
Velocity使得web頁(yè)面的客戶化工作非常容易。作為一個(gè)web site的設(shè)計(jì)人員，你希望每個(gè)用戶登陸時(shí)都擁有自己的頁(yè)面。
你會(huì)見(jiàn)了一些公司內(nèi)的軟件工程師，你發(fā)現(xiàn)他們每個(gè)人都同意客戶應(yīng)該擁有具有個(gè)性化的信息。那讓我們把軟件工程師應(yīng)該作的事情發(fā)在一邊，看一看你應(yīng)該作些什么吧。
你可能在頁(yè)面內(nèi)嵌套如下的VTL聲明：
<html>
<body>
Hello $customer.Name!
<table>
#foreach( $mud in $nudsOnSpecial )
#if ( $customer.hasPurchased( $mud ) )
<tr>
<td>
$flogger.getPromo( $mud )
<td>
<tr>
#end
#end
</table>
Velocity Template Language(VTL):AN introduction
VTL意味著提供最簡(jiǎn)單、最容易并且最整潔的方式合并頁(yè)面動(dòng)態(tài)內(nèi)容。
VTL使用references來(lái)在web site內(nèi)嵌套動(dòng)態(tài)內(nèi)容，一個(gè)變量就是一種類型的reference。變量是某種類型的refreence，它可以指向java代碼中的定義，或者從當(dāng)前頁(yè)面內(nèi)定義的VTL statement得到值。下面是一個(gè)VTL statement的例子，它可以被嵌套到HTML代碼中：
#set ( $a = "Velocity" )
和所有的VTL statement一樣，這個(gè)statement以＃字符開(kāi)始并且包含一個(gè)directive：set。當(dāng)一個(gè)在線用戶請(qǐng)求你的頁(yè)面時(shí)，Velocity Templating Engine將查詢整個(gè)頁(yè)面以便發(fā)現(xiàn)所有＃字符，然后確定哪些是VTL statement，哪些不需要VTL作任何事情。
＃字符后緊跟一個(gè)directive：set時(shí)，這個(gè)set directive使用一個(gè)表達(dá)式（使用括號(hào)封閉）――一個(gè)方程式分配一個(gè)值給變量。變量被列在左邊，而它的值被列在右邊，最后他們之間使用＝號(hào)分割。
在上面的例子中，變量是$a，而它的值是Velocity。和其他的references一樣以$字符開(kāi)始，而值總是以雙引號(hào)封閉。Velocity中僅有String可以被賦值給變量。
記住以下的規(guī)則：
使用$字符開(kāi)始的references用于得到什么；使用#字符開(kāi)始的directives用于作些什么。
Hello Velocity World!
一旦某個(gè)變量被分配了一個(gè)值，那么你就可以在HTML文件的任何地方引用它。在下面的例子中，一個(gè)值被分配給$foo變量，并在其后被引用。
<html>
<body>
#set ( $foo = "Velocity" )
Hello $foo World!
</body>
</html>
上面的實(shí)現(xiàn)結(jié)果是在頁(yè)面上打印"Hello Velocity World！"
為了使包含VTL directives的statement更具有可讀性，我們鼓勵(lì)你在新行開(kāi)始每個(gè)VTL statement，盡管你不是必須這么作。Set directive將在后面詳細(xì)描述。
注釋
單行注釋：
## This is a single line comment.
多行注釋：
#*
Thus begins a multi-line comment. Online visitors won't
see this text because the Velocity Templating Engine will
ignore it.
*#
文檔格式：
#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
information:
@version 5
@author
*#
References
在VTL中有三種類型的references：變量(variables)、屬性(properties)、方法(methods)。作為一個(gè)使用VTL的頁(yè)面設(shè)計(jì)者，你和你的工程師必須就references的名稱達(dá)成共識(shí)，以便你可以在你的template中使用它們。
Everything coming to and from a reference被作為一個(gè)String對(duì)象處理。如果有一個(gè)對(duì)象$foo是一個(gè)Integer對(duì)象，那么Velocity將調(diào)用它的toString()方法將這個(gè)對(duì)象轉(zhuǎn)型為String類型。
變量
格式要求同java。
屬性
例子：
$customer.Address
$purchase.Total
$customer.Address有兩種含義。它可以表示：查找hashtable對(duì)象customer中以Address為關(guān)鍵字的值；也可以表示調(diào)用customer對(duì)象的getAddress()方法。當(dāng)你的頁(yè)面被請(qǐng)求時(shí)，Velocity將確定以上兩種方式選用那種，然后返回適當(dāng)?shù)?/span>值。
方法
一個(gè)方法就是被定義在java中的一段代碼，并且它有完成某些有用工作的能力，例如一個(gè)執(zhí)行計(jì)算和判斷條件是否成立、滿足等。方法是一個(gè)由$開(kāi)始并跟隨VTL標(biāo)識(shí)符組成的References，一般還包括一個(gè)VTL方法體。例如：
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
前兩個(gè)例子$customer.getAddress()和$purchase.getTotal()看起來(lái)挺想上面的屬性$customer.Address 和 $purchase.Total。如果你覺(jué)得他們之間有某種聯(lián)系的話，那你是正確的。
VTL屬性可以作為VTL方法的縮寫(xiě)。$customer.Address屬性和使用$customer.getAddress()方法具有相同的效果。如果可能的話使用屬性的方式是比較合理的。屬性和方法的不同點(diǎn)在于你能夠給一個(gè)方法指定一個(gè)參數(shù)列表。
正式reference標(biāo)記
reference的正是格式如下：
${mudSlinger} 變量
${customer.Address} 屬性
${purchase.getTotal()} 方法
非正是格式更見(jiàn)常用，但是有時(shí)還是使用正是格式比較適合。例如：你希望通過(guò)一個(gè)變量$vice來(lái)動(dòng)態(tài)的組織一個(gè)字符串。
Jack is a $vicemaniac.
本來(lái)變量是$vice現(xiàn)在卻變成了$vicemaniac，這樣Veloctiy就不知道您到底要什么了。所以，應(yīng)該使用正是格式書(shū)寫(xiě)
Jack is a ${vice}maniac
現(xiàn)在Velocity知道變量是$vice而不是$vicemaniac。
Quiet reference notation
例如：
<input type="text" name="email" value="$email" />
當(dāng)頁(yè)面的form被初始加載時(shí)，變量$email還沒(méi)有值，這時(shí)你肯定是希望它能夠顯示一個(gè)blank text來(lái)代替輸出"$email"這樣的字段。那么使用quiet reference notation就比較合適。
<input type="text" name="email" value="$!email"/>
這樣文本框的初始值就不會(huì)是email而是空值了。
正式和quiet格式的reference notation也可一同使用，像下面這樣：
<input type="text" name="email" value="$!{email}"/>
Getting literal
Velocity使用特殊字符$和#來(lái)幫助它工作，所以如果要在template里使用這些特殊字符要格外小心。本節(jié)將討論$字符。
貨幣字符
在VTL中使用$2.5這樣的貨幣標(biāo)識(shí)是沒(méi)有問(wèn)題得的，VTL不會(huì)將它錯(cuò)認(rèn)為是一個(gè)reference，因為VTL中的reference總是以一個(gè)大寫(xiě)或者小寫(xiě)的字母開(kāi)始。
Escaping valid VTL reference
VTL中使用"\"作為逃逸符。
例如：
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
將render為：
foo
$email
\foo
\\$email
如果email變量沒(méi)有被定義則
$email
\$email
\\$email
\\\$email
將被render為：
$email
\$email
\\$email
\\\$email
注意：VTL中未被定義的變量將被認(rèn)為是一個(gè)字符串，所以以下例子：
#set( $foo = "gibbous" )
$moon = $foo
的輸出結(jié)果是：
$moon = gibbous
Case substitution
現(xiàn)在你已經(jīng)對(duì)reference比較熟悉了，你可以將他們高效的應(yīng)用于你的template了。Velocity利用了很多java規(guī)范以方便了設(shè)計(jì)人員的使用。例如：
$foo
$foo.getBar()
## is the same as
$foo.Bar
$data.getUser("jon")
## is the same as
$data.User("jon")
$data.getRequest().getServerName()
# is the same as
$data.Request.ServerName
## is the same as
${data.Request.ServerName}
但是，注意VTL中不會(huì)將reference解釋為對(duì)象的實(shí)例變量。例如：$foo.Name將被解釋為Foo對(duì)象的getName（）方法，而不是Foo對(duì)象的Name實(shí)例變量。
Directives
Reference允許設(shè)計(jì)者使用動(dòng)態(tài)的內(nèi)容，而directive使得你可以應(yīng)用java代碼來(lái)控制你的顯示邏輯，從而達(dá)到你所期望的顯示效果。
#set
#set directive被用于設(shè)置一個(gè)reference的值。例如：
#set ( $primate = "monkey" )
#set ( $customer.Behavior = $primate )
賦值左側(cè)的（LHS）必須是一個(gè)變量或者屬性reference。右側(cè)（RHS）可以是以下類型中一種：
變量reference
String literal
屬性reference
方法reference
number literal
ArrayList
下面是應(yīng)用各種類型的RHS的例子：
＃set ( $monkey = $bill ) ##變量reference
＃set ( $monkey.Friend = "monica" ) ##String literal
＃set ( $monkey.Blame = $whitehouse.Leak )##屬性reference
＃set ( $monkey.Plan = $spindoctor.weave($web) )##方法reference
＃set ( $monkey.Number = 123 )##Number literal
＃set ( $monkey.Say = ["Not", $my, "fault"] )##ArrayList
注意：最后一個(gè)例子的取值方法為：$monkey.Say.get(0)
RHS也可以是一個(gè)簡(jiǎn)單的算術(shù)表達(dá)式：
#set ( $value = $foo + 1 )
#set ( $value = $bar -1 )
#set ( $value = $foo * $bar )
#set ( $value = $foo / $bar )
如果你的RHS是一個(gè)null，VTL的處理將比較特殊：它將指向一個(gè)已經(jīng)存在的reference，這對(duì)初學(xué)者來(lái)講可能是比較費(fèi)解的。例如：
#set ( $resut = $query.criteria("name") )
The result of the first query is $result
#set ( $resut = $query.criteria("address") )
The result of the second query is $result
如果$query.criteria("name")返回一個(gè)"bill"，而$query.criteria("address")返回的是null，則顯示的結(jié)果如下：
The result of the first query is bill
The result of the first query is bill
看看下面的例子：
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
在上面的例子中，程序?qū)⒉荒苤悄艿母鶕?jù)$result的值決定查詢是否成功。在$result被#set后（added to the context），它不能被設(shè)置回null（removed from the context）。打印的結(jié)果將顯示兩次查詢結(jié)果都成功了，但是實(shí)際上有一個(gè)查詢是失敗的。
為了解決以上問(wèn)題我們可以通過(guò)預(yù)先定義的方式：
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria( $criterion ) )
#if( $result )
Query was successful
#end
#end
String Literals
當(dāng)你使用#set directive，String literal封閉在一對(duì)雙引號(hào)內(nèi)。
#set ( $directoryRoot = "www" )
#set ( $templateName = "index.vm" )
#set ( $template = "$directoryRoot/$tempateName" )
$template
上面這段代碼的輸出結(jié)果為：www/index.vm
但是，當(dāng)string literal被封裝在單引號(hào)內(nèi)時(shí)，它將不被解析：
#set ( $foo = "bar" )
$foo
#set ( $blargh = '$foo' )
結(jié)果：
bar
$foo
上面這個(gè)特性可以通過(guò)修改velocity.properties文件的stringliterals.interpolate = false的值來(lái)改變上面的特性是否有效。
條件語(yǔ)句
if/elseif/else
當(dāng)一個(gè)web頁(yè)面被生成時(shí)使用Velocity的#if directrive，如果條件成立的話可以在頁(yè)面內(nèi)嵌入文字。例如：
#if ( $foo )
<strong>Velocity!</strong>
#end
上例中的條件語(yǔ)句將在以下兩種條件下成立：
$foo是一個(gè)boolean型的變量，且它的值為true
$foo變量的值不為null
這里需要注意一點(diǎn)：Velocity context僅僅能夠包含對(duì)象，所以當(dāng)我們說(shuō)"boolean"時(shí)實(shí)際上代表的時(shí)一個(gè)Boolean對(duì)象。即便某個(gè)方法返回的是一個(gè)boolean值，Velocity也會(huì)利用內(nèi)省機(jī)制將它轉(zhuǎn)換為一個(gè)Boolean的相同值。
如果條件成立，那么#if和#end之間的內(nèi)容將被顯示。
#elseif和#else元素可以同#if一同使用。例如：
#if( $foo < 10 )
<strong> Go North </strong>
#elseif( $foo == 10 )
<strong> Go East </strong>
#elseif( $foo == 6 )
<strong> Go South </strong>
#else
<strong> Go West </strong>
#end
注意這里的Velocity的數(shù)字是作為Integer來(lái)比較的――其他類型的對(duì)象將使得條件為false，但是與java不同它使用"＝＝"來(lái)比較兩個(gè)值，而且velocity要求等號(hào)兩邊的值類型相同。
關(guān)系、邏輯運(yùn)算符
Velocity中使用等號(hào)操作符判斷兩個(gè)變量的關(guān)系。例如：
#set ( $foo = "deoxyribonucleic acid" )
#set ( $bar = "ribonucleic acid" )
#if ( $foo == $foo )
In this case it's clear they aren't equivalent.So…
#else
They are not equivalent and this will be the output.
#end
Velocity有AND、OR和NOT邏輯運(yùn)算符。下面是一些例子：
## logical AND
#if( $foo && $bar )
<strong> This AND that </strong>
#end
## logical OR
#if ( $foo || $bar )
<strong>This OR That </strong>
#end
##logical NOT
#if ( !$foo )
<strong> NOT that </strong>
#end
循環(huán)
Foreach循環(huán)
例子：
<ul>
#foreach ( $product in $allProducts )
<li> $product </li>
#end
</ul>
每次循環(huán)$allProducts中的一個(gè)值都會(huì)賦給$product變量。
$allProducts可以是一個(gè)Vector、Hashtable或者Array。分配給$product的值是一個(gè)java對(duì)象，并且可以通過(guò)變量被引用。例如：如果$product是一個(gè)java的Product類，并且這個(gè)產(chǎn)品的名字可以通過(guò)調(diào)用他的getName（）方法得到。
現(xiàn)在我們假設(shè)$allProducts是一個(gè)Hashtable，如果你希望得到它的key應(yīng)該像下面這樣：
<ul>
#foreach ( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key) </li>
#end
</ul>
Velocity還特別提供了得到循環(huán)次數(shù)的方法，以便你可以像下面這樣作：
<table>
#foreach ( $customer in $customerList )
<tr><td>$velocityCount</td><td>$customer.Name</td></tr>
#end
</table>
$velocityCount變量的名字是Velocity默認(rèn)的名字，你也可以通過(guò)修改velocity.properties文件來(lái)改變它。默認(rèn)情況下，計(jì)數(shù)從"1"開(kāi)始，但是你可以在velocity.properties設(shè)置它是從"1"還是從"0"開(kāi)始。下面就是文件中的配置：
# Default name of loop counter
# variable reference
directive.foreach.counter.name = velocityCount
# Default starting value of the loop
# counter variable reference
directive.foreach.counter.initial.value = 1
include
#include script element允許模板設(shè)計(jì)者引入本地文件。被引入文件的內(nèi)容將不會(huì)通過(guò)模板引擎被render。為了安全的原因，被引入的本地文件只能在TEMPLATE_ROOT目錄下。
#inclued ( "one.txt" )
如果您需要引入多個(gè)文件，可以用逗號(hào)分隔就行：
#include ( "one.gif", "two.txt", "three.htm" )
在括號(hào)內(nèi)可以是文件名，但是更多的時(shí)候是使用變量的：
#inclue ( "greetings.txt", $seasonalstock )
parse
#parse script element允許模板設(shè)計(jì)者一個(gè)包含VTL的本地文件。Velocity將解析其中的VTL并render模板。
#parse( "me.vm" )
就像#include，#parse接受一個(gè)變量而不是一個(gè)模板。任何由#parse指向的模板都必須包含在TEMPLATE_ROOT目錄下。與#include不同的是，#parse只能指定單個(gè)對(duì)象。
你可以通過(guò)修改velocity.properties文件的parse_direcive.maxdepth的值來(lái)控制一個(gè)template可以包含的最多#parse的個(gè)數(shù)――默認(rèn)值是10。#parse是可以遞歸調(diào)用的，例如：如果dofoo.vm包含如下行：
Count down.
#set ( $count = 8 )
#parse ( "parsefoo.vm" )
All done with dofoo.vm!
那么在parsefoo.vm模板中，你可以包含如下VTL：
$count
#set ( $count = $count - 1 )
#if ( $count > 0 )
#parse( "parsefoo.vm" )
#else
All done with parsefoo.vm!
#end
的顯示結(jié)果為：
Count down.
8
7
6
5
4
3
2
1
0
All done with parsefoo.vm!
All done with dofoo.vm!
Stop
#stop script element允許模板設(shè)計(jì)者停止執(zhí)行模板引擎并返回。把它應(yīng)用于debug是很有幫助的。
#stop
Velocimacros
#macro script element允許模板設(shè)計(jì)者定義一段可重用的VTL template。例如：
#macro ( d )
<tr><td></td></tr>
#end
在上面的例子中Velocimacro被定義為d，然后你就可以在任何VTL directive中以如下方式調(diào)用它：
#d()
當(dāng)你的template被調(diào)用時(shí)，Velocity將用<tr><td></td></tr>替換為#d()。
每個(gè)Velocimacro可以擁有任意數(shù)量的參數(shù)――甚至0個(gè)參數(shù)，雖然定義時(shí)可以隨意設(shè)置參數(shù)數(shù)量，但是調(diào)用這個(gè)Velocimacro時(shí)必須指定正確的參數(shù)。下面是一個(gè)擁有兩個(gè)參數(shù)的Velocimacro，一個(gè)參數(shù)是color另一個(gè)參數(shù)是array：
#macro ( tablerows $color $somelist )
#foreach ( $something in $somelist )
<tr><td bgcolor=$color>$something</td</tr>
#end
#end
調(diào)用#tablerows Velocimacro：
#set ( $greatlakes = [ "Superior", "Michigan", "Huron", "Erie", "Ontario" ] )
#set ( $color = "blue" )
<table>
#tablerows( $color $greatlakes )
</table>
經(jīng)過(guò)以上的調(diào)用將產(chǎn)生如下的顯示結(jié)果：
<table>
<tr><td bgcolor=" blue"> Superior </td></tr>
<tr><td bgcolor=" blue"> Michigan </td></tr>
<tr><td bgcolor=" blue"> Huron </td></tr>
<tr><td bgcolor=" blue"> Erie </td></tr>
<tr><td bgcolor=" blue"> Ontario </td></tr>
</table>
Velocimacros可以在Velocity模板內(nèi)實(shí)現(xiàn)行內(nèi)定義（inline），也就意味著同一個(gè)web site內(nèi)的其他Velocity模板不可以獲得Velocimacros的定義。定義一個(gè)可以被所有模板共享的Velocimacro顯然是有很多好處的：它減少了在一大堆模板中重復(fù)定義的數(shù)量、節(jié)省了工作時(shí)間、減少了出錯(cuò)的幾率、保證了單點(diǎn)修改。
上面定義的#tablerows( $color $list )Velocimacro被定義在一個(gè)Velocimacros模板庫(kù)(在velocity.properties中定義)里，所以這個(gè)macro可以在任何規(guī)范的模板中被調(diào)用。它可以被多次應(yīng)用并且可以應(yīng)用于不同的目的。例如下面的調(diào)用：
#set ( $parts = [ "volva", "stipe", "annulus", "gills", "pileus" ] )
#set ( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $parts )
</table>
上面VTL將產(chǎn)生如下的輸出：
<table>
<tr><td bgcolor="#CC00FF"> volva </td</tr>
<tr><td bgcolor="#CC00FF"> stipe </td</tr>
<tr><td bgcolor="#CC00FF"> annulus </td</tr>
<tr><td bgcolor="#CC00FF"> gills </td</tr>
<tr><td bgcolor="#CC00FF"> pileus </td</tr>
</table>
Velocimacro arguments
Velocimacro可以使用以下任何元素作為參數(shù)：
Reference：任何以$開(kāi)頭的reference
String literal：
Number literal：
IntegerRange：[1….3]或者[$foo….$bar]
對(duì)象數(shù)組：["a","b","c"]
boolean值：true、false
當(dāng)將一個(gè)reference作為參數(shù)傳遞給Velocimacro時(shí)，請(qǐng)注意reference作為參數(shù)時(shí)是以名字的形式傳遞的。這就意味著參數(shù)的值在每次Velocimacro內(nèi)執(zhí)行時(shí)才會(huì)被產(chǎn)生。這個(gè)特性使得你可以將一個(gè)方法調(diào)用作為參數(shù)傳遞給Velocimacro，而每次Velocimacro執(zhí)行時(shí)都是通過(guò)這個(gè)方法調(diào)用產(chǎn)生不同的值來(lái)執(zhí)行的。例如：
#macro ( callme $a )
$a $a $a
#end
#callme( $foo.bar() )
執(zhí)行的結(jié)果是：reference $foo的bar（）方法被執(zhí)行了三次。
如果你不需要這樣的特性可以通過(guò)以下方法：
#set ( $myval = $foo.bar() )
#callme ( $myval )
Velocimacro properties
Velocity.properties文件中的某幾行能夠使Velocimacros的實(shí)現(xiàn)更加靈活。注意更多的內(nèi)容可以看Developer Guide。
Velocity.properties文件中的velocimacro.libraary：一個(gè)以逗號(hào)分隔的模板庫(kù)列表。默認(rèn)情況下，velocity查找唯一的一個(gè)庫(kù)：VM_global_library.vm。你可以通過(guò)配置這個(gè)屬性來(lái)指定自己的模板庫(kù)。
Velocity.properties文件中的velocimacro.permissions.allow.inline屬性：有兩個(gè)可選的值true或者false，通過(guò)它可以確定Velocimacros是否可以被定義在regular template內(nèi)。默認(rèn)值是ture――允許設(shè)計(jì)者在他們自己的模板中定義Velocimacros。
Velocity.properties文件中的
velocimacro.permissions.allow.inline.replace.global屬性有兩個(gè)可選值true和false，這個(gè)屬性允許使用者確定inline的Velocimacro定義是否可以替代全局Velocimacro定義（比如在velocimacro.library屬性中指定的文件內(nèi)定義的Velocimacro）。默認(rèn)情況下，此值為false。這樣就阻止本地Velocimacro定義覆蓋全局定義。
Velocity.properties文件中的
velocimacro.permissions.allow.inline.local.scale屬性也是有true和false兩個(gè)可選值，默認(rèn)是false。它的作用是用于確定你inline定義的Velocimacros是否僅僅在被定義的template內(nèi)可見(jiàn)。換句話說(shuō)，如果這個(gè)屬性設(shè)置為true，一個(gè)inline定義的Velocimacros只能在定義它的template內(nèi)使用。你可以使用此設(shè)置實(shí)現(xiàn)一個(gè)奇妙的VM敲門：a template can define a private implementation of the second VM that will be called by the first VM when invoked by that template. All other templates are unaffected。
Velocity.properties文件中的velocimacro.context.localscope屬性有true和false兩個(gè)可選值，默認(rèn)值為false。當(dāng)設(shè)置為true時(shí)，任何在Velocimacro內(nèi)通過(guò)#set()對(duì)context的修改被認(rèn)為是針對(duì)此velocimacro的本地設(shè)置，而不會(huì)永久的影響內(nèi)容。
Velocity.properties文件中的velocimacro.library.autoreload屬性控制Velocimacro庫(kù)的自動(dòng)加載。默認(rèn)是false。當(dāng)設(shè)置為ture時(shí)，對(duì)于一個(gè)Velocimacro的調(diào)用將自動(dòng)檢查原始庫(kù)是否發(fā)生了變化，如果變化將重新加載它。這個(gè)屬性使得你可以不用重新啟動(dòng)servlet容器而達(dá)到重新加載的效果，就像你使用regular模板一樣。這個(gè)屬性可以使用的前提就是resource loader緩存是off狀態(tài)（file.resource.loader.cache = false）。注意這個(gè)屬性實(shí)際上是針對(duì)開(kāi)發(fā)而非產(chǎn)品的。
Velocimacro Trivia
Velocimacro必須被定義在他們被使用之前。也就是說(shuō)，你的#macro()聲明應(yīng)該出現(xiàn)在使用Velocimacros之前。
特別要注意的是，如果你試圖#parse()一個(gè)包含#macro()的模板。因為#parse()發(fā)生在運(yùn)行期，但是解析器在parsetiem決定一個(gè)看似VM元素的元素是否是一個(gè)VM元素，這樣#parse()-ing一組VM聲明將不按照預(yù)期的樣子工作。為了得到預(yù)期的結(jié)果，只需要你簡(jiǎn)單的使用velocimacro.library使得Velocity在啟動(dòng)時(shí)加載你的VMs。
Escaping VTL directives
VTL directives can be escaped with "\"號(hào)，使用方式跟VTL的reference使用逃逸符的格式差不多。
## #include( "a.txt" ) renders as <ontents of a.txt>(注釋行)
#include( "a.txt" )
## \#include( "a.txt" ) renders as \#include( "a.txt" )
\#include( "a.txt" )
## \\#include ( "a.txt" ) renders as \<contents of a.txt>
\\#include( "a.txt" )
在對(duì)在一個(gè)directive內(nèi)包含多個(gè)script元素的VTL directives使用逃逸符時(shí)要特別小心（比如在一個(gè)if-else-end statement內(nèi)）。下面是VTL的if-statement的典型應(yīng)用：
#if ( $jazz )
Vyacheslav Ganelin
#end
如果$jazz是ture，輸出將是：
Vyacheslav Ganelin
如果$jazz是false，將沒(méi)有輸出。使用逃逸符將改變輸出?？?/span>慮一下下面的情況：
\#if ( $jazz )
Vyacheslav Ganelin
\#end
現(xiàn)在無(wú)論$jazz是true還是false，輸出結(jié)果都是：
#if ( $jazz )
Vyacheslav Ganelin
#end
事實(shí)上，由于你使用了逃逸符，$jazz根本就沒(méi)有被解析為boolean型值。在逃逸符前使用逃逸符是合法的，例如：
\\#if ( $jazz )
Vyacheslav Ganelin
\\#end
以上程序的顯示結(jié)果為：
\ Vyacheslav Ganelin
\
但是如果$jazz為false，那么將沒(méi)有輸出。（書(shū)上說(shuō)會(huì)沒(méi)有輸出，但是我覺(jué)得應(yīng)該還有有"\"字符被輸出。）
VTL：Formatting issues
盡管在此用戶手冊(cè)中VTL通常都開(kāi)始一個(gè)新行，如下所示：
#set ( $imperial = [ "Munetaka", "Koreyasu", "Hisakira", "Morikune" ] )
#foreach ( $shogun in $imperial )
$shogun
#end
但是像下面這種寫(xiě)法也是可以的：
Send me #set($foo = ["$10 and","a cake"])#foreach($a in $foo)$a #end please.
上面的代碼可以被改寫(xiě)為：
Send me
#set ( $foo = ["$10 and ","a cake"] )
#foreach ( $a in $foo )
$a
#end
please.
或者
Send me
#set($foo = ["$10 and ","a cake"])
#foreach （$a in $foo ）$a
#end please.
這兩種的輸出結(jié)構(gòu)將一樣。
其他特性和雜項(xiàng)
math 在模板中可以使用Velocity內(nèi)建的算術(shù)函數(shù)，如：加、減、乘、除
#set ( $foo = $bar + 3 )
#set ( $foo = $bar - 4 )
#set ( $foo = $bar * 6 )
#set ( $foo = $bar / 2 )
當(dāng)執(zhí)行除法時(shí)將返回一個(gè)Integer類型的結(jié)果。而余數(shù)你可以使用%來(lái)得到：
#set ( $foo = $bar % 5 )
在Velocity內(nèi)使用數(shù)學(xué)計(jì)算公式時(shí)，只能使用像-n,-2,-1,0,1,2,n這樣的整數(shù)，而不能使用其它類型數(shù)據(jù)。當(dāng)一個(gè)非整型的對(duì)象被使用時(shí)它將被logged并且將以null作為輸出結(jié)果。
Range Operator
Range operator可以被用于與#set和#foreach statement聯(lián)合使用。對(duì)于處理一個(gè)整型數(shù)組它是很有用的，Range operator具有以下構(gòu)造形式：
[n..m]
m和n都必須是整型，而m是否大于n則無(wú)關(guān)緊要。例子：
First example:
#foreach ( $foo in [1..5] )
$foo
#end
Second example:
#foreach ( $bar in [2..-2] )
$bar
#end
Third example:
#set ( $arr = [0..1] )
#foreach ( $i in $arr )
$i
#end
Fourth example:
[1..3]
上面四個(gè)例子的輸出結(jié)果為：
First example：
1 2 3 4 5
Second example：
2 1 0 -1 -2
Third example：
0 1
Fourth example：
[1..3]
注意：range operator只在#set和#foreach中有效。
Advanced Issue：Escaping and！
當(dāng)一個(gè)reference被"！"分隔時(shí)，并且在它之前有逃逸符時(shí)，reference將以特殊的方式處理。注意這種方式與標(biāo)準(zhǔn)的逃逸方式時(shí)不同的。對(duì)照如下：
#set ( $foo = "bar" )
特殊形式 標(biāo)準(zhǔn)格式
Render前 Render后 Render前 Render后
$\!foo $!foo \$foo \$foo
$\!{foo} $!{foo} \$!foo \$!foo
$\\!foo $\!foo \$!{foo} \$!{foo}
$\\\!foo $\\!foo \\$!{foo} \bar
Velocimacro雜記
Can I user a directive or another VM as an argument to a VM?
例如：#center ( #bold( "hello" ) )
不可以。一個(gè)directive的參數(shù)使用另外一個(gè)directive是不合法的。
但是，還是有些事情你可以作的。最簡(jiǎn)單的方式就是使用雙引號(hào)：
#set ( $stuff = "#bold( 'hello' )" )
#center ( $stuff )
上面的格式也可以縮寫(xiě)為一行：
#center ( "#bold( 'hello' ) )
請(qǐng)注意在下面的例子中參數(shù)被evaluated在Velocimacro內(nèi)部，而不是在calling level。例子：
#macro ( inner $foo )
inner : $foo
#end
#macro ( outer $foo )
#set ( $bar = "outerlala" )
outer : $foo
#end
#set ( $bar = 'calltimelala' )
#outer( "#inner($bar)" )
輸出結(jié)果為：
outer : inner : outerlala
記住Veloctiy的特性：參數(shù)的傳遞是By Name的。例如：
#macro ( foo $color )
<tr bgcolor = $color ><td>Hi</td></tr>
<tr bgcolor = $color ><td>There</td></tr>
#end
#foo ( $bar.rowColor() )
以上代碼將導(dǎo)致rowColor()方法兩次調(diào)用，而不是一次。為了避免這種現(xiàn)象的出現(xiàn)，我們可以按照下面的方式執(zhí)行：
#set ( $color = $bar.rowColor() )
#foo ( $color )
can I register velocimacros via #parse()?
目前，Velocimacros必須在第一次被模板調(diào)用前被定義。這就意味著你的#macro()聲明應(yīng)該出現(xiàn)在使用Velocimacros之前。
如果你試圖#parse()一個(gè)包含#macro() directive的模板，這一點(diǎn)是需要牢記的。因為#parse()發(fā)生在運(yùn)行期，但是解析器在parsetiem決定一個(gè)看似VM元素的元素是否是一個(gè)VM元素，這樣#parse()-ing一組VM聲明將不按照預(yù)期的樣子工作。為了得到預(yù)期的結(jié)果，只需要你簡(jiǎn)單的使用velocimacro.library使得Velocity在啟動(dòng)時(shí)加載你的VMs。
What is velocimacro autoreloading？
velocimacro.library.autoreload是專門為開(kāi)發(fā)而非產(chǎn)品使用的一個(gè)屬性。此屬性的默認(rèn)值是false。
String concatenation
開(kāi)發(fā)人員最常問(wèn)的問(wèn)題是我如何作字符拼接？在java中是使用"＋"號(hào)來(lái)完成的。
在VTL里要想實(shí)現(xiàn)同樣的功能你只需要將需要聯(lián)合的reference放到一起就行了。例如：
#set ( $size = "Big" )
#set ( $name = "Ben" )
The clock is $size$name.
輸出結(jié)果將是：The clock is BigBen.。更有趣的情況是：
#set ( $size = "Big" )
#set ( $name = "Ben" )
#set ( $clokc = "$size$name" )
The clock is $clock.
上例也會(huì)得到同樣的結(jié)果。最后一個(gè)例子，當(dāng)你希望混合固定字段到你的reference時(shí)，你需要使用標(biāo)準(zhǔn)格式：
#set ( $size = "Big" )
#set ( $name = "Ben" )
#set ( $clock = "${size}Tall$name" )
The clock is $clock.
輸出結(jié)果是：The clock is BigTallBen.。使用這種格式主要是為了使得$size不被解釋為$sizeTall。
posted on 2007-05-21 13:27
砸你家玻璃 閱讀(1303)
評(píng)論(1) 編輯 收藏 所屬分類:
Velocity