Velocity的資料【轉】

http://wiki.hotoo.me/Velocity-Notes.html---來源，感謝做者的辛苦！

Velocity Notes

變量名

$name

爲空時打印變量自己。

$!name

爲空時打印空字符串（不打印任何內容）。

${name}

相似 $name，爲空時原樣打印。但能夠將變量和連續的字符串分隔，例如：${name}space。

$!{name}

相似 $!name，爲空時打印空字符串，但能夠將變量和連續的字符串分隔。例如： $!{name}space。

	$name	$!name	${name}	$!{name}
爲空時打印：	"$name"	""	"${name}"	""

帶花括號的屬性/方法調用方式，屬性/方法須要在花括號以內：

${cookie.name}
${request.getCookies()}

#set() 中，賦值符號左邊的變量名不能加感嘆號。

#set($idx = 0)
#foreach($!item in $!list)
    #set($idx = $!idx + 1)
#end

注：jQuery 的 $.ajax() 之類的代碼會致使 Velocity 解析異常，好在 Javascript 語法的靈活性，能夠增長無效空白 $ .ajax()，固然也可使用 jQuery.ajax()

#set()

#set($list = ["pine", "oak", "maple"])

注： 若是右側的值爲 null，則賦值失敗，左側變量仍保持原值。

#if()

#if(true)
    TRUE.
#elseif(false)
    FALSE.
#end

其實不單單是變量名可使用花括號，保留字一樣可使用，這在內聯 Velocity 腳本的時候 很是有用。 例如：

#foreach()

#foreach($item in $list)
    ${velocityCount}. $item.
#end

#break

可用於中斷 #foreach() 循環。

#parse()

例如：a.vm 中包含以下代碼

#parse("b.vm")

則在解析 a.vm 頁面的這行代碼時，先將 b.vm 插入到其所在的位置，並解析執行， 並且 b.vm 能夠共享 a.vm 中的變量。

若是 a.vm #parse("b.vm")，b.vm 能夠直接使用 a.vm 中定義的變量。 注意：若是 b.vm 定義了同名變量，則 b.vm 中使用自身的定義。

#evaluate()

動態執行一串字符串的值：

#evaluate('string with VTL #if(true)will be displayed#end')

#include()

將文件原文包含進當前文檔中。

#include("a.vm" "readme.txt")

#define()

相似於 C 語言的 #define 命令。

#define($hello)
        Hello ${who}!
    #end
    #set($who = "World")

    $hello
    ## 顯示 "Hello World!"

數組 & 訪問

Velocity 訪問數組對象，沒法經過相似 arr[2] 來訪問特定位置的元素。

#set($arr = [0, 1, 2, 3])
$arr.get(2)

注：Velocity 中的數組對應 Java 中的 List 對象。對於 Java 原生 Array 對象， 只可以 #foreach 進行遍歷，沒法使用 $arr[0]和 $arr.get(0) 方法。

範圍(range)

#foreach($item in [10..20])
    $item
#end

對象 & 訪問

#set($obj = {"key":"value", "name":"space"})
$obj.get("key")

#foreach(#item in $obj)
    $item
#end

上面的 $item 取到的是 values，若是須要在遍歷對象過程當中，同時取到對象的 keys， 可使用 entrySet() 或 keySet() 方法。

#foreach($item in $!obj.entrySet())
    $!item.key : $!item.value
#end

#foreach($item in $obj.keySet())
    $item : $obj.get($item)
#end

注： 這種集合的遍歷是無序的，即遍歷順序可能不一樣於 $obj 中元素的定義順序 （據目前所知，是根據鍵的字母排序的）。

另外有兩種不完美解決方法：

1. I:

   #set($obj = [
       {"key":"key", "value":"value"},
       {"key":"name", "value":"space"}
       ])
   #foreach($item in $obj)
       $item.key : $item.value
   #end

2. II:

   #set($obj = [
       ["key","value"],
       ["name","space"]
       ])
   #foreach($item in $obj)
       $item.get(0) : $item.get(1)
   #end

之因此說 不完美 是由於：對於已知的 key，本能夠直接

$obj.get("key")

如今只能遍歷並進行比較取得，並且較早的 Velocity 版本沒法使用 #break， 以便在找到匹配項以後當即退出循環。

#foreach($item in $obj)
    #if("key" == $!obj.get(0))
        #set($myKey = $!type.get(1))
        ##break
    #end
#end

#macros()

#macro(macroName)
    #subMacro("name", "value")
#end

#macro(subMacro $param1 $param2)
    this is sub macro($param1, $param2).
#end

注意：若是 a.vm 和 b.vm 都在頁面級存在同名，參數數量相同的宏，則後訪問的頁面 的宏不被加載。

參考：

1. Velocity宏Velocimacros

#stop

中止模板引擎，在 Debug 時比較有用。

條件比較

在 Velocity 中可使用大於(>)/小於(<)/等於(==)之類的符號，與編程語言中的意義一致， 不過要注意的是這些符號不能直接接在變量以後，除非變量使用帶花括號的表示方式。 例如：if($num>1) 要修改成 if($num > 1) 或 if(${num}>1)。

轉義

$\name
$\{name}

不解析執行的內容

#[[
    這段內容將不被 Velocity 引擎解析，原文打出。

    * #define()
    * ${blah

]]#

內置對象

$request, $response, $session

#foreach($cookie in $request.getCookies())
    $cookie.name : $cookie.value
#end

得到 URL 中的參數：

#set($n = $!request.getParameter('n'))

另外還可使用 $msg 內的消息工具訪問 Struts 的國際化資源。

參考：

1. Interface ServletRequest
2. Interface HttpServletRequest

註釋

## 單行註釋。
#*
 * 多行註釋。
 *#

#**
 * 文檔風格的註釋。
 * @version 2010/12/27
 *#

聽說 vm 頁面的末尾寫註釋，會致使解析異常 (SofaMVC?)。

Tips

Velocity 在表單中添加 name="action" 的文本/隱藏域，能夠調用對應 Java 類 （submit 按鈕的 name 則指定對應的方法名稱，如 event_submit_do_save ）， 可是此時 IE 瀏覽器經過 js 得到 form 元素自己的 action 屬性值的方式， 和其餘瀏覽器稍有不一樣。

例如對於以下 HTML DOM 結構：

<form action="attr">
    <input name="action" value="elem" />
</form>

IE 中須要使用

form.attributes["action"].value

非 IE 瀏覽器還可使用：

form.getAttribute("action")

如下是些詳細的對照：

// codes                            //  IE          !IE
form.action.value                   // elem         elem
form.getAttribute("action")         // [object]     attr
form.getAttribute("action").value   // elem         undefined
form.attributes["action"].value     // attr         attr

Form 自己的 action 屬性和 action 隱藏域在提交時，瀏覽器自己不受影響， action 隱藏域被看成正常的參數附在 Form 的 action 屬性值所對應 URL 以後。

延伸閱讀

1. Velocity
2. Alipay-SofaMVC
3. VTL Reference
4. 《Velocity 用戶指南手冊中文版》