velocity中文手冊(cè)

1、velocity中文手冊(cè)Velocity用戶指南什么是Velocity？Velocity是基于Java的模板引擎。它允許Web頁(yè)面開發(fā)者引用Java代碼中定義的方法。Web設(shè)計(jì)者可以和Java程序開發(fā)者并行開發(fā)遵循MVC模式的Web站點(diǎn)。這意味著，Web設(shè)計(jì)者可以將精力放在好的Web站點(diǎn)設(shè)計(jì)上，而Java程序開發(fā)者可以將精力放在編寫代碼上。Velocity將Java代碼從Web頁(yè)面中分離，使Web站點(diǎn)更具長(zhǎng)期可維護(hù)性，并提供了一種替代JSP或PHP的方案。VTL(Velocity Template Language)介紹VTL提供一種簡(jiǎn)單、容易和干靜的方法將動(dòng)態(tài)內(nèi)容合并到Web頁(yè)面。VTL使用

2、引用(references)將動(dòng)態(tài)內(nèi)容插入到Web頁(yè)面中。變量是一種引用，可以指向Java代碼中的定義內(nèi)容，或者由Web頁(yè)面中的VTL語(yǔ)句來(lái)獲得值。下面是一個(gè)可以插入到HTML文檔的VTL語(yǔ)句的例子：#set( $a = Velocity )VTL語(yǔ)句以#開頭，并包含指令(set)。變量以$開頭，用引號(hào)引起。引號(hào)可以是單引號(hào)，也可以是雙引號(hào)。前者引用具體的String值；后者可以包含Velocity引用，例如”hello, $name”， $name會(huì)用其當(dāng)前的值替換。上面的例子是將值Velocity賦值給變量a。當(dāng)變量被賦值后，就可以在HTML文檔的任何地方引用，下面是Hello Veloc

3、ity World!的例子：#set( $foo = Velocity )Hello $foo World!注釋VTL支持單行注釋（以#開始）和多行注釋（包括在#*和*#之間），下面是一個(gè)例子：This text is visible. # This text is not visible.This text is visible.This text is visible. #* This text, as part of a multi-line comment,is not visible. This text is not visible; it is also part of them

4、ulti-line comment. This text still not visible. *# This text is outsidethe comment, so it is visible.# This text is not visible.引用VTL有3種類型的引用：變量、屬性和方法。作為一個(gè)設(shè)計(jì)者，必須和Java工程師在VTL引用的名稱（標(biāo)識(shí)符）上一致，以便在模板中使用它們。引用是作為String對(duì)象處理的。（1）變量變量的格式：$VTL標(biāo)識(shí)符VTL標(biāo)識(shí)符以字母開始，由字母、數(shù)字、橫劃線(-)或下劃線(_)組成。變量或者從模板中的set指令獲得值（如前面的例子），或者Java

5、代碼（同名變量）中獲得值。Velocity只處理已定義的變量引用，對(duì)于沒(méi)有定義的變量引用，Velocity原樣返回。例如下面的例子：#set( $foo = gibbous )$moon = $foo輸出結(jié)果是：$moon = gibbous（2）屬性屬性的格式：$VTL標(biāo)識(shí)符. VTL標(biāo)識(shí)符下面是屬性引用的例子：$customer.Address$purchase.Total拿第一例子來(lái)說(shuō)，有兩種意思：l 返回Hashtable對(duì)象customer中鍵值為Address的值l $customer.getAddress()方法引用的縮寫（JavaBean屬性的getter方法）至于是哪種情況，

6、Velocity會(huì)做決定，返回合適的值。（3）方法方法的格式：$VTL標(biāo)識(shí)符(參數(shù)列表)下面是方法引用的例子：$customer.getAddress()$purchase.getTotal()$page.setTitle( My Home Page )$person.setAttributes( Strange, Weird, Excited )前面兩個(gè)例子可以縮寫成屬性引用（如屬性引用的例子）。屬性引用和方法引用的主要區(qū)別是方法引用可以指定參數(shù)列表。（4）正式引用符號(hào)：正式引用符號(hào)在使用變量引用含糊的地方進(jìn)行區(qū)分?？聪旅娴睦樱?set( $vice = klepto )Jack is a

