《Velocity 模板使用指南》中文版《Velocity 模板使用指南》中文版
源文見 http://velocity.
聲明: 轉(zhuǎn)載請保留此頁聲明
**************************************************************************
此文檔為藍杰實訓(xùn)學(xué)員拓展實訓(xùn)之用.
藍杰實訓(xùn)不對譯文中某些說法可能會對您的系統(tǒng)或開發(fā)造成損害負責(zé).
如對您有所幫助，我們不勝榮幸！
*************************************************************************
本文屬NetJava.cn中的Velocity中文系列，本系包含如下文章：
《Velocity Java開發(fā)指南中文版》(Developer`s Guide)
《Velocity模板使用指南中文版》(User`s Guide)
《Velocity Web應(yīng)用開發(fā)指南中文版》(Web Application Guide)
《VTL語法參考指南中文版》(VTL Reference)
《DB4O中文系列之起步篇》
. . .
更多資料請訪問http://www./ 下載.
**************************************************************************
譯者: javaFound
Mail: javafound@gmail.com
*************************************************************************
目 錄
本文主要介紹如何在模板中使用Velocity功能強大的模板語言VTL(Velocity Template Language)用法有一個全面的認識，并掌握如何在模板中有效使用。同時，本文提供較多的例子幫您來學(xué)習(xí)它.
感謝您選擇Velocity幫助您實現(xiàn)純正的MVC系統(tǒng)構(gòu)架。
2.什么是Velocity?
Velocity 是一個基于java的模板引擎(template engine). 它可以讓視圖的設(shè)計者在web頁面中引用java代碼中定義的數(shù)據(jù)對象和命令。從而使Web designers和java開發(fā)者依照MVC思想(Model-View-Controller )開發(fā)系統(tǒng),這意味著Web designers只須將精力注用于良好表現(xiàn)力的視圖外觀設(shè)計，而Java程序員則只要關(guān)心著如何寫出高效簡潔的java對象以實現(xiàn)業(yè)務(wù)邏輯-----Velocity會將他們組裝到一起. 相比傳統(tǒng)的jsp、PHP等腳本語言，Velocity徹底的將避免了在視圖設(shè)計中出現(xiàn)的java代碼, 從而保證了web site的長期可維護性.
一定要理解，Velocity是一個template engine的意思，它還可以從模板中生成SQL語句或其它腳本提供給web pages. 它也可以獨立使用---做為一個工具類(utility class)用來生成源代碼、報表、郵件模板等---在有需要重復(fù)的視圖情況下，你應(yīng)想到使用Velocity.Apache站點提供的另外一個框架Turbine 可以和Velocity有效結(jié)合以實現(xiàn)true MVC model.
3.Velocity能為你做什么?
1.一個Mud Store Example
假設(shè)你是一個page designer 在為一個在線商店設(shè)計頁面. 我們稱這個項目為 "The Online Mud Store".業(yè)務(wù)發(fā)展還不錯，客戶會訂購不同類型的MuD,每個客戶都會用自己的賬號密碼login,查看選擇他們訂購的MuD,查看訂單，但還有些忠誠用戶會購賣不太流行的MuD----這些不需要出現(xiàn)在頁面中顯眼的地方。當(dāng)然，The Online MuD Store必須把每個客戶資料及訂購信息記錄到DB中，現(xiàn)在的問題是，如何讓某個客戶login后就看到他感興趣的信息？
使用Velocity!我們?yōu)槊總€客戶定制一個頁面！這聽起來工作量巨大，讓我們試試：.
使用Velocity的 VTL 如下來設(shè)計 web page:
<HTML>
<BODY>
##指定用戶名字
歡迎你： $customer.Name!
<table>
###輸出用戶喜好的MuD
#foreach( $mud in $mudsOnSpecial )
#if ( $customer.hasPurchased($mud) )
<tr>
<td>
$flogger.getPromo( $mud )
</td>
</tr>
#end
#end
</table>
使用VTL設(shè)計頁面就是這么簡單！文檔《VTL參考中文版》中有更全面的VTL語言介紹，掌握這些，你將會全面體會到Velocity的威力.
4.Velocity Template Language (VTL): 介紹
The Velocity Template Language (VTL)目標(biāo)是提供一個簡潔，易學(xué)的方法將動態(tài)內(nèi)容展現(xiàn)到web page上. a web page設(shè)計者可以沒有任何編程經(jīng)驗就可以在一天內(nèi)學(xué)會使用它增強你的站點的展示力！.
VTL使用引用(references )這種方式將dynamic content(動態(tài)內(nèi)容，一般指java代碼生成的數(shù)據(jù)對象)加入到你的web site,Velocity中的變量(variable)只是refernce中的一種. Variables是用來描述從引入到視圖模板中的java數(shù)據(jù)對象。當(dāng)然，java代碼也可以從模板的VTL中獲取數(shù)據(jù).以下是一個寫在HTML中的VTL變量:
#set( $a = "Velocity" )
VTL聲明( statement),所以的VTL statement都是以#開頭，且包含一個指示符（這里是set）,當(dāng)客戶訪問你的頁面時, the Velocity Templating Engine將搜索頁面中的所有 # 符號,如果確定這是一個VTL聲明時就按一定規(guī)則處理動態(tài)內(nèi)容, 符號#僅僅只是表明這可能是一個VTL聲明.
符號# 所跟的set我們用“指示符”這一名詞來稱呼它(隨后介紹更多的指示符), set 指示符使用一個表達式(expression) (包含在一對括號里) –將一個值 value (這里是Velocity)付給變量a,（變量名在左邊，值在右邊，用=組合起來）.
在以上的例子中,變量是a ,而符號“$”表明它是一個變量,Velocity中所有變量以符號”$”開頭，所付的值要用雙引號括起， 這個值中還可以再添加Velocity變量，如"Hello $name"，輸出的將是name變量所付的值。
這是理解VTL基礎(chǔ)的規(guī)則:
以$開頭的表示“引用”意思是取得一些東東.而”指示”(Directives)則以#開頭來表示，有點“做些什么動作”的意思.
如上便, #set 用來指定值給一個變量名$a, 以“$”標(biāo)示的變量名a的值就是"Velocity".
5.輸出第一個VTL頁面!
有你的HTML文檔的任何地方，都可以引用一個變量名來輸出值, 如下例, 先給變量名foo 賦值為Velocity,然后將它輸出到頁面中.
<html>
<body>
#set( $foo = "Velocity" )
Hello $foo World!
</body>
<html>
在這個頁面上，你看到的將是 "Hello Velocity World!".
為了讓查板中的VTL指令更易讀, 我們強烈建議你每行一條VTL指令,當(dāng)然這不是必須的. 關(guān)于 set directive的更多功能我們隨后再討論.
6.Comments(注釋)
Comments可以讓你在模板中包含對VTL或其它問題的說明描述以便與閱讀和理解.---但它并不會在最終輸出的web pages中看到.如下示例是VTL中的一行注釋.
## This is a single line comment.
單行注釋是以## 開頭的一行文字.如要寫下多行注釋，就要像下面那樣，將它們放入#* 和*#間:
This is text that is outside the multi-line comment.
Online visitors can see it.
#*
Thus begins a multi-line comment. Online visitors won‘t
see this text because the Velocity Templating Engine will
ignore it.
*#
不需要太復(fù)雜了，這兩種方式己足夠你給自己的頁面加上充分的說明。
7.References(引用)
VTL中有三種references：變量引用(variables),屬性引用(properties)和命令引用(methods). 做為一個使用VTL的設(shè)計者, 你和你的java軟件工程師必須就模板中引用的特定名了(就是$后的名字)達成一致的協(xié)議！這樣，模板和java代碼才可按照你們的意圖去結(jié)合以輸出正確的內(nèi)容.
所有的引用在模板中都表現(xiàn)為一個字符串. 假設(shè)一個引用變量 $foo 的值事實上是一個int, Velocity engine在處理時將調(diào)用它的.toString() 去解析這個字符串所代表的對象(int).
1.Variables(變量)
簡單的說變量以"$" 開后，后面跟一個VTL指示符( Identifier).一個合法的VTL指示符是以字母開頭，后面可以是以下任意字符:
alphabetic (a .. z, A .. Z)
numeric (0 .. 9)
hyphen ("-")
underscore ("_")
以下是正確的VTL變量名:
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
當(dāng)VTL中的一個變量如 $foo, 這個變量可以在模板中提取它自己的值通過set 指示符,或者從java代碼中.比如，如果需java中的變量foo的值為bar,給模板中所有輸出$foo聲明的值都成為bar.當(dāng)然，在模板中使用如下VTL也可以達到這個目地。
#set( $foo = "bar" )
2.Properties(屬性)
VTL的第二種引用，屬性引用,注意”屬性”具有相對固定的格式. 它也是以$開頭的合法VTL指示符,隨后是”變量名字.變量屬性”. 如下例:
$customer.Address
$purchase.Total
第一個例子, $customer.Address.我們設(shè)想可能在兩種意思.首先它可能在查找customer引用的一個hashtable中的以“Address”為key關(guān)聯(lián)的一個數(shù)據(jù)對象.另外他可能表示的是java對象customer中的getAddress()這個命令取得的結(jié)果(當(dāng)然也可寫成 $customer.getAddress()). 當(dāng)客戶請求Web頁面中Velocity將根據(jù)具體的customer類型輸出.
3.Methods（命令）
在java 代碼中定義命令是最通常的事, 像執(zhí)得一組方程式計算成本，讀取一個文件等. 命令引用和其它引用一個也是一個一般的VTL聲明,看如下的例子可能會更快的理解:
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
前兩個例子 -- $customer.getAddress() and $purchase.getTotal() – 可以等同與屬性引用情況： $customer.Address and $purchase.Total. 如你猜對了這點，呵，你還蠻聰明！同時，他們是等同與java對象coustomer的getAddress（）命令調(diào)用。后面兩個引用呢，也會直接對應(yīng)java對象的對應(yīng)命令，不同的是傳入了命令參數(shù)。
前己提及,屬性可以引用到對象的命令. Velocity會使用合適的策略選擇引用到的命令. 它會根據(jù)協(xié)定的命令命令格式查找. 無論屬性引用的的名字是否大小寫，Velocity都有固定的查找規(guī)則.如在$customer.address引用時，查找順序是：
- getaddress()
- getAddress()
- get("address")
- isAddress()
對于ＶＴＬ中大寫的屬性名Address引用，將是:
- getAddress()
- getaddress()
- get("Address")
- isAddress()
以上是簡潔格式引用的介紹，規(guī)則的格式像下面，如你看到的變量名需要放到{}中:
${mudSlinger}
${customer.Address}
${purchase.getTotal()}
大多數(shù)情況下，簡潔格式引用足以滿足使用,但有些情況下，必須使用正規(guī)格式引用.
假設(shè)你構(gòu)造的一個字符串中要包括有 $vice 變量的值. 你覺得以下兩種寫法會是同樣的結(jié)果嗎:
1.Jack is a $vicemaniac.
2.Jack is a ${vice}maniac.
這樣，Velocity就知你要的是 $vice, 而不是 $vicemaniac變量，正規(guī)引用格式一般用于在模板中直接調(diào)整字符串內(nèi)容.
Velocity遇到一個不能處理的引用時，一般他會直接輸出這個引用$email的寫法,頁面上會看到的是$email，如下例,我們可以在$后面加上一個!號，那么就會輸出空白:.
<input type="text" name="email" value="$email"/>
<input type="text" name="email" value="$!email"/>
正式的寫法是:.
<input type="text" name="email" value="$!{email}"/>
10.Getting literal( 語義問題)
一般情況下，velocity使用$,#字符來標(biāo)志它的聲明，但有時，ＨＴＭＬ中因為某種其它意圖，也會寫出這樣的字符，我們討論如何消除這種語義歧義問題.
如美元 $2.50!這樣的寫法出現(xiàn)到模板中, VTL處理時是不會出錯，會正確的輸出$2.50!這個你想要的結(jié)果。為什么呢？一個合法的VTL標(biāo)示符是以一個字母開頭的，我們前面己說過.
如下示，如果沒有#set( $email = "foo" )這一行且java代碼中Context對象中沒有放放email對象，將直接輸出$email.
#set( $email = "foo" )
$email
如果email己定義了 (比如它的值是 foo),而這里你卻想輸出 $email. 這樣一個字符串,就需要使用轉(zhuǎn)義字符”\”.
## The following line defines $email in this template:
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
上面的模板在web頁面上的輸出將是:
foo
$email
\foo
\$email
但如果email并沒有定義，我們這樣寫：.
$email
\$email
\\$email
\\\$email
輸出就原封不動了：
$email
\$email
\\$email
\\\$email
注意：當(dāng)己定義變量和未定義變量一起輸出時，會輸出字面意思,如下便，$moon是未定義的：
#set( $foo = "gibbous" )
$moon = $foo
輸出到web頁面中將是
$moon = gibbou
11.Case Substitution(可選的格式)
至此，你對velocity的refenerce己比較熟悉了, 你可以在你的模板中開始應(yīng)用這些功能. 但你還可以知道的是Velocity references從java語法中汲取了一些優(yōu)點以便模板設(shè)計者更容易使用VTL.比如:
$foo
$foo.getBar()
## 等同于
$foo.Bar
$data.setUser("jon")
##等同于
#set( $data.User = "jon" )
$data.getRequest().getServerName()
##等同于
$data.Request.ServerName
## is the same as
${data.Request.ServerName}
這里示例了你可選的一些引用方式. VTL汲取了java語法和java bean的一些簡潔語法以解析java代碼中Context中的對象和這些對象的命令及屬性---這樣，一個java對象的所有功能都可以展示到視圖中了.
Velocity也借見了java Bean的規(guī)范(Bean specifications defined by Sun Microsystems), 是大小寫敏感的; 但Velocity會盡可能的幫你修正錯誤. 當(dāng)命令 getFoo() 通過指令 $bar.foo在模板中引用時,Velocity的搜索規(guī)則我們在前面己講了，你還記得是什么嗎？.
注意:模板中引用的必須是通過java Bean中的getter/setter 實現(xiàn)的，而直接的java對象的數(shù)據(jù)域是不能直接引用的,如$foo.Name 會解析到 class Foo‘s getName() 的實例方法,但不會解析到Foos類的 public Name 這個實例變量.
12.Directives(指令符號)
模板設(shè)計者使用“引用“生成動態(tài)內(nèi)容, 指令(directives) – 簡單的說就是設(shè)計者在模板中操作java對象—讓視圖設(shè)計者全面控制輸出內(nèi)容的格式.
指令總是以 #開頭后面緊跟具體的指令符. 就像引用一樣（指令的一種）,可以將指令理解為”表示這里是一個什么東東).如下例生成一個出錯提示:
#if($a==1)true enough#elseno way!#end
這個例子中應(yīng)使用括號將else分開.
#if($a==1)true enough#{else}no way!#end
1.#set指令
#set 用來給一個引用賦值.值可以被賦給變量引用或?qū)傩砸? 但要將它們放入括號中，如下示:
#set( $primate = "monkey" )
#set( $customer.Behavior = $primate )
“左操作數(shù)被賦值“是引用操作的一個規(guī)則.=號右側(cè)可能是以下類型之一:
- Variable reference變量引用
- String literal字符串
- Property reference 屬性引用
- Method reference 命令引用
- Number literal 數(shù)字
- ArrayList 數(shù)組
- Map 映射
下面是對上述類型設(shè)置的示例:
#set( $monkey = $bill ) ## variable reference
#set( $monkey.Friend = "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"}) ## Map
注意: 在ArrayList類型引用的例子中，其原素定義在數(shù)組 [..]中, 因此，你可以使表 $monkey.Say.get(0)訪問第一個元素.
類似的,引用Map 的例子中, 原素定義在 { } 中，其鍵和值間以:隔成一對，使用 $monkey.Map.get("bannana") 在上例中將返回 ‘good‘, ( $monkey.Map.banana也會有同樣效果).
下面是一般的計算表達式:
#set( $value = $foo + 1 )
#set( $value = $bar - 1 )
#set( $value = $foo * $bar )
#set( $value = $foo / $bar )
但注意：如果右邊的操作數(shù)是一個屬性或命令的引用而返回null,那么賦值將不會成功，且在隨后的VTL中也不能再取出使用. 如下例:
#set( $result = $query.criteria("name") )
The result of the first query is $result
#set( $result = $query.criteria("address") )
The result of the second query is $result
如果 $query.criteria("name") 返回的是字符串 "bill", 但 $query.criteria("address") 返回null, 上面的TVL輸出結(jié)果將是:
The result of the first query is bill
The result of the second query is bill
這對與初學(xué)者的理解有些麻煩,比如在 #foreach loops中， 你使用 #set 給一個屬性或命令賦值時，如下例示:
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
在上例中，就不能依賴if( $result )來決定查詢是否成功. $result 一但被 #set 為null (context會同樣), 它將不能被賦 其它值 (不能從 context中取出).
一個解決辦法是，每次都將$result 設(shè)為 false. 如果 $query.criteria() 調(diào)用成功，就可以檢測到.
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
注意： #set 不需要使用 #end 來聲明結(jié)尾.
使用#set 指令時,變量如果用 “”引起會被解析，如:
#set( $directoryRoot = "www" )
#set( $templateName = "index.vm" )
#set( $template = "$directoryRoot/$templateName" )
$template
輸出的將是:
www/index.vm
但當(dāng)用單引號引起來時，就不會被解析：:
#set( $foo = "bar" )
$foo
#set( $blargh = ‘$foo‘ )
$blargh
輸出后會是:
bar
$foo
默認情況下，不會解析單引號中的變量，當(dāng)然，這可以通過改變Velocity的配置參數(shù)來改變：
velocity.properties such that stringliterals.interpolate=false.
另外, 指令 #literal 元素可以用來輸出字面意思，如下示.
#literal()
#foreach ($woogie in $boogie)
nothing will happen to $woogie
#end
#end
會輸出：:
#foreach ($woogie in $boogie)
nothing will happen to $woogie
#end
3.Conditionals(條件判斷)
1.If / ElseIf / Else
#if 指令用來根據(jù)條件在頁面中輸出內(nèi)容, 如下簡單的例子:
#if( $foo )
<strong>Velocity!</strong>
#end
根據(jù)變量 $foo計算后是否為true決定輸出, 這會有兩種情況: (i) $foo 的是值是一個boolean (true/false)型并有一個true value, 或 (ii) 它是一個非null值. 要記者，Velocity context 中只能包含Objects, 因此當(dāng)我們講 ‘boolean‘時, 它就是一個Boolean (the class).
在 #if 和 #end 的內(nèi)容是否會輸出，由$foo是否為true決定. 這里，如果 $foo is true, 輸出將是: "Velocity!". 如果$foo 為null或false,將不會有任何輸出.
#elseif 或 #else 可以 #if 和組合使用. 如果第一個表達式為true,將會不計算以后的流程，如下例假設(shè)t $foo 是15 and $bar 產(chǎn) 6.
#if( $foo < 10 )
<strong>Go North</strong>
#elseif( $foo == 10 )
<strong>Go East</strong>
#elseif( $bar == 6 )
<strong>Go South</strong>
#else
<strong>Go West</strong>
#end
輸出將會是
Go South.
2.Relational and Logical Operators(關(guān)系和邏輯運算)
Velocity使用==來做比較,如下例.
#set ($foo = "deoxyribonucleic acid")
#set ($bar = "ribonucleic acid")
#if ($foo == $bar)
In this case it‘s clear they aren‘t equivalent. So...
#else
They are not equivalent and this will be the output.
#end
注意：== 計算與java中的 == 計算有些不同：不能用來測試對象是否相等(指向同一塊內(nèi)存). Velocity中是否相等僅直接的用來比較numbers, strings的值, or objects的toString()結(jié)果是否相等. 如果是不同的對象,會調(diào)用它們的toString()命令結(jié)果來比較.
Velocity也使用AND, OR and NOT 執(zhí)行邏輯運算.詳細說明請參看《VTL參考中文版》，如下是一些簡單示例：
## logical AND
#if( $foo && $bar )
<strong> This AND that</strong>
#end
僅當(dāng) $foo $bar 和都為true時，#if()才會輸出中間內(nèi)容.
OR 運算例子
## logical OR
#if( $foo || $bar )
<strong>This OR That</strong>
#end
$foo或$bar只要有一個為true就可以輸出。
NOT運算則只有一個操作參數(shù)或表達式 :
##logical NOT
#if( !$foo )
<strong>NOT that</strong>
#end
考慮下，下面的例子有幾種輸出結(jié)果？.
#if( $foo == $bar)it‘s true!#{else}it‘s not!#end</li>
4.Loops(循環(huán))
Foreach Loop
#foreach 用來創(chuàng)建循環(huán). For example:
<ul>
#foreach( $product in $allProducts )
<li>$product</li>
#end
</ul>
#foreach 會生成包含$products中對象的一個列表. 每一次循環(huán)都會將列表中的一個對象賦與變量$product .
$allProducts 或以是一個Vector, a Hashtable or an Array類型的容器. 指定給變量 $product 是一個引用到其中一個java對象的引用. For example, if $product 確實是一個java代碼中的Product class i,它可以這樣的方法訪問$product.Name method (ie: $Product.getName()).
我們假設(shè) $allProducts 是一個Hashtable.看看取出其中的東東多么簡單:
<ul>
#foreach( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key)</li>
#end
</ul>
通過引用變量$velocityCount可以訪問到Velocity提供的計數(shù)器:
<table>
#foreach( $customer in $customerList )
<tr><td>$velocityCount</td><td>$customer.Name</td></tr>
#end
</table>
$velocityCount默認的計數(shù)器引用，你可以在配置velocity.properties中改成你喜歡的:
# Default name of the loop counter
# variable reference.
directive.foreach.counter.name = velocityCount
# Default starting value of the loop
# counter variable reference.
directive.foreach.counter.initial.value = 1
當(dāng)然，你還可以設(shè)置其它參數(shù)，具體見《Velocity Java開發(fā)指南中文版》中講解.
# The maximum allowed number of loops.
directive.foreach.maxloops = -1
3.Include(引入)
#include 腳本元素讓模板設(shè)計者可以在模板中引入一個本地文件, 這個被引入的文件將不會經(jīng)過Velocity的解析. 安全起見，可以引放的文件只是是配置參數(shù)TEMPLATE_ROOT所定義目錄下的，默認為當(dāng)前目錄下.
#include( "one.txt" )
如果需要引入多個文件，可以像下面這樣.
#include( "one.gif","two.txt","three.htm" )
當(dāng)然，還可用一個變量名來代替文件名引入.
#include( "greetings.txt", $seasonalstock )
6.Parse(解析模板)
#parse 元素指示可以引入一個包含TVL的本地文件，這個文件將被Veloict engine解析輸出。.
#parse( "me.vm" )
與 #include 指令不同, #parse 可以從引入的模板中得到變量引用.但#parse指令只能接受一個參數(shù).
VTL templates 被#parse 的模板中還可以再包含#parse聲明，默認的深度為10，這是由配置參數(shù)directive.parse.max.depth在文件velocity.properties中決定的，你可以修改它以適合項目要求
7.Stop
#stop 指令用來指示在模板的某處，engine停止解析，這一般用來調(diào)用。用法很簡單.
#stop
8.Velocimacros(宏調(diào)用)
#macro 指令讓模板設(shè)計者可以將些重復(fù)、相關(guān)的的腳本版斷定義為一個功能塊.無論在什么情況下. 出于單一意圖設(shè)計的 Velocimacro都會最大程序的減少模板編寫中可以的出錯,還是看個例子來理解一下Velocimacros的概念.
#macro( d )
<tr><td></td></tr>
#end
這樣就定義了一個名為d的宏，它可以在其它的模板中像下面那樣直接引用:
#d()
Velocimacro可以接收0到任意多的傳入?yún)?shù).如上個例是0個參數(shù),但當(dāng)它被調(diào)用時，也必須傳入同樣多的參數(shù). 這里定義了一個有兩個參數(shù)的宏.
#macro( tablerows $color $somelist )
#foreach( $something in $somelist )
<tr><td bgcolor=$color>$something</td></tr>
#end
#end
然后，我們在頁面中來使用：
#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
#tablerows( $color $greatlakes )
</table>
注意變量 $greatlakes 取代了宏中變量 $somelist的輸出，最終的輸出如下:
<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>
宏一般被定義在模板中，那么站點上的其它模板中又如何調(diào)用呢？如能定義一個可以更大范圍內(nèi)共想的宏就太好了
如果將宏#tablerows($color $list) 定義到一個模板庫中(Velocimacros template library), 其它模板就都可以訪問它了.
Velocimacro Arguments（宏的參數(shù)）
Velocimacros可以從TVL中接受以下參數(shù) :
- 引用類型 : 所有以‘$‘開頭的
- String literal : something like "$foo" or ‘hello‘
- Number literal : 1, 2 etc
- IntegerRange : [ 1..2] or [$foo .. $bar]
- ObjectArray : [ "a", "b", "c"]
- boolean value true
- boolean value false
當(dāng)傳一個引用參數(shù)給宏時, 引用是通過名字傳入的(‘pass by name‘).
#macro( callme $a )
$a $a $a
#end
#callme( $foo.bar() )
上例中命令 bar() 被調(diào)用了3 times.
最后要說的是,這個特性有些難以學(xué)習(xí),但當(dāng)你精心組織規(guī)劃你的宏庫時， 消除在VTL中重復(fù)功能的腳本時 –你可以像使用一個對象或組件一樣使用宏, 比如一個宏對象生成多個表格的重復(fù)色彩.
如果你想利用這個特性，你只需要像下面那樣簡單的編碼傳一個值給它來調(diào)用 :
#set( $myval = $foo.bar() )
#callme( $myval )
Velocimacro Properties(宏的屬性)
配置文件 velocity.properties 中有多行相關(guān)配置，具體請見《Velocity Java開發(fā)指南中文版》.
velocimacro.library –用來指定全局的宏庫，多個可以,號分開.
velocimacro.permissions.allow.inline – 默認為true,可以讓宏定義在一個正規(guī)的模板文件中.
velocimacro.permissions.allow.inline.to.replace.global – 用來指定模板內(nèi)定義的宏的功能是否要以替換全局庫，默認為false.
velocimacro.permissions.allow.inline.local.scope –模板中定義的宏的使用范圍是否只是本模板可用.
velocimacro.context.localscope –如果為true,宏通過#set賦值時.宏中將保持一個，且不會由于context中的數(shù)據(jù)被修改而變化,同樣，宏中的修改也不會改變context中的。
velocimacro.library.autoreload – 是否自動重新載入，用于調(diào)試環(huán)境,默認false,如為true,需要取掉chcheing:. file.resource.loader.cache = false ).
一些細節(jié)：
宏必須在模板中使用#macro()指令前定義.
盡量不要直接在模板中使用#parse() 包含 #macro() 指令.因為 #parse() 動作在運行時執(zhí)行,時會有一個在VM中查找元素的過程.
13.注掉 VTL Directives
嗯，你學(xué)下英語吧，一看就懂J
VTL directives can be escaped with the backslash character ("\") in a manner similar to valid VTL references.
## #include( "a.txt" ) renders as <contents 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" )
Extra care should be taken when escaping VTL directives that contain multiple script elements in a single directive (such as in an if-else-end statements). Here is a typical VTL if-statement:
#if( $jazz )
Vyacheslav Ganelin
#end
If $jazz is true, the output is
Vyacheslav Ganelin
If $jazz is false, there is no output. Escaping script elements alters the output. Consider the following case:
\#if( $jazz )
Vyacheslav Ganelin
\#end
Whether $jazz is true or false, the output will be
#if($ jazz )
Vyacheslav Ganelin
#end
In fact, because all script elements are escaped, $jazz is never evaluated for its boolean value. Suppose backslashes precede script elements that are legitimately escaped:
\\#if( $jazz )
Vyacheslav Ganelin
\\#end
In this case, if $jazz is true, the output is
\ Vyacheslav Ganelin
\
To understand this, note that the #if( arg ) when ended by a newline (return) will omit the newline from the output. Therefore, the body of the #if() block follows the first ‘\‘, rendered from the ‘\\‘ preceding the #if(). The last \ is on a different line than the text because there is a newline after ‘Ganelin‘, so the final \\, preceding the #end is part of the body of the block.
If $jazz is false, the output is
\
Note that things start to break if script elements are not properly escaped.
\\\#if( $jazz )
Vyacheslave Ganelin
\\#end
Here the #if is escaped, but there is an #end remaining; having too many endings will cause a parsing error.
14.VTL: 一般使用的格式
盡量是這樣：
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
$shogun
#end
而不要這樣寫，雖然它可以運行:
Send #set($foo=["$10 and ","a pie"])#foreach($a in $foo)$a#end please.
Velocity會自動跳過空格，上面的可以這樣寫：:
Send me
#set( $foo = ["$10 and ","a pie"] )
#foreach( $a in $foo )
$a
#end
please.
or as
Send me
#set($foo = ["$10 and ","a pie"])
#foreach ($a in $foo )$a
#end please.
In each case the output will be the same.
15.Other Features and Miscellany(其它特性和細節(jié))
1.數(shù)學(xué)計算
如下是四則運算的例子:
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
2.Range Operator
The range operator can be used in conjunction with #set and #foreach statements. Useful for its ability to produce an object array containing integers, the range operator has the following construction:
[n..m]
Both n and m must either be or produce integers. Whether m is greater than or less than n will not matter; in this case the range will simply count down. Examples showing the use of the range operator as provided below:
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]
Produces the following output:
First example:
1 2 3 4 5
Second example:
2 1 0 -1 -2
Third example:
0 1
Fourth example:
[1..3]
Note that the range operator only produces the array when used in conjunction with #set and #foreach directives, as demonstrated in the fourth example.
Web page designers concerned with making tables a standard size, but where some will not have enough data to fill the table, will find the range operator particularly useful.
3.Advanced Issues: Escaping and !
When a reference is silenced with the ! character and the ! character preceded by an \ escape character, the reference is handled in a special way. Note the differences between regular escaping, and the special case where \ precedes ! follows it:
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
This renders as:
$!foo
$!{foo}
$\!foo
$\\!foo
Contrast this with regular escaping, where \ precedes $:
\$foo
\$!foo
\$!{foo}
\\$!{foo}
This renders as:
$foo
$!foo
$!{foo}
\bar
4.Velocimacro Miscellany(關(guān)于宏的一些問題)
這是一些簡短的問題總結(jié),也許你先要有這樣一個概念:. ‘Velocimacro‘ 就像一個‘VM’。
可否用一個指示符做為另外一個指示符運算的參數(shù)?
如 : #center( #bold("hello") )
No. 指示符不是有效的參數(shù)但你可以這樣實現(xiàn)你想要的：
#set($stuff = "#bold(‘hello‘)" )
#center( $stuff )
或者：
#center( "#bold( ‘hello‘ )" )
上面這個例子中，參數(shù)是在調(diào)用的宏中生成的.不是調(diào)用者傳入的. 看看下面的例子 :
#macro( inner $foo )
inner : $foo
#end
#macro( outer $foo )
#set($bar = "outerlala")
outer : $foo
#end
#set($bar = ‘calltimelala‘)
#outer( "#inner($bar)" )
輸出將是:
Outer : inner : outerlala
因為 "#inner($bar)" 是發(fā)生在 #outer()內(nèi)部的！
可否通過 #parse()來注冊一個宏 ?
宏必須在模板使用前定義好.前面己有一個關(guān)于此問題的建議，#parse()是運行時執(zhí)進的，JVM查找對象的順序不一定會全按我們預(yù)計的執(zhí)行。
什么是宏的自動重新裝載?
這是由配置參數(shù)決定的, 為方例開發(fā)者，在生產(chǎn)環(huán)境中則不需要 :
velocimacro.library.autoreload
默認的是false.當(dāng)設(shè)為true中，需要設(shè)定chcheing參數(shù);
<type>.resource.loader.cache = false
(具體配置請見開發(fā)指南，如下是一個配置的例子)
file.resource.loader.path = templates
file.resource.loader.cache = false
velocimacro.library.autoreload = true
注意：Don‘t keep this on in production.
5.String Concatenation(連結(jié)字符串)
很簡單，看例子就是 :
#set( $size = "Big" )
#set( $name = "Ben" )
The clock is $size$name.
上面的輸出將是
‘The clock is BigBen‘.
或者：
#set( $size = "Big" )
#set( $name = "Ben" )
#set($clock = "$size$name" )
The clock is $clock.
它們都是同樣的輸出，最后一個例子如下，:
#set( $size = "Big" )
#set( $name = "Ben" )
#set($clock = "${size}Tall$name" )
The clock is $clock.
輸出將是
‘The clock is BigTallBen‘.
16.Feedback
如果您有什么問題或建議，請聯(lián)系 Velocity developers list. Thanks!
