目錄
- 關(guān)于本指南
- 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
- 標(biāo)識符Directives
- Set
- 字符串常量String Literals
- 條件語句If-Else Statements
- Relational and Logical Operators
- foreach循環(huán)Foreach Loops
- 包含Include
- 解析Parse
- 停止Stop
- 宏Velocimacros
- Escaping VTL Directives
- VTL: Formatting Issues
- Other Features and Miscellany
- 數(shù)學(xué)Math
- 范圍操作符Range Operator
- 高級特性Advanced Issues: Escaping and !
- Velocimacro Miscellany
- 字符串聯(lián)String Concatenation
- 反饋Feedback
關(guān)于這個(gè)指南About this Guide
這個(gè)用戶指南目的在于幫助頁面設(shè)計(jì)人員和內(nèi)容提供者掌握簡單但強(qiáng)大的Velocity和其模版語言（VTL）的語法。在本指南中的許多例子主要演示的是在Web頁面中嵌入動(dòng)態(tài)的內(nèi)容，但所有的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是一個(gè)基于Java的模版引擎。他允許使用者通過簡單而強(qiáng)大的模版語言引用Java代碼中定義的對象。在MVC的開發(fā)模式下，Web設(shè)計(jì)者和Java程序員可以并行的開發(fā)web站點(diǎn)，意味著web頁面的設(shè)計(jì)者能專注于站點(diǎn)的樣式而程序員能專注于書寫高質(zhì)量的代碼。Velocity將Java
代碼和web頁面分開了，確保了站點(diǎn)在整個(gè)生命周期中更容易維護(hù)。較之JSP和PHP，提供了一種更有生命力的開發(fā)方式。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可以單獨(dú)的用來作為生成代碼和報(bào)告的工具，也可以作為一個(gè)組件集成到其他的系統(tǒng)中來作為一個(gè)MVC框架的視圖引擎工廠。比如Web應(yīng)用框架Turbine就是使用Velocity作模版生成服務(wù)。Velocity+Turbine能提供一個(gè)支持模版服務(wù)的真正的MVC開發(fā)模型。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
設(shè)想下你是一個(gè)頁面設(shè)計(jì)者，現(xiàn)在在為一個(gè)泥土商店設(shè)計(jì)一個(gè)在線的銷售商店。我們就叫這個(gè)網(wǎng)上商店叫"在線泥土商店-.-!"。事業(yè)欣欣向榮，客戶們紛紛訂購不同類型和數(shù)量的泥土。客戶使用用戶名和密碼登陸你的站點(diǎn)，察看他們的訂單，購買更多的泥土。現(xiàn)在，流行的陶土也在線銷售。一小部分用戶有規(guī)律的購買亮紅色的泥土，但這種泥土不是很流行，往往也只能出現(xiàn)在頁面的靠邊的地方。每個(gè)用戶的信息都記錄在數(shù)據(jù)庫中，現(xiàn)在問題就出來了，為什么不使用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能很簡單的讓你的在線用戶定制不同的頁面。作為一個(gè)站點(diǎn)的設(shè)計(jì)者，你希望用戶在登陸過后能看到他們希望看到的頁面。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引用來保存當(dāng)前登陸的用戶的信息，使用$mudsOnSpecial引用來保存當(dāng)前正在出售的所有泥土的種類，使用$flogger對象來提供和促銷相關(guān)的方法。目前，我們先關(guān)注這三個(gè)引用對象。注意，你不需要關(guān)注數(shù)據(jù)是怎樣從數(shù)據(jù)庫中得到的，你只需要知道數(shù)據(jù)都能正確地得到。這種觀念能讓你專注于你的頁面工作，而其余的事情都交給軟件工程師來做。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>
關(guān)于foreach 語句的更詳細(xì)的描述將在下面的文檔中出現(xiàn)，目前來說，這段代碼確實(shí)能包含在你的頁面中并正確地工作。當(dāng)一個(gè)關(guān)注亮紅泥的客戶登陸到站點(diǎn)，并且亮紅泥正在銷售中，將在最顯著的位置顯示出來。當(dāng)另一個(gè)關(guān)注陶土的客戶登陸到站點(diǎn)，如果陶土正在銷售，那么該客戶將在最顯著的位置發(fā)現(xiàn)陶土的銷售信息。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元素，這些元素共同的工作，提供給你強(qiáng)大的功能和足夠的靈活性。當(dāng)你熟悉了這些元素，你會逐漸釋放Velocity的強(qiáng)大力量。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模版語言旨在于提供一個(gè)簡單、普通、清晰的方式來把動(dòng)態(tài)的內(nèi)容合并到Web頁面中。即便是一個(gè)只具有一點(diǎn)甚至沒有編程經(jīng)驗(yàn)的頁面設(shè)計(jì)者，都能迅速的掌握VTL并合理的使用到web站點(diǎn)的設(shè)計(jì)中。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）來將動(dòng)態(tài)的內(nèi)容嵌入到web站點(diǎn)中。變量僅僅是引用中的一種，它能引用在Java代碼中定義的一些對象，并能獲得在web頁面中為它賦的值。下面是一個(gè)能直接嵌入到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語句一樣，在這個(gè)VTL語句中使用#符號開頭，并且包含一個(gè)指示符（directive）:set。當(dāng)一個(gè)在線的訪問者請求這個(gè)web頁面，Velocity模版引擎會搜索你的web頁面，并找到所有的#符號，當(dāng)確定#之后的是一個(gè)Velocity語句，則處理。對于Velocity來說，#并沒有實(shí)際的意義，只是表明之后是一個(gè)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.
在#之后跟一個(gè)指示符，set。set指示符使用一個(gè)表達(dá)式（包含在一個(gè)括號里）------一個(gè)等號(=)來把一個(gè)值賦給一個(gè)變量。變量都是列在左邊，值放在右邊；兩者使用=分開。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中，不存在數(shù)據(jù)類型的混亂的情況，因?yàn)橹挥凶址ㄎ谋拘畔ⅲ┠軌蛸x值給變量。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.
下面的規(guī)則能讓你更好的理解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 用來給一個(gè)變量賦值。在模版中，變量$a能夠輸出一個(gè)"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!
當(dāng)一個(gè)變量被賦予了一個(gè)值，你可以在你的HTML文檔中的任何位置使用這個(gè)引用。在下面的例子中，首先給變量$foo賦了一個(gè)值，并在之后被引用。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>
該頁面的結(jié)果是在web頁面上顯示出"Hello Velocity World！"。The result is a web page that prints "Hello Velocity World!".
為了讓VTL在頁面中更容易閱讀，我們建議你在每一句VTL語句都新起一行，但這并不是必須的。關(guān)于set指示符，我們在后面會再次仔細(xì)的介紹。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的意思或者其他需要注意的地方。下面是一個(gè)注釋的例子：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.
單行的注釋以##開頭并且在該行的結(jié)束即結(jié)束。如果你需要注釋一段話，那么，你沒有必要把每一行都注釋成單行的注釋。使用以#*開頭，以*#結(jié)束的一段話能提供多行的注釋功能。如下面的例子：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備注塊。這個(gè)備注塊用來保存諸如文檔作者，文檔版本等信息。下面是一個(gè)例子：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中有三種類型的引用：變量，屬性和方法。作為一個(gè)使用VTL的設(shè)計(jì)者，你必須和你的軟件工程師（程序員）在引用的名字上達(dá)成一致的標(biāo)準(zhǔn)，才能正確地在頁面中使用。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.
所有的引用對象都作為一個(gè)字符串對象使用。比如$foo引用指向的是一個(gè)不是String的對象（比如一個(gè)Integer對象），那么在Velocity引擎處理時(shí)，使用的該對象的.toString()方法來將該對象轉(zhuǎn)成字符串。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
簡單說變量就是以$開頭，后跟一個(gè)合法的VTL標(biāo)示符。一個(gè)合法的VTL標(biāo)示符是以一個(gè)字符開頭，后跟下列字符：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)
- 數(shù)字numeric (0 .. 9)
- 連接符hyphen ("-")
- 下劃線underscore ("_")
下面是一些合法的VTL變量的例子：Here are some examples of valid variable references in the VTL:
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
當(dāng)VTL引用了一個(gè)變量，比如$foo，則該變量能從set語句中，或者從Java代碼中得到值。比如一個(gè)Java變量$foo擁有一個(gè)bar的值，則當(dāng)模版被請求的時(shí)候，bar這個(gè)值會代替頁面中所有的$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），屬性都具有很明顯的格式。一個(gè)簡單的描述就是，屬性是以$開頭，跟著一個(gè)VTL標(biāo)示符，接著是一個(gè).號，然后是另一個(gè)VTL標(biāo)示符。下面是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
第一個(gè)例子中，$customer.Address，能有兩個(gè)意思，第一，他能表示在一個(gè)引用hashtable的變量（$customer）中查找一個(gè)以Address作為關(guān)鍵字(key)的值。；另外，這個(gè)屬性也能表示引用一個(gè)方法（關(guān)于方法將在下一個(gè)小節(jié)中介紹），$customer.Address是調(diào)用$customer.getAddress()方法的縮寫。當(dāng)你的頁面被請求時(shí)，Velocity引擎會根據(jù)上下文判斷哪一種意思是最合理的，并且返回適當(dāng)?shù)闹怠ake 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代碼中定義的，能做一些有用的事情，比如計(jì)算或者確定某種決定。方法是在$符號之后，跟一個(gè)合法的標(biāo)示符，后再跟一個(gè)方法體。一個(gè)合法的Velocity方法體是一個(gè)合法的VTL標(biāo)示符，接著是一個(gè)（符號，然后是參數(shù)列表，最后是一個(gè)）符號。下面是一些合法的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"] )
前面兩個(gè)例子---$customer.getAddress() --和 $purchase.getTotal()，_和上一小節(jié)中介紹屬性的例子看起來比較相似-----例如$customer.getAddress() 和 _$purchase.getTotal()。_如果你猜想他們之間存在著什么聯(lián)系，那你說對了。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()_ 的作用其實(shí)是一樣的。通常情況下，在能夠使用屬性的時(shí)候我們建議使用屬性。在方法和屬性之間最大的區(qū)別就在于在調(diào)用方法的時(shí)候能夠向其中傳入一些參數(shù)。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()
我們希望有一個(gè)能返回太陽系的所有星球的名字的方法，一個(gè)能喂養(yǎng)我們的蚯蚓的方法，一個(gè)從相冊里面得到一張照片的方法。下面的方法只能使用完整的方法來調(diào)用。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
正規(guī)的引用格式Formal Reference Notation
關(guān)于引用的縮寫的例子在上面已經(jīng)展示了，下面將列出幾個(gè)正規(guī)的引用的例子:Shorthand notation for references was used for the examples listed above, but there is also a formal notation for references, which is demonstrated below:
$
Unknown macro: {mudSlinger}
$
Unknown macro: {customer.Address}
$
Unknown macro: {purchase.getTotal()}
在通常情況下，我們會使用引用的縮寫方式，但在一些特定的情況下，我們必須使用引用的正規(guī)形式以保證模版能按照我們的想法正確的執(zhí)行。In almost all cases you will use the shorthand notation for references, but in some cases the formal notation is required for correct processing.
設(shè)想你需要使用$vice作為句子中的名詞中的一個(gè)來造個(gè)句子。目標(biāo)是允許一個(gè)人選擇一個(gè)基礎(chǔ)的詞，例如造出下面兩個(gè)句子中的一個(gè)："Jack is a pyromaniac." or "Jack is a kleptomaniac."。如果在這種情況下使用引用的縮寫方式，就不能完成這個(gè)任務(wù)。考慮下面的例子：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.
在這個(gè)語句中存在二義性，并且Velocity會認(rèn)為$vicemaniac會是變量，而不是我們希望的$vice。如果Velocity沒有找到$vicemaniac這個(gè)變量，則就直接會返回$vicemaniac這個(gè)值。使用正規(guī)的引用的寫法能避免這個(gè)問題。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 $
Unknown macro: {vice}
maniac.
現(xiàn)在，Velocity就知道$vice才是引用，而不是$vicemaniac。正規(guī)的引用的寫法通常在當(dāng)引用直接和文本連接的時(shí)候使用。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.
靜態(tài)的引用寫法Quiet Reference Notation
當(dāng)Velocity中引用指向了一個(gè)沒有定義的值的時(shí)候，通常的做法是直接返回這個(gè)引用。舉個(gè)例子：考慮下面的一段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"/>
當(dāng)表單最開始加載的時(shí)候，變量$email并沒有被賦值，所以在頁面上顯示的email輸入框的位置里會顯示出$email。但這個(gè)時(shí)候，你更愿意在email的輸入框的位置顯示空白。使用靜態(tài)的引用格式，即使用$!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"/>
現(xiàn)在，當(dāng)表單第一次被加載的時(shí)候，即使$email引用并沒有被賦值，但這時(shí)候，在email的輸入框的位置上就顯示空白了，而不是之前的$email。Now when the form is initially loaded and $email still has no value, an empty string will be output instead of "$email".
正規(guī)的和靜態(tài)的引用寫法能混合使用，下面是一個(gè)例子：Formal and quiet reference notation can be used together, as demonstrated below.
<input type="text" name="email" value="$!
Unknown macro: {email}
"/>
Getting literal
VTL使用比如$,#的字符來驅(qū)動(dòng)工作，所以，在你的模版中如果要使用這些字符，需要多加小心。這一小節(jié)要討論的就是去掉$的問題。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!"這類語句的時(shí)候，不會發(fā)生任何問題。正如前面介紹的，一個(gè)合法的VTL標(biāo)示符是以一個(gè)大寫或小寫的字母開始的，所以，Velocity不會把$2.50當(dāng)作一個(gè)引用處理。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
潛在的一些情況會導(dǎo)致Velocity的二義性產(chǎn)生。使用反斜扛符是最好的去掉VTL的關(guān)鍵字符的方法。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這個(gè)引用，它就會搜索上下文中是否有該引用的正確的值。在這個(gè)例子中，模版會輸出foo，因?yàn)?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.
假設(shè)$email已經(jīng)定義了（比如它的值就是foo），但是你就想要輸出$email。有許多的辦法能做到這一點(diǎn)，但最簡單的就是直接使用一個(gè)換碼符()。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
上面這個(gè)例子的輸出為:renders as
foo $email \foo \$email
注意\符號是幫定在$符號的左邊。這個(gè)原則導(dǎo)致\\\$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在處理定義了值得引用和沒有定義值得引用的時(shí)候是不一樣的。下面的例子中，直接給$foo定義了一個(gè)值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。為什么會出現(xiàn)這樣的情況，因?yàn)?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),在關(guān)于指示符的一節(jié)里，會更詳細(xì)的介紹這個(gè)問題。It is also possible to escape VTL directives; this is described in more detail in the Directives section.
寫法的替換Case Substitution
現(xiàn)在你也應(yīng)該對引用有了一定的理解，可以開始比較有效的在你的模版中使用了。Velocity引用有一些更有用的特性使模版的設(shè)計(jì)者能更簡單的使用引用。比如：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
## 等同于 $
Unknown macro: {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標(biāo)準(zhǔn)之上的。該標(biāo)準(zhǔn)中的bean是大小寫敏感的，但是Velocity能捕捉到bean的異常，并最大程度的嘗試改正錯(cuò)誤。當(dāng)模版中使用$bar.foo來調(diào)用方法getFoo()，Velocity會先嘗試調(diào)用getfoo()方法，如果出現(xiàn)了錯(cuò)誤，接著Velocity就會嘗試getFoo()方法。同樣的，如果模版引用的是$bar.Foo，那么Velocity會首先嘗試調(diào)用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得到處理。舉個(gè)例子，引用$foo.Name只能對應(yīng)的是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
引用允許模版設(shè)計(jì)者生成動(dòng)態(tài)的內(nèi)容，而指示符---極易使用的腳本元素，卻能更有效的控制輸出-----允許web頁面的設(shè)計(jì)者能真正的控制web站點(diǎn)的顯示內(nèi)容。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指示符用來給一個(gè)引用賦值。可以給一個(gè)變量引用或者一個(gè)屬性引用賦值，賦值可以放在括號里面。下面給出了一個(gè)示例。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 )
左操作數(shù)必須是一個(gè)變量引用或者一個(gè)屬性引用。右操作數(shù)可以是下列類型中的一種：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
- 數(shù)值Number literal
- ArrayList
下面的每一個(gè)例子都示例了上面的類型：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 )
## 數(shù)值 number literal
#set( $monkey.Say = ["Not", $my, "fault"] )
## ArrayList
注意：在最后一個(gè)例子中，可以使用ArrayList的方法來操作[...]中定義的元素，即你可以使用$monkey.Say.get(0)來得到第一個(gè)元素。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).
右操作數(shù)也可以是一個(gè)普通的數(shù)學(xué)表達(dá)式：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 )
如果右操作數(shù)是一個(gè)屬性或者方法的引用，如果這個(gè)引用的結(jié)果是一個(gè)null，那么它不會被賦值給左操作數(shù)，按照這條規(guī)則，在上下文中就不能移出(remove)任何一個(gè)已經(jīng)存在了的引用。這一點(diǎn)可能會讓一些Velocity的初學(xué)者感到困惑。舉個(gè)例子：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
這也會導(dǎo)致在新手使用#foreach循環(huán)中使用#set給一個(gè)屬性或者方法引用賦值的時(shí)候不解。下面給出一個(gè)例子：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賦給它了（移出上下文）。關(guān)于#if和#foreach將在下面的小節(jié)中做詳細(xì)介紹。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.
解決這個(gè)問題的一個(gè)辦法是預(yù)先把#result賦值為false,如果$query.criteria()調(diào)用失敗，則你可以檢查了。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指示符不需要一個(gè)#end結(jié)尾。Unlike some of the other Velocity directives, the #set directive does not have an #end statement.
字符串String Literals
當(dāng)使用#set指示符時(shí)，只有包括在雙引號中的字符才能被解析并用于合成，如下所示：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
但是，當(dāng)字符被包含在單引號中，字符串就不能被解析了,如下所示：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
在默認(rèn)的情況下，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中的內(nèi)容，如果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會被計(jì)算并檢查是否為true，計(jì)算有兩中情況，1，如果foo是一個(gè)boolean(false/true)，則檢查其值是否為true，2，檢查foo是否為空（null）。記住，Velocity中只能保存對象，意味著我們在說boolean時(shí)，實(shí)際上指代的是Java中的Boolean類。如果方法返回的是boolean，自省功能仍然會把它轉(zhuǎn)換成相同值的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.
如果計(jì)算的值為true，包含在#if和#end之間的語句將會作為輸出內(nèi)容。在上面的例子中，如果$foo的值為true,那么輸出將會是"Velocity!"，如果是布爾值false，該語句計(jì)算得到為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語句能和一個(gè)#if語句一起使用。注意Velocity模版引擎會在第一個(gè)表達(dá)式為true的時(shí)候停止，在下面的例子中，假設(shè)$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
在這個(gè)例子中，$foo大于10，所以前兩個(gè)表達(dá)式的結(jié)果為false，下一個(gè)表達(dá)式比較$bar和6的值，結(jié)果為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.
注意在這個(gè)例子中，如果Velocity的數(shù)值將會被轉(zhuǎn)成Integer，這時(shí)候，所有的計(jì)算結(jié)果都會為false。唯一的例外是相等(==)，Velocity要求==兩邊的對象屬于同一個(gè)類。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.
關(guān)系和邏輯操作Relational and Logical Operators
Velocity使用相等操作符來判斷變量之間的關(guān)系。下面是一個(gè)演示使用等號的例子。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 來得到更多的信息。下面演示了一個(gè)使用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的結(jié)果都為true的時(shí)候#if指示符的結(jié)果才為true。如果$foo為false，那么表達(dá)式的值就是false,并且$bar的值不會再被計(jì)算。如果$foo為true，Velocity模版引擎就會計(jì)算$bar的值，如果$bar也為true，則表達(dá)式的值為true，并且輸出This AND that。如果$bar為false，因?yàn)楸磉_(dá)式的值就為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邏輯符同樣的工作。只要表達(dá)式中有一個(gè)引用的值為true，則整個(gè)表達(dá)式的值就為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模版引擎就不會再去計(jì)算$bar的值，不管$bar的值是true還是false,表達(dá)式的值都為true，并且This OR That就是輸出了。但如果$foo為false，那么就要計(jì)算$bar的值了，如果$bar的值也為false，那么整個(gè)表達(dá)式的值就是false，并且沒有輸出。如果$bar為true，那么表達(dá)式的值就是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操作符，就只需要一個(gè)參數(shù)：With logical NOT operators, there is only one argument :
##logical NOT
#if( !$foo )
<strong>NOT that</strong>
#end
在這個(gè)例子中，如果$foo為true，那么!$foo的值就為false，并且沒有輸出。如果$foo的值為false，那么!$foo的值就為true并且輸出NOT that。注意不要把NOT操作符和$!foo這兩個(gè)完全不同的東西相混淆。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>
這個(gè)#foreach遍歷操作把$allProducts列表中的所有的prodect進(jìn)行訪問。每一次遍歷，$allProducts中的一個(gè)元素就會放在$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的內(nèi)容可以是一個(gè)Vector，Hashtable,或者一個(gè)Array。賦值給$product的值是一個(gè)Java對象，并能在循環(huán)中被引用。如果$product在Java中被定義為一個(gè)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是一個(gè)HashTable，如果你想根據(jù)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同時(shí)也提供了一個(gè)簡單的方法來得到已經(jīng)循環(huán)了的次數(shù)，那么你就能象下面這樣做些有用的事情了：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>
引用循環(huán)計(jì)數(shù)器的名字是在velocity.properties文件中使用$velocityCount指定的。在默認(rèn)情況下，計(jì)數(shù)器是從1開始的，但你也能通過修改velocity.properties文件來選擇是從1開始還是從0開始。下面是關(guān)于配置循環(huán)計(jì)數(shù)器方面的配置片斷：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腳本元素允許模版設(shè)計(jì)者在#include元素的位置包含進(jìn)一個(gè)本地的文件。這個(gè)本地文件的內(nèi)容會不經(jīng)過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指示符所引用的文件需要包含在雙引號中。如果有多個(gè)文件需要被引入，則使用逗號分開。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" )
需要被包含的文件不一定必須直接使用文件名，事實(shí)上，我們更傾向于使用一個(gè)變量引用而不是直接的文件名。這在需要根據(jù)提交請求來判斷需要引入哪個(gè)文件時(shí)很有用。下面是一個(gè)同時(shí)使用文件名和變量的例子：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腳本元素允許模版設(shè)計(jì)者引入一個(gè)包含VTL的本地文件。Velocity會在將該文件包含的時(shí)候解析其中的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也可以使用一個(gè)變量來引入模版，并且所有的需要用#parse引入的模版文件同樣也都必須放在TEMPLATE_ROOT下。和#include不同，#parse只允許傳入一個(gè)參數(shù)。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包含進(jìn)的模版也含有#parse語句。默認(rèn)情況下，一個(gè)模版中只允許包含不超過10個(gè)#parse。這是在velocity.properties文件中的parse_directive.maxdepth 變量定義的。Velocity允許遞歸。比如，如果在模版dofoo.vm中包含了下面的代碼行：（注意，如果在velocity.properties文件中沒有包含parse_directive.maxdepth 屬性，則Velocity自動(dòng)設(shè)置該值為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!
這會引入一個(gè)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會執(zhí)行parsefoo.vm，從8開始倒計(jì)數(shù)，直到0，并會顯示"All down with dofoo.vm"消息。這時(shí)，執(zhí)行點(diǎn)回到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腳本元素允許模版設(shè)計(jì)者停止模版引擎的執(zhí)行并返回。這對于調(diào)試很有用。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
#macro腳本元素允許模版設(shè)計(jì)者定義一段可以重復(fù)使用的VTL片斷。不論簡單的還是復(fù)雜的情況，Velocity宏都很有用。作為一個(gè)介紹Velocity宏的入門例子，下面的一段Velocity宏只有唯一的目的，就是減少打字的個(gè)數(shù)和可能發(fā)生的打字的錯(cuò)誤。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
在這個(gè)例子中定義的宏的名字為d，并且可以使用類似于其他的VTL指示符的使用格式來調(diào)用：The Velocimacro being defined in this example is d, and it can be called in a manner analogous to any other VTL directive:
#d()
當(dāng)這個(gè)模版被調(diào)用的時(shí)候，Velocity會使用一個(gè)空白的表格單元格來代替。When this template is called, Velocity would replace #d() with a row containing a single, empty data cell.
一個(gè)Velocity的宏能夠包含零個(gè)（在上面這個(gè)例子中已經(jīng)演示了）到任何個(gè)數(shù)的參數(shù)。但當(dāng)Velocity宏在被調(diào)用的時(shí)候，調(diào)用的參數(shù)必須和這個(gè)宏在定義的時(shí)候定義的參數(shù)個(gè)數(shù)相同。當(dāng)然，許多Velocity宏都比上面這個(gè)例子要復(fù)雜。下面是一個(gè)帶有兩個(gè)參數(shù)的Velocity宏的例子，一個(gè)顏色值，一個(gè)數(shù)組。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
這個(gè)叫做tablerows的Velocity宏帶有兩個(gè)參數(shù)。第一個(gè)參數(shù)代替了$color的位置，第二個(gè)參數(shù)代替了$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包含了一個(gè)foreach語句，并且有兩個(gè)#end語句。第一個(gè)數(shù)據(jù)#foreach，第二個(gè)結(jié)束了該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。當(dāng)這個(gè)#tablerows象上面的例子那樣調(diào)用，輸出為：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宏可以定義在一個(gè)Velocity模版之內(nèi)，但這是意味在同一應(yīng)用的其他的模版中該宏是不可見的。定義一個(gè)能讓所有的模版都能使用的宏又很多的好處：能夠減少定義同一個(gè)Velocity宏的數(shù)量，減少了出錯(cuò)的幾率，并且保證了在一處的改變能應(yīng)用到所有的模版中。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)定義在模版庫中，那么這個(gè)宏就能在相似的所有的模版中使用了。它能被多次使用于不同的目標(biāo)。在模版mushroom.vm中，調(diào)用#tablerows宏來列出一個(gè)典型的蘑菇房。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>
當(dāng)完成了對mushroom.vm的請求，Velocity能在模版庫中找到#tablerows宏------需要把這個(gè)宏定義在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宏中的參數(shù)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'
- 數(shù)值：Number literal : 1, 2 etc
- 數(shù)值范圍：IntegerRange : [ 1..2] or [$foo .. $bar]
- 對象數(shù)組：ObjectArray : [ "a", "b", "c"]
- boolean value true
- boolean value false
當(dāng)使用引用作為參數(shù)傳遞給Velocity宏，請注意引用是按名字使用。意味著他們的值是在Velocity宏中每一次的引用都是重新生成的。這個(gè)特點(diǎn)允許你傳入一個(gè)對方法的引用，并且在宏中的每一次引用都調(diào)用該方法一次。作為一個(gè)例子，下面的代碼展示了這一點(diǎn)：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()實(shí)際上被調(diào)用了三次。results in the method bar() of the reference $foo being called 3 times.
初次接觸該特性，會感到一些驚訝，但當(dāng)你比較深入的思考Velocity宏的最初的動(dòng)機(jī)的時(shí)候------減少在VTL中對于重復(fù)代碼的剪切/復(fù)制操作。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.
如果你不需要這種特性，那么你可以總是把方法的值傳遞給一個(gè)變量引用，再把該引用作為參數(shù)傳遞給方法，如下面的例子所示：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宏模版庫的列表。默認(rèn)情況下,Velocity只尋找VM_global_library.vm.這一個(gè)模版庫。配制的模版路徑用來尋找模版庫。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。該屬性用來規(guī)定宏是否能定義在模版中。默認(rèn)值為true，即允許模版設(shè)計(jì)者把宏直接定義在模版中。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。該屬性規(guī)定在模版中定義的宏是否能覆蓋在全局宏庫（velocimacro.library）中定義的宏。該屬性的默認(rèn)值為false，即阻止定義在模版中的宏覆蓋在引擎啟動(dòng)時(shí)候加載的全局宏。 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指示符的意義，這點(diǎn)和消去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" )
需要注意的就是那種需要多個(gè)指示符來完成任務(wù)的情況，比如if-else-end。下面是一個(gè)典型的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
事實(shí)上，因?yàn)樗械哪_本元素都被消意了，所以$jazz其實(shí)根本就沒有被計(jì)算。考慮下面的一個(gè)例子：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，那么會沒有輸出。注意如果腳本元素沒有正確的被消意，錯(cuò)誤就將產(chǎn)生。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仍然存在。象這樣的多余的元素會導(dǎo)致解析錯(cuò)誤。Here the #if is escaped, but there is an #end remaining; having too many endings will cause a parsing error.
VTL：格式問題VTL: Formatting Issues
雖然在這個(gè)用戶指南中，使用了轉(zhuǎn)行和空格來顯示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的規(guī)則是跳過空格，前面的例子同樣可以象下面這樣寫：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.
其他的特性O(shè)ther Features and Miscellany
數(shù)學(xué)問題Math
Velocity可以set指示符在模版中完成許多數(shù)學(xué)功能。下面的方程式展示了使用加減乘除的例子：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 )
當(dāng)使用除法做運(yùn)算，結(jié)果會是integer。所有的余數(shù)都可以使用取模運(yùn)算得到。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中，數(shù)學(xué)公式中只能使用integer(...-2, -1, 0, 1, 2...)。當(dāng)使用了一個(gè)非integer的值，日志會紀(jì)錄這個(gè)錯(cuò)誤并且返回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聯(lián)合使用。作用在于創(chuàng)建一個(gè)integer對象的數(shù)組。范圍操作具有下面的格式：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或者計(jì)算的值必須是integer。m大于或者小于n都無所謂，如果m小于n的話，該數(shù)組中的值就是下降的值序了。下面給出了一個(gè)使用范圍操作的例子：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指示符一起使用，范圍操作才有效的提供一個(gè)數(shù)組，如同上面的第四個(gè)例子所展示的一樣。Note that the range operator only produces the array when used in conjunction with #set and #foreach directives, as demonstrated in the fourth example.
當(dāng)Web頁面設(shè)計(jì)者關(guān)注于提供一致的表格大小，但有時(shí)沒有足夠的信息來填滿表格空間的時(shí)候，范圍操作會是一個(gè)很有用的解決問題的途徑。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
$!
Unknown macro: {foo}
$
!foo
$\\\!foo
This renders as:
$!foo
$!
$!foo
$
!foo
Contrast this with regular escaping, where __ precedes _$_:
\$foo
\$!foo
\$!
This renders as:
\$foo
\$!foo
\$!
Unknown macro: {foo}
\bar
Velocity宏的其他Velocimacro Miscellany
這一小節(jié)是灌關(guān)于Velocity宏的小型的FAQ。這一小節(jié)會不斷變化，所有，經(jīng)常地來看看這一小節(jié)能得到更多新的信息。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.
注意，在這一小節(jié)中，Velocimacro（Velocity宏）都縮寫為VM。Note : Throughout this section, 'Velocimacro' will commonly be abbreviated as 'VM'.
我能否使用一個(gè)指示符或者另外一個(gè)VM作為一個(gè)VM的參數(shù)？Can I use a directive or another VM as an argument to a VM?
例子：Example : #center( #bold("hello") )
不行。一個(gè)指示符不是一個(gè)合法的參數(shù)，并且在更多的情況下，VM是一作為一個(gè)指示符。No. A directive isn't a valid argument to a directive, and for most practical purposes, a VM is a directive.
不過，However..., 你可以象這樣做。一個(gè)簡單的解決該問題的方法是利用雙引號能合成其中的內(nèi)容這一特點(diǎn)。你可以象下面這樣：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' )" )
注意在后一個(gè)例子中，參數(shù)是在調(diào)用的宏里面生成的，而不是在調(diào)用方法時(shí)就生成了。換句話說，就是說作為參數(shù)傳入的VM實(shí)際上是在調(diào)用它的那個(gè)VM中生成的。看看下面這個(gè)例子：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
因?yàn)?#inner($bar)"的計(jì)算是發(fā)生在#outer()之內(nèi)的。所以，在#outer()方法內(nèi)對$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.
這和之前介紹的參數(shù)是以名字傳入VM的特點(diǎn)是符合的。所以你才能象下面那樣調(diào)用：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()就被重復(fù)的調(diào)用了，而不僅僅只有一次。要避免這個(gè)，可以在VM方法調(diào)用之外先計(jì)算出該方法的值，然后只將結(jié)果傳入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()來注冊一個(gè)Velocity宏嗎？Can I register Velocimacros via #parse() ? 當(dāng)前，要在模版中使用宏，必須確保該宏在使用之前是定義了的。這意味著#macro定義一個(gè)宏必須在使用該宏之前。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.
這一點(diǎn)在你試圖#parse一個(gè)帶有#macro的模版時(shí)需要記住的。因?yàn)?parse發(fā)生在運(yùn)行期間，并且解析器才判斷一個(gè)類似VM的元素是一個(gè)VM，這時(shí)候，#parse就不會起作用了。避免這個(gè)問題，只需要砸velocity.properties文件中定義需要在啟動(dòng)時(shí)加載的宏庫就可以了。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的自動(dòng)重加載？What is Velocimacro Autoreloading?
在開發(fā)期間，可以使用velocity.properties中的一個(gè)參數(shù)：There is a property, meant to be used in development, not production :
velocimacro.library.autoreload
該參數(shù)默認(rèn)為false。當(dāng)把該值設(shè)置為true并且下面這個(gè)屬性：which defaults to false. When set to true along with
<type>.resource.loader.cache = false
(<type>是你使用的資源加載器，比如file）象這樣設(shè)置后，當(dāng)你對Velocity宏庫做了一些改動(dòng)后，Velocity引擎會自動(dòng)地重新加載他們，所以，你就不需要手動(dòng)地去重起你的servlet引擎或者應(yīng)用了。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.
下面是一個(gè)典型的對自動(dòng)重加載做的配置：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
記住，在產(chǎn)品中不要這樣使用。Don't keep this on in production.
字符串連接String Concatenation
開發(fā)者問得比較多的一個(gè)問題就是字符串時(shí)怎么連接的？是和在Java中使用+號相似的嗎？A common question that developers ask is How do I do String concatenation? Is there any analogue to the '+' operator in Java?.
在VTL中要串連引用，你自需要把他們放在一起就行了。對將他們放在一起的環(huán)境沒有特別的要求，下面就舉幾個(gè)例子來演示：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'。一個(gè)更有趣的例子，比如你想要把一個(gè)連接后的字符串傳遞給一個(gè)方法調(diào)用，或者賦值給一個(gè)新的引用，只需要：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.
該段代碼和上一個(gè)例子有同樣的輸出。最后一個(gè)例子，當(dāng)你想把字符串引用和字符串復(fù)合起來使用，你需要使用正規(guī)的引用：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 = "$
Unknown macro: {size}
Tall$name" )
The clock is $clock.
現(xiàn)在，輸出為'The clockis BigTalBenl'。前面已經(jīng)介紹過，正規(guī)的引用告訴解析器你的引用是$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.