7、 $vicemaniac.輸出結(jié)果是：Jack is a $vicemaniac.（$vicemaniac沒(méi)有定義，原樣輸出）#set( $vice = klepto )Jack is a $vicemaniac.輸出結(jié)果是：Jack is a kleptomaniac.（使用正式引用符號(hào)將$vice和其它文本區(qū)分開）（5）Quit引用符號(hào)：!看下面的例子：初始時(shí)，$email沒(méi)有值，所以文本框中會(huì)顯示值$email，而更希望是空白。下面是使用Quit引用符號(hào)的例子：當(dāng)$email沒(méi)有值時(shí)，Velocity會(huì)用空串替代$email。（6）特殊字符轉(zhuǎn)義對(duì)于$、#等特殊字符要正常顯示，可以使用進(jìn)行

8、轉(zhuǎn)義，轉(zhuǎn)義為。下面是一個(gè)例子：#set( $email = foo )$email$email$email$email輸出結(jié)果是：foo$emailfoo$email指令(Directives)引用允許模板設(shè)計(jì)者為Web站點(diǎn)生成動(dòng)態(tài)內(nèi)容，而指令使巧妙處理Java代碼的腳本元素容易使用。（1）#set格式：#set( LHS = RHS )l LHS可以是變量引用或?qū)傩砸胠 RHS可以是引用、字符串、數(shù)字、ArrayList或Map下面的例子展示了上面的每種RHS類型：#set( $monkey = $bill ) # variable reference#set( $monkey.Frien

9、d = monica ) # string literal#set( $monkey.Blame = $whitehouse.Leak ) # property reference#set( $monkey.Plan = $spindoctor.weave($web) ) # method reference#set( $monkey.Number = 123 ) #number literal#set( $monkey.Say = Not, $my, fault ) # ArrayList#set( $monkey.Map = banana : good, roast beef : bad)

10、 # Map對(duì)于ArrayList和Map，可以使用對(duì)應(yīng)的Java方法訪問(wèn)其中的元素值：$monkey.Say.get(0)$monkey.Map.get(bannana)$monkey.Map.banana # same as abovel RHS可以是簡(jiǎn)單的算術(shù)表達(dá)式#set( $value = $foo + 1 ) # Addition#set( $value = $bar - 1 ) # Subtraction#set( $value = $foo * $bar ) # Multiplication#set( $value = $foo / $bar ) # Division#set(

11、 $value = $foo % $bar ) # Remainder算術(shù)表達(dá)式只支持整型。/的結(jié)果為整數(shù)；如果非整型數(shù)值，返回nulll 如果RHS的結(jié)果為null，是不會(huì)賦值給LHS的看下面的例子：#set( $criteria = name, address )#foreach( $criterion in $criteria ) #set( $result = $query.criteria($criterion) ) #if( $result ) Query was successful #end#end上面使用$result檢查是否執(zhí)行成功是有問(wèn)題的。如果第一次執(zhí)行成功，$resu

12、lt不為null，則后面的執(zhí)行不管是否成功，檢查條件總是成立。改進(jìn)的方法是在每次執(zhí)行前初始化為false：#set( $criteria = name, address )#foreach( $criterion in $criteria )#set( $result = false ) #set( $result = $query.criteria($criterion) ) #if( $result ) Query was successful #end#endl String文字可以使用雙引號(hào)或單引號(hào)括起。兩者的主要區(qū)別是雙引號(hào)中的引用會(huì)替換成相應(yīng)的值，而單引號(hào)中的引用原樣輸出#set(

13、 $directoryRoot = www )#set( $templateName = index.vm )#set( $template = $directoryRoot/$templateName )$template輸出結(jié)果是：www/index.vm如果使用單引號(hào)：#set( $template = $directoryRoot/$templateName )輸出結(jié)果是：$directoryRoot/$templateNamel 使用雙引號(hào)可以實(shí)現(xiàn)字符串的串聯(lián)，如下面的例子： #set( $size = Big ) #set( $name = Ben ) #set($clock =

14、$sizeTall$name ) The clock is $clock.（2）#if / #elseif / #else#if指令在條件成立時(shí)，顯示#if和#end之間的內(nèi)容，否則顯示#else和#end之間的內(nèi)容。下面是一個(gè)例子：#if( $foo ) Velocity!#end條件成立有兩種情況：l 如果$foo是boolean，則$foo要為true；l 否則，$foo不為null#if指令中可以使用的關(guān)系和邏輯符號(hào)包括：l 、=、l &(and)、|(or)、!(not)（3）循環(huán)：foreach下面是一個(gè)例子：#foreach( $product in $allProducts )

15、 $product#end$allProducts的內(nèi)容可以是Vector、Hashtable或ArrayList，每次取出一個(gè)值賦值給$product；返回的值是一個(gè)Java對(duì)象，可以用來(lái)引用具體的方法。下面的例子假設(shè)$allProducts是Hashtable對(duì)象：#foreach( $key in $allProducts.keySet() ) Key: $key - Value: $allProducts.get($key)#endVelocity提供了訪問(wèn)循環(huán)計(jì)數(shù)變量的簡(jiǎn)單方法：#foreach( $customer in $customerList ) $velocityCount

