目录
- 关于本指南
- 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:
$
Unknown macro: {mudSlinger}
$
Unknown macro: {customer.Address}
$
Unknown macro: {purchase.getTotal()}
在通常情况下，我们会使用引用的缩写方式，但在一些特定的情况下，我们必须使用引用的正规形式以保证模版能按照我们的想法正确的执行。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 $
Unknown macro: {vice}
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="$!
Unknown macro: {email}
"/>
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
## 等同于 $
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标准之上的。该标准中的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
#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
$!
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
这一小节是灌关于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 = "$
Unknown macro: {size}
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.