Stop
#stop script element允許模板設計者停止執行模板引擎並返回。把它應用於debug是很有幫助的。
#stop
Velocimacros
#macro script element允許模板設計者定義一段可重用的VTL template。例如：
#macro ( d )
〈tr〉〈td〉〈/td〉〈/tr〉
#end
在上面的例子中Velocimacro被定義爲d，然後你就可以在任何VTL directive中以如下方式調用它：
#d()
當你的template被調用時，Velocity將用〈tr〉〈td〉〈/td〉〈/tr〉替換爲#d()。
每個Velocimacro可以擁有任意數量的參數――甚至0個參數，雖然定義時可以隨意設置參數數量，但是調用這個Velocimacro時必須指定正確的參數。下面是一個擁有兩個參數的Velocimacro，一個參數是color另一個參數是array：
- #macro ( tablerows $color $somelist )
- #foreach ( $something in $somelist )
- 〈tr〉〈td bgcolor=$color〉$something〈/td〈/tr〉
- #end
- #end
調用#tablerows Velocimacro：
- #set ( $greatlakes = [ “Superior”, “Michigan”, “Huron”, “Erie”, “Ontario” ] )
- #set ( $color = “blue” )
- 〈table〉
- #tablerows( $color $greatlakes )
- 〈/table〉
經過以上的調用將產生如下的顯示結果：
- 〈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模板內實現行內定義（inline），也就意味着同一個web site內的其他Velocity模板不可以獲得Velocimacros的定義。定義一個可以被所有模板共享的Velocimacro顯然是有很多好處的：它減少了在一大堆模板中重複定義的數量、節省了工作時間、減少了出錯的機率、保證了單點修改。
上面定義的#tablerows( $color $list )Velocimacro被定義在一個Velocimacros模板庫(在velocity.properties中定義)裏，所以這個macro可以在任何規範的模板中被調用。它可以被多次應用並且可以應用於不同的目的。例如下面的調用：
- #set ( $parts = [ “volva”, “stipe”, “annulus”, “gills”, “pileus” ] )
- #set ( $cellbgcol = “#CC00FF” )
- 〈table〉
- #tablerows( $cellbgcol $parts )
- 〈/table〉
上面VTL將產生如下的輸出：
- 〈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可以使用以下任何元素作爲參數：
l Reference：任何以$開頭的reference
l String literal：
l Number literal：
l IntegerRange：[1….3]或者[$foo….$bar]
l 對象數組：[“a”,”b”,”c”]
l boolean值：true、false
當將一個reference作爲參數傳遞給Velocimacro時，請注意reference作爲參數時是以名字的形式傳遞的。這就意味着參數的值在每次Velocimacro內執行時纔會被產生。這個特性使得你可以將一個方法調用作爲參數傳遞給Velocimacro，而每次Velocimacro執行時都是通過這個方法調用產生不同的值來執行的。例如：
- #macro ( callme $a )
- $a $a $a
- #end
- #callme( $foo.bar() )
執行的結果是：reference $foo的bar（）方法被執行了三次。
如果你不需要這樣的特性可以通過以下方法：
#set ( $myval = $foo.bar() )
#callme ( $myval )
Velocimacro properties
Velocity.properties文件中的某幾行能夠使Velocimacros的實現更加靈活。注意更多的內容可以看Developer Guide。
Velocity.properties文件中的velocimacro.libraary：一個以逗號分隔的模板庫列表。默認情況下，velocity查找唯一的一個庫：VM_global_library.vm。你可以通過配置這個屬性來指定自己的模板庫。
Velocity.properties文件中的velocimacro.permissions.allow.inline屬性：有兩個可選的值true或者false，通過它可以確定Velocimacros是否可以被定義在regular template內。默認值是ture――允許設計者在他們自己的模板中定義Velocimacros。
Velocity.properties文件中的
velocimacro.permissions.allow.inline.replace.global屬性有兩個可選值true和false，這個屬性允許使用者確定inline的Velocimacro定義是否可以替代全局Velocimacro定義（比如在velocimacro.library屬性中指定的文件內定義的Velocimacro）。默認情況下，此值爲false。這樣就阻止本地Velocimacro定義覆蓋全局定義。
Velocity.properties文件中的
velocimacro.permissions.allow.inline.local.scale屬性也是有true和false兩個可選值，默認是false。它的作用是用於確定你inline定義的Velocimacros是否僅僅在被定義的template內可見。換句話說，如果這個屬性設置爲true，一個inline定義的Velocimacros只能在定義它的template內使用。你可以使用此設置實現一個奇妙的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兩個可選值，默認值爲false。當設置爲true時，任何在Velocimacro內通過#set()對context的修改被認爲是針對此velocimacro的本地設置，而不會永久的影響內容。
Velocity.properties文件中的velocimacro.library.autoreload屬性控制Velocimacro庫的自動加載。默認是false。當設置爲ture時，對於一個Velocimacro的調用將自動檢查原始庫是否發生了變化，如果變化將重新加載它。這個屬性使得你可以不用重新啓動servlet容器而達到重新加載的效果，就像你使用regular模板一樣。這個屬性可以使用的前提就是resource loader緩存是off狀態（file.resource.loader.cache = false）。注意這個屬性實際上是針對開發而非產品的。
Velocimacro Trivia
Velocimacro必須被定義在他們被使用之前。也就是說，你的#macro()聲明應該出現在使用Velocimacros之前。
特別要注意的是，如果你試圖#parse()一個包含#macro()的模板。因爲#parse()發生在運行期，但是解析器在parsetiem決定一個看似VM元素的元素是否是一個VM元素，這樣#parse()-ing一組VM聲明將不按照預期的樣子工作。爲了得到預期的結果，只需要你簡單的使用velocimacro.library使得Velocity在啓動時加載你的VMs。
Escaping VTL directives
VTL directives can be escaped with “\”號，使用方式跟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” )
在對在一個directive內包含多個script元素的VTL directives使用逃逸符時要特別小心（比如在一個if-else-end statement內）。下面是VTL的if-statement的典型應用：
#if ( $jazz )
Vyacheslav Ganelin
#end
如果$jazz是ture，輸出將是：
Vyacheslav Ganelin
如果$jazz是false，將沒有輸出。使用逃逸符將改變輸出。考慮一下下面的情況：
\#if ( $jazz )
Vyacheslav Ganelin
\#end
現在無論$jazz是true還是false，輸出結果都是：
#if ( $jazz )
Vyacheslav Ganelin
#end
事實上，由於你使用了逃逸符，$jazz根本就沒有被解析爲boolean型值。在逃逸符前使用逃逸符是合法的，例如：
\\#if ( $jazz )
Vyacheslav Ganelin
\\#end
以上程序的顯示結果爲：
\ Vyacheslav Ganelin
\
但是如果$jazz爲false，那麼將沒有輸出。（書上說會沒有輸出，但是我覺得應該還有有“\”字符被輸出。）
VTL：Formatting issues
儘管在此用戶手冊中VTL通常都開始一個新行，如下所示：
#set ( $imperial = [ “Munetaka”, “Koreyasu”, “Hisakira”, “Morikune” ] )
#foreach ( $shogun in $imperial )
$shogun
#end
但是像下面這種寫法也是可以的：
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.
或者
Send me
#set($foo = [“$10 and “,”a cake”])
#foreach （$a in $foo ）$a
#end please.
這兩種的輸出結構將一樣。
其他特性和雜項
math 在模板中可以使用Velocity內建的算術函數，如：加、減、乘、除
#set ( $foo = $bar + 3 )
#set ( $foo = $bar - 4 )
#set ( $foo = $bar * 6 )
#set ( $foo = $bar / 2 )
當執行除法時將返回一個Integer類型的結果。而餘數你可以使用%來得到：
#set ( $foo = $bar % 5 )
在Velocity內使用數學計算公式時，只能使用像-n,-2,-1,0,1,2,n這樣的整數，而不能使用其它類型數據。當一個非整型的對象被使用時它將被logged並且將以null作爲輸出結果。
Range Operator
Range operator可以被用於與#set和#foreach statement聯合使用。對於處理一個整型數組它是很有用的，Range operator具有以下構造形式：
[n..m]
m和n都必須是整型，而m是否大於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]
上面四個例子的輸出結果爲：
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！
當一個reference被“！”分隔時，並且在它之前有逃逸符時，reference將以特殊的方式處理。注意這種方式與標準的逃逸方式時不同的。對照如下：
#set ( $foo = “bar” )
特殊形式 標準格式
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” ) )
不可以。一個directive的參數使用另外一個directive是不合法的。
但是，還是有些事情你可以作的。最簡單的方式就是使用雙引號：
#set ( $stuff = “#bold( ‘hello’ )” )
#center ( $stuff )
上面的格式也可以縮寫爲一行：
#center ( “#bold( ‘hello’ ) )
請注意在下面的例子中參數被evaluated在Velocimacro內部，而不是在calling level。例子：
#macro ( inner $foo )
inner : $foo
#end
#macro ( outer $foo )
#set ( $bar = “outerlala” )
outer : $foo
#end
#set ( $bar = ‘calltimelala’ )
#outer( “#inner($bar)” )
輸出結果爲：
outer : inner : outerlala
記住Veloctiy的特性：參數的傳遞是By Name的。例如：
#macro ( foo $color )
〈tr bgcolor = $color 〉〈td〉Hi〈/td〉〈/tr〉
〈tr bgcolor = $color 〉〈td〉There〈/td〉〈/tr〉
#end
#foo ( $bar.rowColor() )
以上代碼將導致rowColor()方法兩次調用，而不是一次。爲了避免這種現象的出現，我們可以按照下面的方式執行：
#set ( $color = $bar.rowColor() )
#foo ( $color )
can I register velocimacros via #parse()?
目前，Velocimacros必須在第一次被模板調用前被定義。這就意味着你的#macro()聲明應該出現在使用Velocimacros之前。
如果你試圖#parse()一個包含#macro() directive的模板，這一點是需要牢記的。因爲#parse()發生在運行期，但是解析器在parsetiem決定一個看似VM元素的元素是否是一個VM元素，這樣#parse()-ing一組VM聲明將不按照預期的樣子工作。爲了得到預期的結果，只需要你簡單的使用velocimacro.library使得Velocity在啓動時加載你的VMs。
What is velocimacro autoreloading？
velocimacro.library.autoreload是專門爲開發而非產品使用的一個屬性。此屬性的默認值是false。
String concatenation
開發人員最常問的問題是我如何作字符拼接？在java中是使用“＋”號來完成的。
在VTL裏要想實現同樣的功能你只需要將需要聯合的reference放到一起就行了。例如：
#set ( $size = “Big” )
#set ( $name = “Ben” )
The clock is $size$name.
輸出結果將是：The clock is BigBen.。更有趣的情況是：
#set ( $size = “Big” )
#set ( $name = “Ben” )
#set ( $clokc = “$size$name” )
The clock is $clock.
上例也會得到同樣的結果。最後一個例子，當你希望混合固定字段到你的reference時，你需要使用標準格式：
#set ( $size = “Big” )
#set ( $name = “Ben” )
#set ( $clock = “${size}Tall$name” )
The clock is $clock.
輸出結果是：The clock is BigTallBen.。使用這種格式主要是爲了使得$size不被解釋爲$sizeTall。