Velocity使用者指南
目錄
- 關於本指南
- Velocity是什麼?
- Velocity能爲我們做什麼？What can Velocity do for me?
- The Mud Store example
- Velocity模版語言（VTL）:入門Velocity Template Language (VTL): An Introduction
- Hello Velocity World!
- 註釋Comments
- 引用References
- 變量Variables
- 屬性Properties
- 方法Methods
- Formal Reference Notation
- Quiet Reference Notation
- Getting literal
- Currency
- Escaping Valid VTL References
- Case Substitution
- 標識符Directives
- Set
- 字符串常量String Literals
- 條件語句If-Else Statements
- Relational and Logical Operators
- foreach循環Foreach Loops
- 包含Include
- 解析Parse
- 停止Stop
- 宏Velocimacros
- Escaping VTL Directives
- VTL: Formatting Issues
- Other Features and Miscellany
- 數學Math
- 範圍操作符Range Operator
- 高級特性Advanced Issues: Escaping and !
- Velocimacro Miscellany
- 字符串聯String Concatenation
- 反饋Feedback
關於這個指南About this Guide
這個用戶指南目的在於幫助頁面設計人員和內容提供者掌握簡單但強大的Velocity和其模版語言（VTL）的語法。在本指南中的許多例子主要演示的是在Web頁面中嵌入動態的內容，但所有的VTL例子對於其他任何的頁面或者模版都是通用的、一致的。謝謝選擇Velocity!The Velocity User Guide is intended to help page designers and content providers get acquainted with Velocity and the syntax of its simple yet powerful scripting language, the Velocity Template Language (VTL). Many of the examples in this guide deal with using Velocity to embed dynamic content in web sites, but all VTL examples are equally applicable to other pages and templates.
Thanks for choosing Velocity!
什麼是Velocity？What is Velocity?
Velocity是一個基於Java的模版引擎。他允許使用者通過簡單而強大的模版語言引用Java代碼中定義的對象。在MVC的開發模式下，Web設計者和Java程序員可以並行的開發web站點，意味着web頁面的設計者能專注於站點的樣式而程序員能專注於書寫高質量的代碼。Velocity將Java
代碼和web頁面分開了，確保了站點在整個生命週期中更容易維護。較之JSP和PHP，提供了一種更有生命力的開發方式。Velocity
is a Java-based template engine. It permits web page designers to reference methods defined in Java code. Web designers can work in parallel with Java programmers to develop web sites according to the Model-View-Controller (MVC) model, meaning that web page
designers can focus solely on creating a well-designed site, and programmers can focus solely on writing top-notch code. Velocity separates Java code from the web pages, making the web site more maintainable over the long run and providing a viable alternative
to Java Server Pages (JSPs) or PHP.
Velocity還可以用來從模版中生成SQL，PostScript和XML。Velocity可以單獨的用來作爲生成代碼和報告的工具，也可以作爲一個組件集成到其他的系統中來作爲一個MVC框架的視圖引擎工廠。比如Web應用框架Turbine就是使用Velocity作模版生成服務。Velocity+Turbine能提供一個支持模版服務的真正的MVC開發模型。Velocity
can be used to generate web pages, SQL,
PostScript and other output from templates. It can be used either as a standalone utility for generating source code and reports, or as an integrated component of other systems. When complete, Velocity will provide
template services for the Turbine web application framework. Velocity+Turbine will provide a template service that will allow web applications to be developed according to a true MVC model.
Velocity能爲我做什麼？What can Velocity do for me?
泥土商店的例子The Mud Store Example
設想下你是一個頁面設計者，現在在爲一個泥土商店設計一個在線的銷售商店。我們就叫這個網上商店叫"在線泥土商店-.-!"。事業欣欣向榮，客戶們紛紛訂購不同類型和數量的泥土。客戶使用用戶名和密碼登陸你的站點，察看他們的訂單，購買更多的泥土。現在，流行的陶土也在線銷售。一小部分用戶有規律的購買亮紅色的泥土，但這種泥土不是很流行，往往也只能出現在頁面的靠邊的地方。每個用戶的信息都記錄在數據庫中，現在問題就出來了，爲什麼不使用Velocity來讓用戶直接得到他們最感興趣的泥土的信息？Suppose you are a page designer for an online store that specializes in selling mud. Let's call it "The Online Mud Store". Business is thriving. Customers place orders for various types and quantities of mud. They login to your site using their username and password, which allows them to view their orders and buy more mud. Right now, Terracotta Mud is on sale, which is very popular. A minority of your customers regularly buys Bright Red Mud, which is also on sale, though not as popular and usually relegated to the margin of your web page. Information about each customer is tracked in your database, so one day the question arises, Why not use Velocity to target special deals on mud to the customers who are most interested in those types of mud?
Velocity能很簡單的讓你的在線用戶定製不同的頁面。作爲一個站點的設計者，你希望用戶在登陸過後能看到他們希望看到的頁面。Velocity makes it easy to customize web pages to your online visitors. As a web site designer at The Mud Room, you want to make the web page that the customer will see after logging into your site.
你會見了你公司的軟件工程師，他們都同意使用$customer引用來保存當前登陸的用戶的信息，使用$mudsOnSpecial引用來保存當前正在出售的所有泥土的種類，使用$flogger對象來提供和促銷相關的方法。目前，我們先關注這三個引用對象。注意，你不需要關注數據是怎樣從數據庫中得到的，你只需要知道數據都能正確地得到。這種觀念能讓你專注於你的頁面工作，而其餘的事情都交給軟件工程師來做。You meet with software engineers at your company, and everyone has agreed that $customer will hold information pertaining to the customer currently logged in, that $mudsOnSpecial will be all the types mud on sale at present. The $flogger object contains methods that help with promotion. For the task at hand, let's concern ourselves only with these three references. Remember, you don't need to worry about how the software engineers extract the necessary information from the database, you just need to know that it works. This lets you get on with your job, and lets the software engineers get on with theirs.
你只需要將下面VTL語句嵌入你的頁面中：You could embed the following VTL statement in the web page:
<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具有高度的靈活性，只有你想不到的，沒有做不到的。The exact details of the
foreach statement will be described in greater depth shortly; what's important is the impact this short script can have on your web site. When a customer with a penchant for Bright Red Mud logs in, and Bright Red Mud is on sale, that is what this customer
will see, prominently displayed. If another customer with a long history of Terracotta Mud purchases logs in, the notice of a Terracotta Mud sale will be front and center. The flexibility of Velocity is enormous and limited only by your creativity.
在VTL指南中還包含了許多其他的Velocity元素，這些元素共同的工作，提供給你強大的功能和足夠的靈活性。當你熟悉了這些元素，你會逐漸釋放Velocity的強大力量。Documented in the VTL Reference are the many other Velocity elements, which collectively give you the power and flexibility you need to make your web site a web presence. As you get more familiar with these elements, you will begin to unleash the power of Velocity.
Velocity模版語言介紹Velocity Template Language (VTL): An Introduction
Velocity模版語言旨在於提供一個簡單、普通、清晰的方式來把動態的內容合併到Web頁面中。即便是一個只具有一點甚至沒有編程經驗的頁面設計者，都能迅速的掌握VTL併合理的使用到web站點的設計中。The Velocity Template Language (VTL) is meant to provide the easiest, simplest, and cleanest way to incorporate dynamic content in a web page. Even a web page developer with little or no programming experience should soon be capable of using VTL to incorporate dynamic content in a web site.
VTL使用引用（reference）來將動態的內容嵌入到web站點中。變量僅僅是引用中的一種，它能引用在Java代碼中定義的一些對象，並能獲得在web頁面中爲它賦的值。下面是一個能直接嵌入到HTML文檔中的VTL語句例子。VTL uses references to embed dynamic content in a web site, and a variable is one type of reference. Variables are one type of reference that can refer to something defined in the Java code, or it can get its value from a VTL statement in the web page itself. Here is an example of a VTL statement that could be embedded in an HTML document:
#set( $a = "Velocity" )
和所有的VTL語句一樣，在這個VTL語句中使用#符號開頭，並且包含一個指示符（directive）:set。當一個在線的訪問者請求這個web頁面，Velocity模版引擎會搜索你的web頁面，並找到所有的#符號，當確定#之後的是一個Velocity語句，則處理。對於Velocity來說，#並沒有實際的意義，只是表明之後是一個Velocity語句。This VTL statement, like all VTL statements, begins with the
# character and contains a directive: set. When an online visitor requests your web page, the Velocity Templating Engine will search through your web page to find all
# characters, then determine which mark the beginning of VTL statements, and which of the
# characters that have nothing to do with VTL.
在#之後跟一個指示符，set。set指示符使用一個表達式（包含在一個括號裏）------一個等號(=)來把一個值賦給一個變量。變量都是列在左邊，值放在右邊；兩者使用=分開。The # character is followed by a directive, set. The set directive uses an expression (enclosed in brackets) -- an equation that assigns a value to a variable. The variable is listed on the left hand side and its value on the right hand side; the two are separated by an = character.
在上面的例子中，變量是$a，值是Velocity。象所有的變量一樣，以$符號開頭。值一般都是放在引號裏；在Velocity中，不存在數據類型的混亂的情況，因爲只有字符串（文本信息）能夠賦值給變量。In the example above, the variable is $a and the value is Velocity. This variable, like all references, begins with the $ character. Values are always enclosed in quotes; with Velocity there is no confusion about data types, as only strings (text-based information) may be passed to variables.
下面的規則能讓你更好的理解Velocity是怎樣工作的：引用以$開頭，用來得到一些東西。指示符以#開頭，用來做一些事情。The following rule of thumb may be useful to better understand how Velocity works: References begin with $ and are used to get something. Directives begin with # and are used to do something.
在上面的例子中，#set 用來給一個變量賦值。在模版中，變量$a能夠輸出一個"Velocity"。In the example above, #set is used to assign a value to a variable. The variable, $a, can then be used in the template to output "Velocity".
Hello Velocity World!
當一個變量被賦予了一個值，你可以在你的HTML文檔中的任何位置使用這個引用。在下面的例子中，首先給變量$foo賦了一個值，並在之後被引用。Once a value has been assigned to a variable, you can reference the variable anywhere in your HTML document. In the following example, a value is assigned to $foo and later referenced.
<html>
<body>
#set( $foo = "Velocity" )
Hello $foo World!
</body>
<html>
該頁面的結果是在web頁面上顯示出"Hello Velocity World！"。The result is a web page that prints "Hello Velocity World!".
爲了讓VTL在頁面中更容易閱讀，我們建議你在每一句VTL語句都新起一行，但這並不是必須的。關於set指示符，我們在後面會再次仔細的介紹。To make statements containing VTL directives more readable, we encourage you to start each VTL statement on a new line, although you are not required to do so. The set directive will be revisited in greater detail later on.
註釋Comments
註釋允許你在頁面中加入一些描述性的文本，他們並不會在模版引擎的輸出中顯示。註釋能有效地提醒你一段VTL的意思或者其他需要注意的地方。下面是一個註釋的例子：Comments allows descriptive text to be included that is not placed into the output of the template engine. Comments are a useful way of reminding yourself and explaining to others what your VTL statements are doing, or any other purpose you find useful. Below is an example of a comment in VTL.
## This is a single line comment.
單行的註釋以##開頭並且在該行的結束即結束。如果你需要註釋一段話，那麼，你沒有必要把每一行都註釋成單行的註釋。使用以#*開頭，以*#結束的一段話能提供多行的註釋功能。如下面的例子：A single line comment begins with
## and finishes at the end of the line. If you're going to write a few lines of commentary, there's no need to have numerous single line comments. Multi-line comments, which begin with
#* and end with *#, are available to handle this scenario.
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.
下面是一些單行註釋和多行註釋混合使用的例子：Here are a few examples to clarify how single line and multi-line comments work:
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. ##這一行不可見
下面是另一種註釋的類型------Velocity備註塊。這個備註塊用來保存諸如文檔作者，文檔版本等信息。下面是一個例子：There is a third type of comment, the VTL comment block, which may be used to store such information as the document author and versioning information:
#** This is a VTL comment block and may be used to store such information as the document author and versioning information: @author @version 5 *#
引用References
在VTL中有三種類型的引用：變量，屬性和方法。作爲一個使用VTL的設計者，你必須和你的軟件工程師（程序員）在引用的名字上達成一致的標準，才能正確地在頁面中使用。There are three types of references in the VTL: variables, properties and methods. As a designer using the VTL, you and your engineers must come to an agreement on the specific names of references so you can use them correctly in your templates.
所有的引用對象都作爲一個字符串對象使用。比如$foo引用指向的是一個不是String的對象（比如一個Integer對象），那麼在Velocity引擎處理時，使用的該對象的.toString()方法來將該對象轉成字符串。Everything coming to and from a reference is treated as a String object. If there is an object that represents $foo (such as an Integer object), then Velocity will call its .toString() method to resolve the object into a String.
變量Variables
簡單說變量就是以$開頭，後跟一個合法的VTL標示符。一個合法的VTL標示符是以一個字符開頭，後跟下列字符：The shorthand notation of a variable consists of a leading "$" character followed by a VTL
Identifier. A VTL Identifier must start with an alphabetic character (a .. z or A .. Z). The rest of the characters are limited to the following types of characters:
- 字符alphabetic (a .. z, A .. Z)
- 數字numeric (0 .. 9)
- 連接符hyphen ("-")
- 下劃線underscore ("_")
下面是一些合法的VTL變量的例子：Here are some examples of valid variable references in the VTL:
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
當VTL引用了一個變量，比如$foo，則該變量能從set語句中，或者從Java代碼中得到值。比如一個Java變量$foo擁有一個bar的值，則當模版被請求的時候，bar這個值會代替頁面中所有的$foo變量。此外，如果包含了語句：When VTL references a variable, such as
$foo, the variable can get its value from either a set directive in the template, or from the Java code. For example, if the Java variable
$foo has the value bar at the time the template is requested,
bar replaces all instances of $foo on the web page. Alternatively, if I include the statement
#set( $foo = "bar" )
那麼所有的$foo同樣也會被替換。The output will be the same for all instances of $foo that follow this directive.
屬性Properties
VTL的另一種類型是屬性（properties），屬性都具有很明顯的格式。一個簡單的描述就是，屬性是以$開頭，跟着一個VTL標示符，接着是一個.號，然後是另一個VTL標示符。下面是VTL的合法的屬性的例子：The second flavor of VTL references are properties, and properties have a distinctive format. The shorthand notation consists of a leading
$ character followed a VTL Identifier, followed by a dot character (".") and another VTL Identifier. These are examples of valid property references in the VTL:
$customer.Address
$purchase.Total
第一個例子中，$customer.Address，能有兩個意思，第一，他能表示在一個引用hashtable的變量（$customer）中查找一個以Address作爲關鍵字(key)的值。；另外，這個屬性也能表示引用一個方法（關於方法將在下一個小節中介紹），$customer.Address是調用$customer.getAddress()方法的縮寫。當你的頁面被請求時，Velocity引擎會根據上下文判斷哪一種意思是最合理的，並且返回適當的值。Take the first example,
$customer.Address. It can have two meanings. It can mean, Look in the hashtable identified as
customer and return the value associated with the key Address. But
$customer.Address can also be referring to a method (references that refer to methods will be discussed in the next section);
$customer.Address could be an abbreviated way of writing $customer.getAddress(). When your page is requested, Velocity will determine which of these two possibilities makes sense, and then return the appropriate value.
方法Methods
方法是在Java代碼中定義的，能做一些有用的事情，比如計算或者確定某種決定。方法是在$符號之後，跟一個合法的標示符，後再跟一個方法體。一個合法的Velocity方法體是一個合法的VTL標示符，接着是一個（符號，然後是參數列表，最後是一個）符號。下面是一些合法的VTL方法引用的例子：A method is defined in the Java code and is capable of doing something useful, like running a calculation or arriving
at a decision. Methods are references that consist of a leading "$" character followed a VTL Identifier, followed by a VTL
Method Body. A VTL Method Body consists of a VTL Identifier followed by an left parenthesis character ("("), followed by an optional parameter list, followed by right parenthesis character (")"). These are examples of valid method references in the
VTL:
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
前面兩個例子---$customer.getAddress() --和 $purchase.getTotal()，_和上一小節中介紹屬性的例子看起來比較相似-----例如$customer.getAddress() 和 _$purchase.getTotal()。_如果你猜想他們之間存在着什麼聯繫，那你說對了。The first two examples -- _$customer.getAddress()
and $purchase.getTotal() -- may look similar to those used in the Properties section above,
$customer.Address and $purchase.Total. If you guessed that these examples must be related some in some fashion, you are correct!
VTL的屬性能作爲VTL的方法的一種簡寫。$customer.Address 的作用和_$customer.getAddress()_ 的作用其實是一樣的。通常情況下，在能夠使用屬性的時候我們建議使用屬性。在方法和屬性之間最大的區別就在於在調用方法的時候能夠向其中傳入一些參數。VTL Properties can be used as a shorthand notation for VTL Methods. The Property $customer.Address has the exact same effect as using the Method $customer.getAddress(). It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.
使用屬性的縮寫能代替下列的方法：The shorthand notation can be used for the following Methods
$sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()
我們希望有一個能返回太陽系的所有星球的名字的方法，一個能餵養我們的蚯蚓的方法，一個從相冊裏面得到一張照片的方法。下面的方法只能使用完整的方法來調用。We might expect these methods to return the names of planets belonging to the sun, feed our earthworm, or get a photograph from an album. Only the long notation works for the following
Methods.
$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## Can't pass a parameter list with $sun.Planets
$sisyphus.pushRock()
## Velocity assumes I mean $sisyphus.getRock()
$book.setTitle( "Homage to Catalonia" )
## Can't pass a parameter list
正規的引用格式Formal Reference Notation
關於引用的縮寫的例子在上面已經展示了，下面將列出幾個正規的引用的例子:Shorthand notation for references was used for the examples listed above, but there is also a formal notation for references, which is demonstrated below:
$
$
$
在通常情況下，我們會使用引用的縮寫方式，但在一些特定的情況下，我們必須使用引用的正規形式以保證模版能按照我們的想法正確的執行。In almost all cases you will use the shorthand notation for references, but in some cases the formal notation is required for correct processing.
設想你需要使用$vice作爲句子中的名詞中的一個來造個句子。目標是允許一個人選擇一個基礎的詞，例如造出下面兩個句子中的一個："Jack is a pyromaniac." or "Jack is a kleptomaniac."。如果在這種情況下使用引用的縮寫方式，就不能完成這個任務。考慮下面的例子：Suppose you were constructing a sentence on the fly where
$vice was to be used as the base word in the noun of a sentence. The goal is to allow someone to choose the base word and produce one of the two following results: "Jack is a pyromaniac." or "Jack is a kleptomaniac.". Using the shorthand notation would
be inadequate for this task. Consider the following example:
Jack is a $vicemaniac.
在這個語句中存在二義性，並且Velocity會認爲$vicemaniac會是變量，而不是我們希望的$vice。如果Velocity沒有找到$vicemaniac這個變量，則就直接會返回$vicemaniac這個值。使用正規的引用的寫法能避免這個問題。There is ambiguity here, and Velocity assumes that
$vicemaniac, not $vice, is the Identifier that you mean to use. Finding no value for
$vicemaniac, it will return $vicemaniac. Using formal notation can resolve this problem.
Jack is a $
maniac.
現在，Velocity就知道$vice纔是引用，而不是$vicemaniac。正規的引用的寫法通常在當引用直接和文本連接的時候使用。Now Velocity knows that
$vice, not $vicemaniac, is the reference. Formal notation is often useful when references are directly adjacent to text in a template.
靜態的引用寫法Quiet Reference Notation
當Velocity中引用指向了一個沒有定義的值的時候，通常的做法是直接返回這個引用。舉個例子：考慮下面的一段VTL語句。When Velocity encounters an undefined reference, its normal behavior is to output the image of the reference. For example, suppose the following reference appears as part of a VTL template.
<input type="text" name="email" value="$email"/>
當表單最開始加載的時候，變量$email並沒有被賦值，所以在頁面上顯示的email輸入框的位置裏會顯示出$email。但這個時候，你更願意在email的輸入框的位置顯示空白。使用靜態的引用格式，即使用$!email來代替$email，那麼在模版中上面的語句就會像下面這樣：When the form initially loads, the variable reference
$email has no value, but you prefer a blank text field to one with a value of "$email". Using the quiet reference notation circumvents Velocity's normal behavior; instead of using
$email in the VTL you would use $!email. So the above example would look like the following:
<input type="text" name="email" value="$!email"/>
現在，當表單第一次被加載的時候，即使$email引用並沒有被賦值，但這時候，在email的輸入框的位置上就顯示空白了，而不是之前的$email。Now when the form is initially loaded and
$email still has no value, an empty string will be output instead of "$email".
正規的和靜態的引用寫法能混合使用，下面是一個例子：Formal and quiet reference notation can be used together, as demonstrated below.
<input type="text" name="email" value="$!
"/>
Getting literal
VTL使用比如$,#的字符來驅動工作，所以，在你的模版中如果要使用這些字符，需要多加小心。這一小節要討論的就是去掉$的問題。VTL uses special characters, such as $ and #, to do its work, so some added care should be taken where using these characters in your templates. This section deals with escaping the $ character.
貨幣Currency
在使用"I bought a 4 lb. sack of potatoes at the farmer's market for only $2.50!"這類語句的時候，不會發生任何問題。正如前面介紹的，一個合法的VTL標示符是以一個大寫或小寫的字母開始的，所以，Velocity不會把$2.50當作一個引用處理。There is no problem writing "I bought a 4 lb. sack of potatoes at the farmer's market for only $2.50!"
As mentioned, a VTL identifier always begins with an upper- or lowercase letter, so $2.50 would not be mistaken for a reference.
Escaping Valid VTL References
潛在的一些情況會導致Velocity的二義性產生。使用反斜扛符是最好的去掉VTL的關鍵字符的方法。Cases may arise where there is the potential for Velocity to get confused.
Escaping special characters is the best way to handle VTL's special characters in your templates, and this can be done using the backslash ( __ ) character.
#set( $email = "foo" ) $email
如果Velocity在你的模版中遇到了比如$email這個引用，它就會搜索上下文中是否有該引用的正確的值。在這個例子中，模版會輸出foo，因爲$email被定義了。如果$email沒有定義，那麼就直接輸出$email。If Velocity encounters a reference in your VTL template to
$email, it will search the Context for a corresponding value. Here the output will be
foo, because $email is defined. If $email is not defined, the output will be
$email.
假設$email已經定義了（比如它的值就是foo），但是你就想要輸出$email。有許多的辦法能做到這一點，但最簡單的就是直接使用一個換碼符()。Suppose that $email is defined (for example, if it has the value foo), and that you want to output $email. There are a few ways of doing this, but the simplest is to use the escape character.
## The following line defines $email in this template: #set( $email = "foo" ) $email \$email
$email \\\$email
上面這個例子的輸出爲:renders as
foo $email \foo \$email
注意\符號是幫定在$符號的左邊。這個原則導致\\\$email被解析爲
$email。試比較下面的例子，下面的是如果$email沒有被賦值的情況。Note that the __ character bind to the _$_ from the left. The bind-from-left rule causes
\\\$email to render as
$email. Compare these examples to those in which $email is not defined.
$email \$email
$email \\\$email
則輸出爲：renders as
$email \$email
$email \\\$email
注意，Velocity在處理定義了值得引用和沒有定義值得引用的時候是不一樣的。下面的例子中，直接給$foo定義了一個值gibbous。Notice Velocity handles references that are defined differently from those that have not been defined. Here is a set directive that gives
$foo the value gibbous.
#set( $foo = "gibbous" ) $moon = $foo
該例子的輸出會是：$moon = gibbous。爲什麼會出現這樣的情況，因爲$moon是沒有定義的，而$foo將會被定義了的值：gibbous代替。The output will be:
$moon = gibbous -- where $moon is output as a literal because it is undefined and
gibbous is output in place of $foo.
這樣的方法同樣也能作用於VTL的指示符(#xxx),在關於指示符的一節裏，會更詳細的介紹這個問題。It is also possible to escape VTL directives; this is described in more detail in the Directives section.
寫法的替換Case Substitution
現在你也應該對引用有了一定的理解，可以開始比較有效的在你的模版中使用了。Velocity引用有一些更有用的特性使模版的設計者能更簡單的使用引用。比如：Now that you are familiar with references, you can begin to apply them effectively in your templates. Velocity references take advantage of some Java principles that template designers will find easy to use. For example:
$foo $foo.getBar() ## 等同於$foo.Bar
$data.getUser("jon") ## 等同於 $data.User("jon")
$data.getRequest().getServerName()
## 等同於 $data.Request.ServerName
## 等同於 $
這些例子說明了一些引用的可選的寫法。These examples illustrate alternative uses for the same references. Velocity takes advantage of Java's introspection and bean features to resolve the reference names to both objects in the Context as well as the objects methods. It is possible
to embed and evaluate references almost anywhere in your template.
Velocity建立在Sun的Bean標準之上的。該標準中的bean是大小寫敏感的，但是Velocity能捕捉到bean的異常，並最大程度的嘗試改正錯誤。當模版中使用$bar.foo來調用方法getFoo()，Velocity會先嚐試調用getfoo()方法，如果出現了錯誤，接着Velocity就會嘗試getFoo()方法。同樣的，如果模版引用的是$bar.Foo，那麼Velocity會首先嚐試調用getFoo()方法，然後是getfoo()。Velocity,
which is modelled on the Bean specifications defined by Sun Microsystems, is case sensitive; however, its developers have strove to catch and correct user errors wherever possible. When the method
getFoo() is referred to in a template by $bar.foo, Velocity will first try $getfoo. If this fails, it will then try $getFoo. Similarly, when a template refers to $bar.Foo, Velocity will try
$getFoo() first and then try getfoo().
注意：Velocity中不能引用對象的屬性。只有在JavaBean中定義了getter/setter方法的屬性能在Velocity得到處理。舉個例子，引用$foo.Name只能對應的是foo對象中的getName()或者setName()方法，而不是foo對象的name屬性。Note:
References to instance variables in a template are not resolved. Only references to the attribute equivalents of
JavaBean
getter/setter methods are resolved (i.e. $foo.Name does resolve to the class Foo's getName() instance method, but not to a public Name instance variable of Foo).
指示符Directives
引用允許模版設計者生成動態的內容，而指示符---極易使用的腳本元素，卻能更有效的控制輸出-----允許web頁面的設計者能真正的控制web站點的顯示內容。References allow template designers to generate dynamic content for web sites, while
directives -- easy to use script elements that can be used to creatively manipulate the output of Java code -- permit web designers to truly take charge of the appearance and content of the web site.
#set
#set指示符用來給一個引用賦值。可以給一個變量引用或者一個屬性引用賦值，賦值可以放在括號裏面。下面給出了一個示例。The #set directive is used for setting the value of a reference. A value can be assigned to either a variable reference or a property reference, and this occurs in brackets, as demonstrated:
#set( $primate = "monkey" )
#set( $customer.Behavior = $primate )
左操作數必須是一個變量引用或者一個屬性引用。右操作數可以是下列類型中的一種：The left hand side (LHS) of the assignment must be a variable reference or a property reference. The right hand side (RHS) can be one of the following types:
- 變量引用Variable reference
- 字符串String literal
- 屬性引用Property reference
- 方法引用Method reference
- 數值Number literal
- ArrayList
![]()
下面的每一個例子都示例了上面的類型：These examples demonstrate each of the aforementioned types:
#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
注意：在最後一個例子中，可以使用ArrayList的方法來操作[...]中定義的元素，即你可以使用$monkey.Say.get(0)來得到第一個元素。NOTE:
In the last example the elements defined with the [..] operator are accessible using the methods defined in the
ArrayList
class. So, for example, you could access the first element above using $monkey.Say.get(0).
右操作數也可以是一個普通的數學表達式：The RHS can also be a simple arithmetic expression:
#set( $value = $foo + 1 )
#set( $value = $bar - 1 )
#set( $value = $foo * $bar )
#set( $value = $foo / $bar )
如果右操作數是一個屬性或者方法的引用，如果這個引用的結果是一個null，那麼它不會被賦值給左操作數，按照這條規則，在上下文中就不能移出(remove)任何一個已經存在了的引用。這一點可能會讓一些Velocity的初學者感到困惑。舉個例子：If the RHS is a property or method reference that evaluates to
null, it will not be assigned to the LHS. It is not possible to remove an existing reference from the context via this mechanism. This can be confusing for newcomers to Velocity. For example:
#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,那麼上面的輸出會是：If
$query.criteria("name") returns the string "bill", and $query.criteria("address") returns
null, the above VTL will render as the following:
The result of the first query is bill
The result of the second query is bill
這也會導致在新手使用#foreach循環中使用#set給一個屬性或者方法引用賦值的時候不解。下面給出一個例子：This tends to confuse newcomers who construct
#foreach loops that attempt to #set a reference via a property or method reference, then immediately test that reference with an
#if directive. For example:
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
在上面的例子中，不能依賴使用#if來測試$result來判斷查詢是否成功。一旦$result被成功的賦值（添加到了上下文），就不能再把null賦給它了（移出上下文）。關於#if和#foreach將在下面的小節中做詳細介紹。In the above example, it would not be wise to rely on the evaluation of
$result to determine if a query was successful. After $result has been
#set (added to the context), it cannot be set back to null (removed from the context). The details of the
#if and #foreach directives are covered later in this document.
解決這個問題的一個辦法是預先把#result賦值爲false,如果$query.criteria()調用失敗，則你可以檢查了。One solution to this would be to pre-set $result to false. Then if the $query.criteria() call fails, you can check.
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
和其他的Velocity指示符不一樣，#set指示符不需要一個#end結尾。Unlike some of the other Velocity directives, the
#set directive does not have an #end statement.
字符串String Literals
當使用#set指示符時，只有包括在雙引號中的字符才能被解析並用於合成，如下所示：When using the #set directive, string literals that are enclosed in double quote characters will be parsed and rendered, as shown:
#set( $directoryRoot = "www" )
#set( $templateName = "index.vm" )
#set( $template = "$directoryRoot/$templateName" )
$template
輸出會是：The output will be
www/index.vm
但是，當字符被包含在單引號中，字符串就不能被解析了,如下所示：However, when the string literal is enclosed in single quote characters, it will not be parsed:
#set( $foo = "bar" ) $foo
#set( $blargh = '$foo' ) $blargh
bar
$foo
在默認的情況下，Velocity不會解析在單引號中包括的字符，但這也可以在velocity.properties文件中，通過修改stringliterals.interpolate=false來修改。By default, this feature of using single quotes to render unparsed text is available in Velocity. This default can be changed by editing velocity.properties
such that stringliterals.interpolate=false.
條件控制Conditionals
If / ElseIf
/ Else
#if指示符能夠有條件的顯示包含在if中的內容，如果if語句的值是true。比如：The #if directive in Velocity allows for text to be included when the web page is generated, on the conditional that the if statement is true. For example:
#if( $foo )
<strong>Velocity!</strong>
#end
變量$foo會被計算並檢查是否爲true，計算有兩中情況，1，如果foo是一個boolean(false/true)，則檢查其值是否爲true，2，檢查foo是否爲空（null）。記住，Velocity中只能保存對象，意味着我們在說boolean時，實際上指代的是Java中的Boolean類。如果方法返回的是boolean，自省功能仍然會把它轉換成相同值的Boolean。The variable
$foo is evaluated to determine whether it is true, which will happen under one of two circumstances:
$foo is a boolean (true/false) which has a true value, or (ii) the value is not null. Remember that the Velocity context only contains Objects, so when we say 'boolean', it will be represented as a Boolean (the class). This is true even for methods
that return boolean - the introspection infrastructure will return a Boolean of the same logical value.
如果計算的值爲true，包含在#if和#end之間的語句將會作爲輸出內容。在上面的例子中，如果$foo的值爲true,那麼輸出將會是"Velocity!"，如果是布爾值false，該語句計算得到爲false，則沒有任何輸出。The content between the #if and the #end statements become the output if the evaluation is true. In this case, if $foo is true, the output will be: "Velocity!". Conversely, if $foo has a null value, or if it is a boolean false, the statement evaluates as false, and there is no output.
#elseif或者#else語句能和一個#if語句一起使用。注意Velocity模版引擎會在第一個表達式爲true的時候停止，在下面的例子中，假設$foo的值爲15，$bar的值爲6：An #elseif or #else element can be used with an #if element. Note that the Velocity Templating Engine will stop at the first expression that is found to be true. In the following example, suppose that $foo has a value of 15 and $bar has a value of 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
在這個例子中，$foo大於10，所以前兩個表達式的結果爲false，下一個表達式比較$bar和6的值，結果爲true，所以輸出Go South。In this example,
$foo is greater than 10, so the first two comparisons fail. Next $bar is compared to 6, which is true, so the output is
Go South.
注意在這個例子中，如果Velocity的數值將會被轉成Integer，這時候，所有的計算結果都會爲false。唯一的例外是相等(==)，Velocity要求==兩邊的對象屬於同一個類。Please note that currently, Velocity's numeric comparisons are constrained to Integers - anything else will evaluate to false. The only exception to this is equality '==', where Velocity requires that the objects on each side of the '==' is of the same class.
關係和邏輯操作Relational and Logical Operators
Velocity使用相等操作符來判斷變量之間的關係。下面是一個演示使用等號的例子。Velocity uses the equivalent operator to determine the relationships between variables. Here is a simple example to illustrate how the equivalent operator is used.
#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
Velocity也具有邏輯AND,OR和NOT操作。請參見VTL
Reference Guide 來得到更多的信息。下面演示了一個使用AND，OR和NOT的例子：Velocity
has logical AND, OR and NOT operators as well. For further information, please see the VTL Reference Guide Below are examples demonstrating the use of the logical AND, OR and NOT operators.
## logical AND
#if( $foo && $bar )
<strong> This AND that</strong>
#end
只有$foo和$bar的結果都爲true的時候#if指示符的結果才爲true。如果$foo爲false，那麼表達式的值就是false,並且$bar的值不會再被計算。如果$foo爲true，Velocity模版引擎就會計算$bar的值，如果$bar也爲true，則表達式的值爲true，並且輸出This AND that。如果$bar爲false，因爲表達式的值就爲false，並且沒有輸出。The
#if() directive will only evaluate to true if both $foo and
$bar are true. If $foo is false, the expression will evaluate to false;
$bar will not be evaluated. If $foo is true, the Velocity Templating Engine will then check the value of
$bar; if $bar is true, then the entire expression is true and
This AND that becomes the output. If $bar is false, then there will be no output as the entire expression is false.
OR邏輯符同樣的工作。只要表達式中有一個引用的值爲true，則整個表達式的值就爲true。考慮下面的例子：Logical OR operators work the same way, except only one of the references need evaluate to true in order for the entire expression to be considered true. Consider the following example.
## logical OR
#if( $foo || $bar )
<strong>This OR That</strong>
#end
如果$foo是true，則Velocity模版引擎就不會再去計算$bar的值，不管$bar的值是true還是false,表達式的值都爲true，並且This OR That就是輸出了。但如果$foo爲false，那麼就要計算$bar的值了，如果$bar的值也爲false，那麼整個表達式的值就是false，並且沒有輸出。如果$bar爲true，那麼表達式的值就是true，並且輸出This OR That。If
$foo is true, the Velocity Templating Engine has no need to look at
$bar; whether $bar is true or false, the expression will be true, and
This OR That will be output. If $foo is false, however,
$bar must be checked. In this case, if $bar is also false, the expression evaluates to false and there is no output. On the other hand, if
$bar is true, then the entire expression is true, and the output is
This OR That
對於NOT操作符，就只需要一個參數：With logical NOT operators, there is only one argument :
##logical NOT
#if( !$foo )
<strong>NOT that</strong>
#end
在這個例子中，如果$foo爲true，那麼!$foo的值就爲false，並且沒有輸出。如果$foo的值爲false，那麼!$foo的值就爲true並且輸出NOT that。注意不要把NOT操作符和$!foo這兩個完全不同的東西相混淆。Here, the if
$foo is true, then !$foo evaluates to false, and there is no output. If
$foo is false, then !$foo evaluates to true and NOT that will be output. Be careful not to confuse this with the
quiet reference $!foo which is something altogether different.
遍歷Loops
Foreach Loop
#foreach元素允許遍歷操作，比如：The #foreach element allows for looping. For example:
<ul>
#foreach( $product in $allProducts )
<li>$product</li>
#end
</ul>
這個#foreach遍歷操作把$allProducts列表中的所有的prodect進行訪問。每一次遍歷，$allProducts中的一個元素就會放在$product變量中。This
#foreach loop causes the $allProducts list (the object) to be looped over for all of the products (targets) in the list. Each time through the loop, the value from
$allProducts is placed into the $product variable.
變量$allProducts的內容可以是一個Vector，Hashtable,或者一個Array。賦值給$product的值是一個Java對象，並能在循環中被引用。如果$product在Java中被定義爲一個Product類，那麼它的名字就可以使用$product.Name來引用得到。（或者使用$Product.getName()）The contents of the $allProducts variable is a Vector, a Hashtable or an Array. The value assigned to the $product variable is a Java Object and can be referenced from a variable as such. For example, if $product was really a Product class in Java, its name could be retrieved by referencing the $product.Name method (ie: $Product.getName()).
如果$allProducts是一個HashTable，如果你想根據key的值來遍歷得到該HashTable中的所有對象，則你可以象下面這樣編碼：Lets
say that $allProducts is a Hashtable. If you wanted to retrieve the key values for the Hashtable as well as the objects within the Hashtable, you can use code like this:
<ul>
#foreach( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key)</li>
#end
</ul>
Velocity同時也提供了一個簡單的方法來得到已經循環了的次數，那麼你就能象下面這樣做些有用的事情了：Velocity provides an easy way to get the loop counter so that you can do something like the following:
<table>
#foreach( $customer in $customerList )
<tr>
<td>$velocityCount</td>
<td>$customer.Name</td>
</tr>
#end
</table>
引用循環計數器的名字是在velocity.properties文件中使用$velocityCount指定的。在默認情況下，計數器是從1開始的，但你也能通過修改velocity.properties文件來選擇是從1開始還是從0開始。下面是關於配置循環計數器方面的配置片斷：The default name for the loop counter variable reference, which is specified in the velocity.properties file, is $velocityCount.
By default the counter starts at 1, but this can be set to either 0 or 1 in the velocity.properties file. Here's what the loop counter properties section of the velocity.properties file appears:
# 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
包含Include
#include腳本元素允許模版設計者在#include元素的位置包含進一個本地的文件。這個本地文件的內容會不經過Velocity引擎的解釋加入到模版文件中。考慮到安全的原因，被包含的文件只能放在TEMPLATE_ROOT文件夾下。The #include script element allows the template designer to import a local file, which is then inserted into the location where the #include directive is defined. The contents of the file are not rendered through the template engine. For security reasons, the file to be included may only be under TEMPLATE_ROOT.
#include( "one.txt" )
#include指示符所引用的文件需要包含在雙引號中。如果有多個文件需要被引入，則使用逗號分開。The file to which the #include directive refers is enclosed in quotes. If more than one file will be included, they should be separated by commas.
#include( "one.gif","two.txt","three.htm" )
需要被包含的文件不一定必須直接使用文件名，事實上，我們更傾向於使用一個變量引用而不是直接的文件名。這在需要根據提交請求來判斷需要引入哪個文件時很有用。下面是一個同時使用文件名和變量的例子：The file being included need not be referenced by name; in fact, it is often preferable to use a variable instead of a filename. This could be useful for targeting
output according to criteria determined when the page request is submitted. Here is an example showing both a filename and a variable.
#include( "greetings.txt", $seasonalstock )
解析Parse
#parse腳本元素允許模版設計者引入一個包含VTL的本地文件。Velocity會在將該文件包含的時候解析其中的VTL。The #parse script element allows the template designer to import a local file that contains VTL. Velocity will parse the VTL and render the template specified.
#parse( "me.vm" )
和#include指示符相似，#parse也可以使用一個變量來引入模版，並且所有的需要用#parse引入的模版文件同樣也都必須放在TEMPLATE_ROOT下。和#include不同，#parse只允許傳入一個參數。Like the
#include directive, #parse can take a variable rather than a template. Any templates to which
#parse refers must be included under TEMPLATE_ROOT. Unlike the #include directive,
#parse will only take a single argument.
VTL模版允許#parse包含進的模版也含有#parse語句。默認情況下，一個模版中只允許包含不超過10個#parse。這是在velocity.properties文件中的parse_directive.maxdepth 變量定義的。Velocity允許遞歸。比如，如果在模版dofoo.vm中包含了下面的代碼行：（注意，如果在velocity.properties文件中沒有包含parse_directive.maxdepth 屬性，則Velocity自動設置該值爲10。）VTL templates can have #parse statements referring to templates that in turn have #parse statements. By default set to 10, the parse_directive.maxdepth line of the velocity.properties allows users to customize maximum number of #parse referrals that can occur from a single template. (Note: If the parse_directive.maxdepth property is absent from the velocity.properties file, Velocity will set this default to 10.) Recursion is permitted, for example, if the template dofoo.vm contains the following lines:
Count down.
#set( $count = 8 )
#parse( "parsefoo.vm" )
All done with dofoo.vm!
這會引入一個parsefoo.vm模版，如果在該模版中包含下列VTL:It would reference the template parsefoo.vm, which might contain the following VTL:
$count
#set( $count = $count - 1 )
#if( $count > 0 )
#parse( "parsefoo.vm" )
#else All done with parsefoo.vm!
#end
在"Count down"顯示之後，Velocity會執行parsefoo.vm，從8開始倒計數，直到0，並會顯示"All down with dofoo.vm"消息。這時，執行點回到dofoo.vm中，並顯示"All done with dofoo.vm"。After "Count down." is displayed, Velocity passes through parsefoo.vm, counting down from 8. When the count reaches 0, it will
display the "All done with parsefoo.vm!" message. At this point, Velocity will return to dofoo.vm and output the "All done with dofoo.vm!" message.
停止Stop
#stop腳本元素允許模版設計者停止模版引擎的執行並返回。這對於調試很有用。The #stop script element allows the template designer to stop the execution of the template engine and return. This is useful for debugging purposes.
#stop
Velocity宏Velocimacros![]()
#macro腳本元素允許模版設計者定義一段可以重複使用的VTL片斷。不論簡單的還是複雜的情況，Velocity宏都很有用。作爲一個介紹Velocity宏的入門例子，下面的一段Velocity宏只有唯一的目的，就是減少打字的個數和可能發生的打字的錯誤。The #macro script element allows template designers to define a repeated segment of a VTL template. Velocimacros are very useful in a wide range of scenarios both simple and complex. This Velocimacro, created for the sole purpose of saving keystrokes and minimizing typographic errors, provides an introduction to the concept of Velocimacros.
#macro( d ) <tr><td></td></tr> #end
在這個例子中定義的宏的名字爲d，並且可以使用類似於其他的VTL指示符的使用格式來調用：The Velocimacro being defined in this example is
d, and it can be called in a manner analogous to any other VTL directive:
#d()
當這個模版被調用的時候，Velocity會使用一個空白的表格單元格來代替。When this template is called, Velocity would replace
#d() with a row containing a single, empty data cell.
一個Velocity的宏能夠包含零個（在上面這個例子中已經演示了）到任何個數的參數。但當Velocity宏在被調用的時候，調用的參數必須和這個宏在定義的時候定義的參數個數相同。當然，許多Velocity宏都比上面這個例子要複雜。下面是一個帶有兩個參數的Velocity宏的例子，一個顏色值，一個數組。A Velocimacro could take any number of arguments -- even zero arguments, as demonstrated in the first example, is an option -- but when the Velocimacro is invoked, it must be called with the same number of arguments with which it was defined. Many Velocimacros are more involved than the one defined above. Here is a Velocimacro that takes two arguments, a color and an array.
#macro( tablerows $color $somelist )
#foreach( $something in $somelist )
<tr><td bgcolor=$color>$something</td></tr>
#end
#end
這個叫做tablerows的Velocity宏帶有兩個參數。第一個參數代替了$color的位置，第二個參數代替了$somelist的位置。The Velocimacro being defined in this example,
tablerows, takes two arguments. The first argument takes the place of
$color, and the second argument takes the place of $somelist.
任何的能放入模版中的VTL，都能放在Velocity宏中。tablerows包含了一個foreach語句，並且有兩個#end語句。第一個數據#foreach，第二個結束了該Velocity宏的定義。Anything that can be put into a VTL template can go into the body of a Velocimacro. The tablerows Velocimacro is a foreach statement. There are two #end statements in the definition of the #tablerows Velocimacro; the first belongs to the #foreach, the second ends the Velocimacro definition.
#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
#tablerows( $color $greatlakes )
</table>
注意$greatlakes取代了$somelist。當這個#tablerows象上面的例子那樣調用，輸出爲：Notice that $greatlakes takes the place of
$somelist. When the #tablerows Velocimacro is called in this situation, the following output is generated:
<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>
Velocity宏可以定義在一個Velocity模版之內，但這是意味在同一應用的其他的模版中該宏是不可見的。定義一個能讓所有的模版都能使用的宏又很多的好處：能夠減少定義同一個Velocity宏的數量，減少了出錯的機率，並且保證了在一處的改變能應用到所有的模版中。Velocimacros can be defined
inline in a Velocity template, meaning that it is unavailable to other Velocity templates on the same web site. Defining a Velocimacro such that it can be shared by all templates has obvious advantages: it reduces the need to redefine the Velocimacro
on numerous templates, saving work and reducing the chance of error, and ensures that a single change to a macro available to more than one template.
如果#tablerows($color $list)定義在模版庫中，那麼這個宏就能在相似的所有的模版中使用了。它能被多次使用於不同的目標。在模版mushroom.vm中，調用#tablerows宏來列出一個典型的蘑菇房。Were the #tablerows($color $list) Velocimacro defined in a Velocimacros template library, this macro could be used on any of the regular templates. It could be used many times and for many different purposes. In the template mushroom.vm devoted to all things fungi, the #tablerows Velocimacro could be invoked to list the parts of a typical mushroom:
#set( $parts = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table> #tablerows( $cellbgcol $parts )
</table>
當完成了對mushroom.vm的請求，Velocity能在模版庫中找到#tablerows宏------需要把這個宏定義在velocity.properties文件中。該例子輸出爲：When fulfilling a request for mushroom.vm, Velocity would find the
#tablerows Velocimacro in the template library (defined in the velocity.properties file) and generate the following output:
<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>
Velocity宏中的參數Velocimacro Arguments
Velocity宏能有下列一些類型的VTL元素：Velocimacros can take as arguments any of the following VTL elements :
- 引用：Reference : anything that starts with '$'
- 字符串：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
當使用引用作爲參數傳遞給Velocity宏，請注意引用是按名字使用。意味着他們的值是在Velocity宏中每一次的引用都是重新生成的。這個特點允許你傳入一個對方法的引用，並且在宏中的每一次引用都調用該方法一次。作爲一個例子，下面的代碼展示了這一點：When passing references as arguments to Velocimacros, please note that references are passed 'by name'. This means that their value is 'generated' at each use inside the Velocimacro. This feature allows you to pass references with method calls and have the method called at each use. For example, when calling the following Velocimacro as shown
#macro( callme $a )
$a
$a
$a
#end
#callme( $foo.bar() )
在callme宏中，方法引用$foo.bar()實際上被調用了三次。results in the method bar() of the reference $foo being called 3 times.
初次接觸該特性，會感到一些驚訝，但當你比較深入的思考Velocity宏的最初的動機的時候------減少在VTL中對於重複代碼的剪切/複製操作。At first glance, this feature appears surprising, but when you take into consideration the original motivation behind Velocimacros -- to eliminate cut'n'paste duplication of commonly used VTL -- it makes sense. It allows you to do things like pass stateful objects, such as an object that generates colors in a repeating sequence for coloring table rows, into the Velocimacro.
如果你不需要這種特性，那麼你可以總是把方法的值傳遞給一個變量引用，再把該引用作爲參數傳遞給方法，如下面的例子所示：If you need to circumvent this feature, you can always just get the value from the method as a new reference and pass that :
#set( $myval = $foo.bar() )
#callme( $myval )
Velocity宏的屬性Velocimacro Properties
在velocity.properties文件中有幾行是用來控制Velocity的宏的。注意這部分在Developer Guide 中也有介紹。Several lines in the velocity.properties file allow for flexible implementation of Velocimacros. Note that these are also documented in the Developer Guide.
velocimacro.library------以逗號分隔開的Velocity宏模版庫的列表。默認情況下,Velocity只尋找VM_global_library.vm.這一個模版庫。配製的模版路徑用來尋找模版庫。A comma-separated list of all Velocimacro template libraries. By default, Velocity looks for a single library: VM_global_library.vm. The configured template path is used to find the Velocimacro libraries.
velocimacro.permissions.allow.inline------取值爲false或者true。該屬性用來規定宏是否能定義在模版中。默認值爲true，即允許模版設計者把宏直接定義在模版中。This property, which has possible values of true or false, determines whether Velocimacros can be defined in regular templates. The default, true, allows template designers to define Velocimacros in the templates themselves.
velocimacro.permissions.allow.inline.to.replace.global------取值爲true或者false。該屬性規定在模版中定義的宏是否能覆蓋在全局宏庫（velocimacro.library）中定義的宏。該屬性的默認值爲false，即阻止定義在模版中的宏覆蓋在引擎啓動時候加載的全局宏。 With possible values of true or false, this property allows the user to specify if a Velocimacro defined inline in a template can replace a globally defined template, one that was loaded on startup via the velocimacro.library property. The default, false, prevents Velocimacros defined inline in a template from replacing those defined in the template libraries loaded at startup.
velocimacro.permissions.allow.inline.local.scope - 取值爲true或者false。該屬性控制了在模版中定義的宏是否只對定義該宏的模版可見。This property, with possible values of true or false, defaulting to false, controls if Velocimacros defined inline are 'visible' only to the defining template. In other words, with this property set to true, a template can define inline VMs that are usable only by the defining template. You can use this for fancy VM tricks - if a global VM calls another global VM, with inline scope, 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.
velocimacro.context.localscope - This property has the possible values true or false, and the default is false. When true, any modifications to the context via #set() within a Velocimacro are considered 'local' to the Velocimacro, and will not permanently affect the context.
velocimacro.library.autoreload - This property controls Velocimacro library autoloading. The default value is false. When set to true the source Velocimacro library for an invoked Velocimacro will be checked for changes, and reloaded if necessary. This allows you to change and test Velocimacro libraries without having to restart your application or servlet container, just like you can with regular templates. This mode only works when caching is off in the resource loaders (e.g. file.resource.loader.cache = false ). This feature is intended for development, not for production.
Velocimacro Trivia
Currently, Velocimacros must be defined before they are first used in a template. This means that your #macro() declarations should come before using the Velocimacros.
This is important to remember if you try to #parse() a template containing inline #macro() directives. Because the #parse() happens at runtime, and the parser decides if a VM-looking element in the template is a VM at parsetime, #parse()-ing a set of VM declarations won't work as expected. To get around this, simply use the velocimacro.library facility to have Velocity load your VMs at startup.
去掉VTL指示符Escaping VTL Directives
VTL指示符可以使用反斜扛（\）來消去VTL指示符的意義，這點和消去VTL引用差不多。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" )
需要注意的就是那種需要多個指示符來完成任務的情況，比如if-else-end。下面是一個典型的VTL if語句。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
如果$jazz的值爲true，那麼輸出會是：If $jazz is true, the output is
Vyacheslav Ganelin
如果$jazz爲false，那麼沒有輸出。如果該指示符被消意，如下面所示：If $jazz is false, there is no output. Escaping script elements alters the output. Consider the following case:
#if( $jazz ) Vyacheslav Ganelin #end
那麼不管$jazz的值爲什麼，都會是下面的輸出：Whether $jazz is true or false, the output will be
#if($ jazz ) Vyacheslav Ganelin #end
事實上，因爲所有的腳本元素都被消意了，所以$jazz其實根本就沒有被計算。考慮下面的一個例子：In fact, because all script elements are escaped,
$jazz is never evaluated for it's boolean value. Suppose backslashes precede script elements that are legitimately escaped:
#if( $jazz )
Vyacheslav Ganelin
#end
在這種情況下，如果$jazz的值爲true，那麼輸出會是：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.
如果$jazz爲false，那麼會沒有輸出。注意如果腳本元素沒有正確的被消意，錯誤就將產生。If $jazz is false, there is no output. Note that things start to break if script elements are not properly escaped.
\\\#if( $jazz )
Vyacheslave Ganelin
#end
在這裏，#if被去掉了，但是#end仍然存在。象這樣的多餘的元素會導致解析錯誤。Here the #if is escaped, but there is an
#end remaining; having too many endings will cause a parsing error.
VTL：格式問題VTL: Formatting Issues
雖然在這個用戶指南中，使用了轉行和空格來顯示VTL代碼，但下面的VTL片段：Although VTL in this user guide is often displayed with newlines and whitespaces, the VTL shown below
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
$shogun #end
和下面的VTL片段都是合法的：is equally valid as the following snippet that Geir Magnusson Jr. posted to the Velocity user mailing list to illustrate a completely unrelated point:
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
Velocity的規則是跳過空格，前面的例子同樣可以象下面這樣寫：Velocity's behaviour is to gobble up excess whitespace. The preceding directive can be written as:
Send me
#set( $foo = ["$10 and ","a cake"] )
#foreach( $a in $foo )
$a
#end
please.
或者象下面這樣寫：or as
Send me
#set($foo = ["$10 and ","a cake"])
#foreach ($a in $foo )$a #end
please.
上面三種情況的輸出是一樣的。In each case the output will be the same.
其他的特性Other Features and Miscellany
數學問題Math
Velocity可以set指示符在模版中完成許多數學功能。下面的方程式展示了使用加減乘除的例子：Velocity has a handful of built-in mathematical functions that can be used in templates with the set directive. The following equations are examples of addition, subtraction, multiplication and division, respectively:
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
當使用除法做運算，結果會是integer。所有的餘數都可以使用取模運算得到。When a division operation is performed, the result will be an integer. Any remainder can be obtained by using the modulus (%) operator.
#set( $foo = $bar % 5 )
在Velocity中，數學公式中只能使用integer(...-2, -1, 0, 1, 2...)。當使用了一個非integer的值，日誌會紀錄這個錯誤並且返回null。Only integers (...-2, -1, 0, 1, 2...) are permissible when performing mathematical equations in Velocity; when a non-integer is used, it is logged and a null will be returned
as the output.
範圍操作Range Operator
範圍操作一般和#set還有#foreach聯合使用。作用在於創建一個integer對象的數組。範圍操作具有下面的格式：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]
其中，n和m必須是integer或者計算的值必須是integer。m大於或者小於n都無所謂，如果m小於n的話，該數組中的值就是下降的值序了。下面給出了一個使用範圍操作的例子：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]
注意，只有同#set和#foreach指示符一起使用，範圍操作纔有效的提供一個數組，如同上面的第四個例子所展示的一樣。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頁面設計者關注於提供一致的表格大小，但有時沒有足夠的信息來填滿表格空間的時候，範圍操作會是一個很有用的解決問題的途徑。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.
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
This renders as:
$!foo
$!
$!foo
$
!foo
Contrast this with regular escaping, where __ precedes _$_:
\$foo
\$!foo
\$!
$!
This renders as:
\$foo
\$!foo
\$!
\bar
Velocity宏的其他Velocimacro Miscellany
這一小節是灌關於Velocity宏的小型的FAQ。這一小節會不斷變化，所有，經常地來看看這一小節能得到更多新的信息。This section is a mini-FAQ on topics relating to Velocimacros. This section will change over time, so it's worth checking for new information from time to time.
注意，在這一小節中，Velocimacro（Velocity宏）都縮寫爲VM。Note : Throughout this section, 'Velocimacro' will commonly be abbreviated as 'VM'.
我能否使用一個指示符或者另外一個VM作爲一個VM的參數？Can I use a directive or another VM as an argument to a VM?
例子：Example : #center( #bold("hello") )
不行。一個指示符不是一個合法的參數，並且在更多的情況下，VM是一作爲一個指示符。No. A directive isn't a valid argument to a directive, and for most practical purposes, a VM is a directive.
不過，However..., 你可以象這樣做。一個簡單的解決該問題的方法是利用雙引號能合成其中的內容這一特點。你可以象下面這樣：there are things you can do. One easy solution is to take advantage of the fact that 'doublequote' (") renders it's contents. So you could do something like
#set($stuff = "#bold('hello')" )
#center( $stuff )
也可以省略一步：You can save a step...
#center( "#bold( 'hello' )" )
注意在後一個例子中，參數是在調用的宏裏面生成的，而不是在調用方法時就生成了。換句話說，就是說作爲參數傳入的VM實際上是在調用它的那個VM中生成的。看看下面這個例子：Please note that in the latter example the arg is evaluated
inside the VM, not at the calling level. In other words, the argument to the VM is passed in in its entirety and evaluated within the VM it was passed into. This allows you to do things like :
#macro( inner $foo )
inner : $foo
#end
#macro( outer $foo )
#set($bar = "outerlala")
outer : $foo
#end
#set($bar = 'calltimelala')
#outer( "#inner($bar)" )
輸出爲：Where the output is
Outer : inner : outerlala
因爲"#inner($bar)"的計算是發生在#outer()之內的。所以，在#outer()方法內對$bar賦的值纔是#inner()中真正用到的值。because the evaluation of the "#inner($bar)" happens inside #outer(), so the $bar value set inside #outer() is the one that's used.
這和之前介紹的參數是以名字傳入VM的特點是符合的。所以你才能象下面那樣調用：This is an intentional and jealously guarded feature - args are passed 'by name' into VMs, so you can hand VMs things like stateful references such as
#macro( foo $color )
<tr bgcolor=$color>
<td>Hi</td>
</tr>
<tr bgcolor=$color>
<td>There</td>
</tr>
#end
#foo( $bar.rowColor() )
在這裏，rowColor()就被重複的調用了，而不僅僅只有一次。要避免這個，可以在VM方法調用之外先計算出該方法的值，然後只將結果傳入VM：And have rowColor() called repeatedly, rather than just once. To avoid that, invoke the method outside of the VM, and pass the value into the VM.
#set($color = $bar.rowColor())
#foo( $color )
能通過#parse()來註冊一個Velocity宏嗎？Can I register Velocimacros via #parse() ? 當前，要在模版中使用宏，必須確保該宏在使用之前是定義了的。這意味着#macro定義一個宏必須在使用該宏之前。Currently, Velocimacros must be defined before they are first used in a template. This means that your #macro() declarations
should come before using the Velocimacros.
這一點在你試圖#parse一個帶有#macro的模版時需要記住的。因爲#parse發生在運行期間，並且解析器才判斷一個類似VM的元素是一個VM，這時候，#parse就不會起作用了。避免這個問題，只需要砸velocity.properties文件中定義需要在啓動時加載的宏庫就可以了。This is important to remember if you try to #parse() a template containing inline #macro() directives. Because the #parse() happens at runtime, and the parser decides if a VM-looking element in the template is a VM at parsetime, #parse()-ing a set of VM declarations won't work as expected. To get around this, simply use the velocimacro.library facility to have Velocity load your VMs at startup.
什麼是Velocity的自動重加載？What is Velocimacro Autoreloading?
在開發期間，可以使用velocity.properties中的一個參數：There is a property, meant to be used in
development, not production :
velocimacro.library.autoreload
該參數默認爲false。當把該值設置爲true並且下面這個屬性：which defaults to false. When set to true along with
<type>.resource.loader.cache = false
(<type>是你使用的資源加載器，比如file）象這樣設置後，當你對Velocity宏庫做了一些改動後，Velocity引擎會自動地重新加載他們，所以，你就不需要手動地去重起你的servlet引擎或者應用了。where <type> is the name of the resource loader that you are using, such as 'file') then the Velocity engine will automatically reload changes to your Velocimacro library files when you make them, so you do not have to dump the servlet engine (or application) or do other tricks to have your Velocimacros reloaded.
下面是一個典型的對自動重加載做的配置：Here is what a simple set of configuration properties would look like.
file.resource.loader.path = templates file.resource.loader.cache = false velocimacro.library.autoreload = true
記住，在產品中不要這樣使用。Don't keep this on in production.
字符串連接String Concatenation
開發者問得比較多的一個問題就是字符串時怎麼連接的？是和在Java中使用+號相似的嗎？A common question that developers ask is How do I do String concatenation? Is there any analogue to the '+' operator in Java?.
在VTL中要串連引用，你自需要把他們放在一起就行了。對將他們放在一起的環境沒有特別的要求，下面就舉幾個例子來演示：To do concatenation of references in VTL, you just have to 'put them together'. The context of where you want to put them together does matter, so we will illustrate with some examples.
In the regular 'schmoo' of a template (when you are mixing it in with regular content) :
#set( $size = "Big" )
#set( $name = "Ben" )
The clock is $size$name.
輸出會是'The clock is BigBen'。一個更有趣的例子，比如你想要把一個連接後的字符串傳遞給一個方法調用，或者賦值給一個新的引用，只需要：and
the output will render as 'The clock is BigBen'.
For more interesting cases, such as when you want to concatenate strings to pass to a method, or to set a new reference, just do
#set( $size = "Big" )
#set( $name = "Ben" )
#set($clock = "$size$name" )
The clock is $clock.
該段代碼和上一個例子有同樣的輸出。最後一個例子，當你想把字符串引用和字符串複合起來使用，你需要使用正規的引用：Which will result in the same output. As a final example, when you want to mix in 'static' strings with your references, you may need to use 'formal references' :
#set( $size = "Big" )
#set( $name = "Ben" )
#set($clock = "$
Tall$name" )
The clock is $clock.
現在，輸出爲'The clockis BigTalBenl'。前面已經介紹過，正規的引用告訴解析器你的引用是$size而不是$sizeTall。Now
the output is 'The clockis BigTalBenl'.
The formal notation is needed so the parser knows you mean to use the reference '$size' versus '$sizeTall' which it would if the '{}' weren't there.