Velocity介紹
--入門之二 語言本身介紹
|
1. 關於
Velocity 用戶指南旨在幫助頁面設計者和內容提供者瞭解Velocity 和其簡單而又強大的腳本語言（Velocity Template Language (VTL)）。本指南中有很多示例展示了用Velocity來講動態內容嵌入到網站之中，但是所有的VTL examples 都同演示用於所有的頁面和模版。
感謝選擇Velocity!
2. 什麼是Velocity?
Velocity 是一個基於Java的模版引擎。它允許web 頁面設計者引用JAVA代碼預定義的方法。Web 設計者可以根據MVC模式和JAVA程序員並行工作，這意味着Web設計者可以單獨專注於設計良好的站點，而程序員則可單獨專注於編寫底層代碼。Velocity 將Java 代碼從web頁面中分離出來，使站點在長時間運行後仍然具有很好的可維護性，並提供了一個除JSP和PHP之外的可行的被選方案。
Velocity可用來從模板產生web 頁面，SQL, PostScript以及其他輸出。他也可用於一個獨立的程序以產生源代碼和報告，或者作爲其它系統的一個集成組件。這個項目完成後，Velocity將爲Turbine web 應用程序框架提供模板服務。Velocity Turbine 方案提供的模板服務將允許web 應用按真正的mvc模式進行開發。
3. Velocity 可以做什麼?
3.1. Mud Store 示例
假設你是一個專門銷售泥漿（MUD）的在線商店的頁面設計者。我們稱他爲"The Online Mud Store"。生意很好。客戶訂購各種各樣的類型和數量的泥漿。他們使用他們的用戶名和密碼登陸到商店中來，就可以瀏覽他們的訂貨和購買其他東西。現在，赤土陶泥正在促銷，這是一種很常用的泥巴。一少部分顧客很有規律的購買一種亮紅土Bright Red Mud，這也是促銷產品，但是不太常用，因此被移到頁面的邊緣。所有顧客的信息都在數據庫中被跟蹤，因此有一天問題出現了： 爲什麼不使用Velocity來定位目標客戶，這些客戶對某種類型的產品特別感興趣？
Velocity 使針對訪問者個性的WEB頁面客戶化（個性化）非常容易。作爲一個在線泥巴商店的站點設計者，以想在客戶以登陸進展點後就看到它們想看的頁面。
你遇到你公司的軟件工程師，每個人都認爲 $customer 將保持當前登陸進入的客戶信息，而 $mudsOnSpecial 將士當前所有促銷的泥巴。 $flogger 對象包含有助於促銷的方法。對於當前的任務，讓我們僅關注這三個問題。記住，你不需要擔心軟件工程師如何從數據庫中取得顧客信息，但你必須知道他們可以。這樣可以使你專注於你的工作而軟件工程師則忙於他們自己的工作。
你可以在你的頁面中嵌入如下的VTL語句：
<HTML>
<BODY>
Hello $customer.Name!
<table>
#foreach( $mud in $mudsOnSpecial )
#if ( $customer.hasPurchased( $mud) )
<tr>
<td>
$flogger.getPromo( $mud )
</td>
</tr>
#end
#end
</table>
foreach 語句的細節將進一步細說，但重要的是這個短小的腳本居然可以在你的站點上運行。當有一個傾向於亮紅土的顧客登陸進來時，亮紅土正在促銷，這就是這個顧客所看到的，並且促銷顯示非常顯著。如果另外一個長期購買赤陶土的顧客登陸進來，赤陶土促銷的提示信息則應該在前面中間位置。Velocity是非常靈活的，受限的只是你的創造力。
寫在VTL參考文檔中的是其他Velocity 元素，他們一起給你很強大的能力和靈活性以創建很好的站點。待你更加了解這些元素，就可以開始釋放Velocity的強大動力。
4. Velocity模板語言(VTL): 介紹
Velocity模板語言(VTL)旨在爲Web頁面結合動態內容提供最容易、簡單和簡潔的方法。即使有一點或者沒有編程經驗的頁面設計者也可以很快能爲頁面提供動態內容。
VTL 使用引用（references ）來將動態內容嵌入web頁面，每個變量就是某一個類型的引用。變量實際上是一個可以調用定義在java代碼中的內容的引用，或者它可以從頁面內的VTL語句得出自身的值。下面是一個例子，說明可以嵌入到HTML文檔中的VTL語句。
#set( $a = "Velocity" )
這個VTL語句，就像所有的VTL語句一樣，以 # 字符開始，並跟着一個指令set。 當一個在線訪問這請求頁面時， Velocity 模伴引擎在頁面內搜索所有# 字符，然後決定是哪一個標記了VTL語句的開始，哪個標記不需要VTL做什麼動作。
# 字符後面緊跟一個指令 set.。set 指令使用一個括在括號內的表達式---一個等式將一個值指派給一個變量。變量在等號的左邊而值在等號的右邊。
在上面的示例中，變量是 $a 值是Velocity。 這個變量就象其他引用一樣，以一個 $字符開始。值通常在引號之中，對Velocity來說一般沒有類型衝突的問題，因爲只有字符串 (基於文本的信息)可以傳遞給變量。
下面的主要規則可能有助於理解Velocity 是如何工作的：引用以 $開頭用於取得什麼東西，而指令以# 開始用於做什麼事情。
在上面的例子中，#set 用於將一個值指派給一個變量。而變量 $a 則可以用來在模板中輸出"Velocity" 。
5. Hello Velocity World!
一旦一個值被賦給一個變量，便可以在HTML中隨處引用它。在下面的示例中，先給變量 $foo 賦值然後引用它。
<html>
<body>
#set( $foo = "Velocity" )
Hello $foo World!
</body>
<html>
這個頁面的結果是輸出"Hello Velocity World!"。
爲了使包含VTL 指令的語句具有可讀性，我們鼓勵每個VTL語句在一個新行開始，雖然並不一定要這樣做。 set 將隨後深入解釋。
6. 註釋
可以用註釋加入描述性文本，他們並不在模板引擎中輸出。註釋可以有助於你的記憶或者想其他人解釋你的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.
*#
Here is text outside the multi-line comment; it is visible.
下面事一些例子說明單行註釋和多行註釋如何工作。
This text is visible. ## This text is not.
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 the
multi-line comment. This text still not visible. *# This text is outside
the comment, so it is visible.
## This text is not visible.
還有第三種註釋， VTL 註釋塊，可以用來存儲諸如文檔作者、版本信息等。
#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
information:
@author
@version 5
*#
7. 引用
VTL中有三種類型的引用：變量，屬性和方法。作爲使用VTL的設計者，你和你的工程師必須在飲用的特定命名上取得一致，以便在你的模板中正確的使用他們。
有關引用的所有參數都處理爲字符串對象。Everything coming to and from a reference is treated as a String object. 假如有一個對象表示 $foo (比如說是整型對象)，Velocity 將調用其toString() 方法來將此對象轉換爲一個字符串。
7.1. 變量Variables
變量的簡略標記是有一個前導" $"字符後跟一個 VTL 標識符（Identifier.）組成。一個VTL 標識符必須以一個字母開始(a .. z或 A .. Z)。剩下的字符將由以下類型的字符組成：
字母 (a .. z, A .. Z)
數字 (0 .. 9)
連字符("-")
下劃線 ("_")
下面是一些有效的變量引用:
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
當VTL 引用一個變量時，比如 $foo，變量可以從模板的set 指令取得值，也可以從
Java 代碼中取得。例如，如果Java 變量 $foo 在模板被請求的時候具有值bar ，則bar 將替換頁面中的所有 $foo 的實例。或者，如果包含下面的語句：
#set( $foo = "bar" )
緊跟指令後的所有 $foo 的實例的輸出將會一樣值。
7.2. 屬性
VTL引用的第二種元素是屬性，而屬性具有獨特的格式。屬性的簡略標記識前導符 $ 後跟一個VTL 標識符，在後跟一個點號(".")最後又是一個VTL 標識符。這是一些有效的示例： $customer.Address
$purchase.Total
請看第一個例子， $customer.Address.。他有兩種意思。 它可以意味着，查詢由customer 標是的哈希表並按關鍵字Address返回值。但是 $customer.Address
也可能引用一個方法（下述， $customer.Address 可能是 $customer.getAddress().的縮寫。當一個頁面被請求時，Velocity 將決定這兩種可能到底是哪一個，然後返回相應的值。
7.3. 方法
方法在JAVA代碼中定義，並作一些有用的事情，比如運行一個計算器或者作出一個決定。方法是實際上也是引用，由前導符" $"後跟一個VTL 標識符，後跟一個VTL 方法體（Method Body）。 VTL 方法體由一個VTL 標識符後跟一個左括號，再跟可選的參數列表，最後是右括號。下面是一些有效的方法示例：
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
前面兩個例子-- $customer.getAddress() 和 $purchase.getTotal() – 看起來有點象上面屬性一節中所用的樣子， $customer.Address 和 $purchase.Total.。如果你想這些例子在某些方面相關，那你就對了。
VTL 屬性可以爲VTL方法用作簡略標記。屬性 $customer.Address 具有和方法 $customer.getAddress() 完全一樣的效果。屬性和方法的主要不同點是方法中可以添加參數列表。
簡略標記可以用在下面的方法中：
sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()
我們或許希望方法可以爲我們放回屬於太陽系的行星的名字，餵養我們的蚯蚓，或者從相冊中返回一張照片。下面只有長的那個標記是可以工作的方法：
$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## 不能將參數列表傳遞給 $sun.Planets
$sisyphus.pushRock()
## Velocity 假定我意思是 $sisyphus.getRock()
$book.setTitle( "Homage to Catalonia" )
## 不能傳遞一個參數列表
7.4. 形式引用符Formal Reference Notation
引用的簡略符號如上所述，但是另外還有一種引用的形式符號，示例如下：
${mudSlinger}
${customer.Address}
${purchase.getTotal()}
在大多數情況下，我們將使用引用的簡略符號，但在一些情況下，也需要擁戴哦形式引用符以便正確處理。
假定你正在紙片上構件一個句子，將使用 $vice 作爲句子中名詞的詞根。我們的目標是允許人們選擇詞根，然後產生以下兩種結果之一：
"Jack is a pyromaniac."
或者 "Jack is a kleptomaniac."。
在這種情況下，使用簡略符號是不太充分的。考慮到下面的例子：
Jack is a $vicemaniac.
這裏有個不確定性， Velocity 假定 $vicemaniac，（而不是 $vice） 是一個你想要使用的標識符。 找不到 $vicemaniac的值，他將返回 $vicemaniac。使用形式符號便可解決這個問題：
Jack is a ${vice}maniac
現在Velocity 知道 $vice（而不是 $vicemaniac） 是一個引用。形式符號常用在飲用咋模板中和文本直接鄰近的地方。
7.5. 安靜引用符Quiet Reference Notation
當 Velocity 遇到一個位定義的引用時，其通常行爲是輸出這個引用的映像。比如，假設下面的引用出現在模板中的一部分：
<input type="text" name="email" value=" $email"/>
當表單初次裝入時，變量引用 $email 無值，你寧願是一個空白域而不是具有值" $email"。使用安靜引用符可以繞過Velocity的常規行爲，在VTL中不用 $email 而是用 $!email 符號。 所以，上面的例子將會看起來像下面的樣子：
<input type="text" name="email" value=" $!email"/>
現在，當表單初次裝入時， $email 仍然沒有值，但是將輸出空字符串而不是" $email"。
形式和安靜引用符可以一起使用，如下所示：
<input type="text" name="email" value=" $!{email}"/>
|