16、$customer.Name#end$velocityCount是Velocity表示循環(huán)計(jì)數(shù)的內(nèi)部變量，缺省開始值為1。該設(shè)置在perties文件中定義：# Default name of the loop counter# variable = velocityCount# Default starting value of the loop# counter variable reference.directive.foreach.counter.initial.value = 1可

17、以在#foreach指令中使用范圍操作符n.m，其中n和m必須是整型：First example:#foreach( $foo in 1.5 )$foo#endSecond example:#foreach( $bar in 2.-2 )$bar#endThird example:#set( $arr = 0.1 )#foreach( $i in $arr )$i#end輸出結(jié)果是：First example:1 2 3 4 5Second example:2 1 0 -1 -2Third example:0 1（4）#include#include指令導(dǎo)入本地文件到#include指令定義的

18、地方。導(dǎo)入的文件內(nèi)容不會(huì)被模板引擎解析。出于安全考慮，導(dǎo)入的文件應(yīng)該放在TEMPLATE_ROOT目錄下。一次可以導(dǎo)入多個(gè)文件，文件名之間用逗號(hào)分隔；并且通常使用變量引用來(lái)替代文件名。下面是一個(gè)例子：#include( greetings.txt, $seasonalstock )（5）#parse#parse指令允許導(dǎo)入一個(gè)包含VTL的本地文件，并由模板引擎進(jìn)行解析。#parse指令導(dǎo)入的文件必須放在TEMPLATE_ROOT目錄下，并且一次只能導(dǎo)入一個(gè)文件。允許在Velocity模板中嵌套執(zhí)行#parse指令。最大深度由perties文件中的parse_direct

19、ive.maxdepth定義。下面是一個(gè)例子：Count down.#set( $count = 8 )#parse( parsefoo.vm )All done with dofoo.vm!包含的parsefoo.vm文件如下：$count#set( $count = $count - 1 )#if( $count 0 ) #parse( parsefoo.vm )#else All done with parsefoo.vm!#end輸出結(jié)果是：Count down.876543210All done with parsefoo.vm!All done with dofoo.vm!（6）#

20、stop#stop指令停止模板引擎的執(zhí)行并返回。這在Debug時(shí)很有用。（7）#macro#macro指令允許定義一段重復(fù)使用的VTL模板（稱Velocimacros）。l Velocimacros可以有0或多個(gè)參數(shù)。下面是一個(gè)例子：#macro( tablerows $color $somelist )#foreach( $something in $somelist ) $something#end#end這個(gè)叫tablerows的Velocimacro帶2個(gè)參數(shù)：一個(gè)color和一個(gè)array。下面的代碼包含對(duì)tablerows的調(diào)用：#set( $greatlakes = Superi

21、or,Michigan,Huron,Erie,Ontario )#set( $color = blue ) #tablerows( $color $greatlakes )輸出結(jié)果為： Superior Michigan Huron Erie Ontariol Velocimacros可以在VTL模板中定義為inline，這樣對(duì)其它的VTL模板是無(wú)效的；要使Velocimacros在所有VTL模板中共享，可以將Velocimacros定義在Velocimacros模板庫(kù)（全局）中。l Velocimacros屬性在perties文件中定義，提供實(shí)現(xiàn)Velocimacro

22、s的靈活性：velocimacro.library = VM_global_library.vmvelocimacro.permissions.allow.inline = truevelocimacro.permissions.allow.inline.to.replace.global = falsevelocimacro.permissions.allow.inline.local.scope = falsevelocimacro.context.localscope = falsevelocimacro.library.autoreload = falsevelocimacro.lib

23、rary：定義逗號(hào)分隔的Velocimacros全局模板庫(kù)，缺省是VM_global_library.vm，可以增加自定義的模板庫(kù)；velocimacro.permissions.allow.inline：指定是否允許在VTL模板中定義Velocimacros，缺省是true（允許）；velocimacro.permissions.allow.inline.to.replace.global：指定是否允許inline定義的Velocimacros替換同名的全局Velocimacros，缺省是false（不允許）；velocimacro.permissions.allow.inline.local.scope：指定inline定義是否是定義的模板中可見，缺省是false；velocimacro.context.localscope：指定context內(nèi)容是否是本地范圍的，缺省是false；如果設(shè)為true，則使用#set指令對(duì)c