这是关于Velocity模版语言的指南。要得到更多的信息，请参阅Velocity 用户手册。This guide is the reference for the Velocity Template Language (VTL). For more information, please also refer to the Velocity User Guide.

参考References

变量Variables

合法的变量规则：Notation:

$ [ ! ][ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ][ } ]

例子：Examples:

• Normal notation（普通的写法，如果mud-Slinger_9 不存在，则会显示mud-Slinger_9 ）: $mud-Slinger_9
• Silent notation（如果mud-Slinger_9 不存在，则不显示任何东西）: $!mud-Slinger_9
• Formal notation（正规的写法，能最正确的区别变量名字）: ${mud-Slinger_9}

  属性Properties

合法的规则：Notation:

$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]* .[a..z, A..Z ][ a..z, A-Z, 0..9, -, ]* [ } ]

例子 Examples:

• Regular Notation: $customer.Address
• Formal Notation: ${purchase.Total}

  方法Methods

合法的规则Notation:

$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]* .[ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]*( [ opional parameter list... ] ) [ } ]

例子：Examples:

• Regular Notation: $customer.getAddress()
• Formal Notation: ${purchase.getTotal()}
• Regular Notation with Parameter List（带有参数的方法的正规调用方式）: $page.setTitle( "My Home Page" )
  VTL属性调用（get和set方法）可以被简写。比如_$object.getMethod()和$object.setMethod()_ 方法都可以简写成_$object.Method_。在使用的时候，我们更偏好使用后者,即简化的写法。使用调用方法这种写法的最大的好处就在于你能向其中传递一些参数。VTL Properties can be used as a shorthand notation for VTL Methods that take get and set. Either $object.getMethod() or $object.setMethod() can be abbreviated as $object.Method. 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.

  语句Directives

#set - 给一个引用赋值Establishes the value of a reference

格式：Format:

#set( $*ref *= [ ", ' ]arg[ ", ' ] )

其中：Usage:

• $ref - 左操作数应该是一个变量的引用或者一个属性的引用。The LHS of the assignment must be a variable reference or a property reference.
• arg - 右操作，如果右操作数是被双引号括起来的话，那么在赋值给左操作数的时候，返回的是右操作数解析出来的值，如果右操作数是被单引号括起来的话，那么就直接赋值给左操作数。如果右操作数的解析的结果为null的话，不会给左操作数赋值。The RHS of the assignment, arg is parsed if enclosed in double quotes, and not parsed if enclosed in single quotes. If the RHS evaluates to null , it is not assigned to the LHS.

例子：Examples:

• 变量的引用：Variable reference: #set( $monkey = "bill" )
• 给属性赋值：String literal: #set( $monkey.Friend = "monica" )
• 属性赋值：Property reference: #set( $monkey.Blame = $whitehouse.Leak )
• 方法引用：Method reference: #set( $monkey.Plan = $spindoctor.weave($web) )
• Number literal: #set( $monkey.Number = 123 )
• Range operator: #set( $monkey.Numbers = [1..3] )
• Object array: #set( $monkey.Say = ["Not", $my, "fault"] )

右操作数也可以是简单的数学表达式，比如：The RHS can also be a simple arithmetic expression, such as:

• Addition: #set( $value = $foo + 1 )
• Subtraction: #set( $value = $bar - 1 )
• Multiplication: #set( $value = $foo * $bar )
• Division: #set( $value = $foo / $bar )
• Remainder: #set( $value = $foo % $bar )

  #if / #elseif / #else - output conditional on truth of statements条件控制语句

格式：Format:

#if( [condition] ) [output] [ #elseif( [condition] ) [output] ]* [ #else [output] ] #end

其中：Usage:

• condition - 如果是一个boolean的话，则根据值是true或者false来判断，如果不是一个boolean，则条件的值不为null则为true。If a boolean, considered true if it has a true false; if not a boolean, considered true if not null.
• output - May contain VTL.

例子：Examples:

• 相等操作Equivalent Operator: #if( $foo == $bar )
• 大于Greater Than: #if( $foo > 42 )
• 小于Less Than: #if( $foo < 42 )
• 不小于Greater Than or Equal To: #if( $foo >= 42 )
• 不大于Less Than or Equal To: #if( $foo <= 42 )
• 相等的值Equals Number: #if( $foo == 42 )
• 相等的字符串Equals String: #if( $foo == "bar" )
• 求反Boolean NOT: #if( !$foo )

  #foreach - Loops through a list of objects遍历一个列表

格式：Format:

#foreach( $ref in arg ) statement #end

其中：Usage:

• $ref - 遍历列表的当前引用。The first variable reference is the item.
• arg - 一个列表(比如一个对象数组，集合，map)，或者数组列表，或者范围操作。May be one of the following: a reference to a list (i.e. object array, collection, or map), an array list, or the range operator.
• 语句statement - 对每次通过遍历得到的一个值得操作。What is output each time Velocity finds a valid item in the list denoted above as arg . This output is any valid VTL and is rendered each iteration of the loop.

下面是省略了处理语句的#foreach()的例子：Examples of the #foreach(), omitting the statement block :

• 引用：Reference: #foreach ( $item in $items )
• 数组：Array list: #foreach ( $item in ["Not", $my, "fault"] )
• 范围：Range operator: #foreach ( $item in [1..3] )

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>
默认的计数的变量是$velocityCount，不过，你也能在velocity.properties文件中进行自己的配置。默认的情况下，计数器是从1开始的，但是这也可以在velocity.properties文件中进行配置，也能从0开始计数。下面是在velocity.properties文件中对计数器的名字和起始值配置的代码片断：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 refernce.

counter.name = velocityCount

# Default starting value of the loop

# counter variable reference.

counter.initial.value = 1

#include -不加解释的合成本地文件Renders local file(s) that are not parsed by Velocity

格式：Format:

#include( arg[, arg2, ... argn] )

• arg - Refers to a valid file under TEMPLATE_ROOT.

例子：Examples:

• String: #include( "disclaimer.txt", "opinion.txt" )
• Variable: #include( $foo, $bar )

什么叫不加解释?就是说velocity只是把这个文件的内容直接合成到指定的位置，而如果在这个文件中也有VTL的语句，是不会翻译的。如果要实现这个功能，要用到下面的#parse。

#parse - 解释的合成本地模版Renders a local template that is parsed by Velocity

格式：Format:

#parse( arg )

• arg - Refers to a template under TEMPLATE_ROOT.

例子：Examples:

• String: #parse( "lecorbusier.vm" )
• Variable: #parse( $foo )

这里允许递归的调用。你可以在velocity.properties中改变parse_directive.maxdepth 的值来确定允许递归的层数。（默认的值为10）Recursion permitted. See parse_directive.maxdepth in velocity.properties to change from parse depth. (The default parse depth is 10.)

#stop - 停止模版引擎Stops the template engine

格式：Format:

#stop

Usage:

这个方法能停止执行当前的模版，很适合用于DEBUG。This will stop execution of the current template. This is good for debugging a template.

#macro - 允许用户定义一个Velocity宏（VM），能重用一些操作。Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required

格式：Format:

#macro( vmname $arg1 [ $arg2 $arg3 ... $argn ] ) [ VM VTL code... ] #end

• vmname - 宏的名字。Name used to call the VM ( #vmname )
• $arg1 $arg2 [ ... ] - 传递给VM的参数列表。参数的个数不限，但调用时候传入的参数必须和定义宏的时候规定的参数个数相同。Arguments to the VM. There can be any number of arguments, but the number used at invocation must match the number specified in the definition.
• [ VM VTL code... ] - 合法的VTL代码。任何能放在模版中的代码都能放在VM里面。Any valid VTL code, anything you can put into a template, can be put into a VM.

如果宏一旦定义，就可以像下面这样调用：Once defined, the VM is used like any other VTL directive in a template.

#vmname( $arg1 $arg2 )
VM可以在下面两个地方定义：VMs can be defined in one of two places:

1. Template library: can be either VMs pre-packaged with Velocity or custom-made, user-defined, site-specific VMs; available from any template
2. Inline: found in regular templates, only usable when velocimacro.permissions.allowInline=true in velocity.properties .

   注释Comments

被注释了的内容不会被合成。Comments are not rendered at runtime.

单行的注释Single Line

Example:

## This is a comment.

多行的注释Multi Line

Example:

#*
This is a multiline comment.
This is the second line
*#

Velocity在应用中通常用于生成页面，来直接代替JSP。一些使用Velocity来生成Web页面的好处如下：Velocity is often used to generate web pages in applications, usually as a direct replacement for JSP. Some of the benefits of using Velocity to generate web pages are:

• 简单Simplicity -没有多少技术的Web设计者就能书写这些页面。 The pages can be written and maintained by non-technical web designers.
• 容易维护Ease of maintainance - 使用推荐的MVC开发模式，小程序（script）不再出现在Web页面中。Scripting is removed from web pages with the recommended MVC approach.
• 对方法和属性的访问Access both methods and properties - Web设计者可以访问上下文中一个对象的属性和方法。Web designers can reference methods as well as properties of objects in a context.
• 一致性Consistency -Velocity可以被用作其他的文本生成工作（比如发送email），并提供了一致的标记语言。 Velocity can be used for other text generation tasks (such as sending email) providing a consistent way to mark up text.

这篇文档中提供了一些将Velocity用于Web应用中的基本信息。This document provides some basic info on getting started with Velocity in a web application.

使用一个框架

Velocity引擎的主要功能是基于一个模版生成文本。因此，Velocity并没有包含任何与Web相关的功能。The primary purpose of the Velocity engine is simply to generate text based on a template. Consequently, Velocity does not contain any web-related functionality in and of itself. 要创建一个Web应用，你需要一个框架来响应HTTP请求，处理用户认证，调用业务逻辑，并且返回响应。To make a web application, you will need a framework to respond to HTTP requests, handle user authentication, make business logic calls, and generate a response. 下面是一些非常强大的提供者。There are several strong contenders.

1. Velocity Tools / VelocityViewServlet - 最简单的开始的方法是下载Velocity Tools子项目，使用VelocityViewServlet。这个servlet的配置和安装都很简单。The easiest way to get started is to download the companion Velocity Tools subproject and use the VelocityViewServlet . This servlet is easy to configure and install.你需要在web服务器上创建一个模版的目录，并编辑一个包含了需要放置在上下文中的"Tools"的列表的XML文件就行了。具体的细节请参见下面的指南。 You create a directory of templates on your web server, edit an XML file that lists various "Tools" to place in the context and you are off. More details can be found in the tutorial below.
2. Velocity Tools / VelocityStruts - 也许你对流行的Struts框架比较熟悉。Struts最开始是为了设计一个为JSP提供更多有用的功能的应用。You may be familiar with the popular Struts framework, originally designed to provide much needed application functionality to JSP.在Velocity Tools 的VelocityStruts模块的帮助下，你可以用Velocity代替JSP作为页面的模版语言。这允许你使用Struts强大的基础设施的好处的同时，使用Velocity设计页面。 With the VelocityStruts module of Velocity Tools you can substitute Velocity for JSP as the page template language. This allows you to take advantage of the large base of Struts infrastructure while designing pages using Velocity.
3. 第三方框架Third party frameworks - 还有许多的第三方框架在PoweredByVelocity wiki 页面上。There are a number of third party frameworks listed on the PoweredByVelocity wiki page. 在其中，Spring可能是被公认的最先进的框架了。Of these, Spring is probably the most sophisticated and well known. Jakarta Turbine 有许多特点并且也很有用，它基于Velocity并使用Velocity作为主要的页面语言，这并不奇怪，因为有许多Velocity的早期开发者在开发和维护它。Jakarta Turbine has many features and can also be very useful. It was built with Velocity as the primary page language, which is not surprising since many of the original Velocity developers were involved in creating it.一个更简单的选择是Maverick框架，Maverick提供了一个很好的集成了Velocity的简单的控制器结构，但仅此而已。 A simpler alternative is the Maverick framework which provides a simple Controller architecture that integrates nicely with Velocity but has no bells or whistles.
4. 构建你自己的Build your own - 最后的一个选择是创建你自己的框架。A final alternative is to build your own framework.建立一个转发servlet（Dispatcher servlet），从一个文件或者数据库中检索出模版，集成你自己的商务逻辑，并返回结果给用户。 Create a dispatcher servlet, retrieve templates from a file or database, integate with your business logic and send the results back to the user. 从一个已有的框架出发并扩展它通常是一更简单的方法。特别的，你只需要为VelocityViewServlet创建一个子类，既能向其中添加新的功能。Often you'll have an easier time starting with one of the existing frameworks and customizing it. In particular you can add new functionality to the VelocityViewServlet simply by creating a subclass.

顺便一提，你可能偶然发现VelocityServlet这个类，该对象是一个在Velocity 1.4版本中不提倡使用的servlet。VelocityServlet已经不再维护，所以，我们强烈建议你使用Velocity Tools中的VelocityViewServlet。As a side note, you may also come across references to VelocityServlet, which is a deprecated servlet that was included in the Velocity Engine up to version 1.4. Since VelocityServlet is no longer being maintained we strongly recommend you use VelocityViewServlet in Velocity Tools instead.

Web方面的问题Web-Specific Issues

对于Velocity在web的应用，有一些问题需要讨论。这些都是经常遇到的问题中的一些简单的讨论。There are a few issues with Velocity that are specific to web applications. Here is a brief discussion of the most commonly encountered issues.

不要改变对象的状态Changing Object State - Don't!

在Velocity中，如果将一个对象作为一个引用，那么Velocity提供了访问该对象的任何方法的能力。在页面中显示信息的时候，这个功能很有用，但是同时如果对象或者应用的状态被改变了，这样做也是很危险的。Velocity provides the ability to call any method of an object acting as a reference. This can be useful when displaying information into the page but is dangerous when object or application state is modified.

举个例子，下面的代码安全的调用了一个list的size()方法并显示结果。For example, the following code safely calls the size() method of a list and displays the result.

There are $users.size() currently logged in.
一个不安全调用的例子：在一个财务web页面上，在上下文中的一个对象能计算每一年的数据。方法calculateNextYear()方法能计算下一年的数据并将一个内部的计数器做增加操作。An example of an unsafe operation concerns a financial web page with an object in the context that calculates data year by year. The method calculateNextYear() calculates data for the next year and advances an internal counter:

2005 data: $table.data
$table.calculateNextYear()

2006 data: $table.data
The problem with this approach is that the code cannot be repeated in multiple parts of the page. You may not intend to do so, but it's easy to forget this when cutting and pasting or writing control statements (such as #if or #foreach). This becomes more of an issue when you are dealing with application or session-level state.

我们强烈建议的实践是只使用Velocity向文本中插入信息。方法调用会是得到信息的一个有效的方法，但一般说来使用一个方法调用来改变对象的状态是一个不良的观念，来改变应用的状态一定是一个错误的想法。The (strongly) recommended practice is to only use Velocity for inserting information into text. Method calls can be useful to retrieve information. However, it's generally a bad idea to use a method call to change object state, and it's always a bad idea to change application state.

如果你必需要改变对象的状态（比如前面的例子），可以预先计算出所有可能的值并放入一个List或则Map对象中。所有的要改变应用的状态的动作应该总是放在控制器中。If you find yourself needing to change object state (as in the previous example) try precalculating all the possible values in the controller and putting them in a List or Map. Any changes to application state should always be done by the controller.

一个相关的注意，你应该在上下文对象中放入一个List或者一个Set对象，而不是放入一个Iterator或者Enumeration。这样允许集合对象在没有改变时重复使用。On a related note, you should always put a List or Set into the context instead of an Iterator or Enumeration. This allows the collection to be used more than once in the page with no change in behavior.

去掉HTML/XML标记Escaping HTML/XML Entities

任何用户添加的带有HTML或者XML标记（比如<,>,&）的文本都应该在填到web页面之前被去掉。为了确保页面正确显示和避免危险的跨站点脚本（cross-site scripting一种攻击手段，在页面中包含另一个带有木马的页面）。不象JSTL（Java标准标记语言），Velocity不包含去除HTML标记的功能，但是你可以通过三种方法来达到目的。Any user-entered text that contains special HTML or XML entities (such as <, >, or &) needs to be escaped before included in the web page. This is required, both to ensure the text is visible, and also to prevent dangerous cross-site scripting. Unlike, for example, JSTL (the Java Standard Tag Language found in Java Server Pages), Velocity does not contain any HTML-specific escaping functionality. However, you have three options:

1. 创建一个"Tool"，并且包含一个能去掉HTML标记的方法。比如 $escape.html($usertext)。这是最简单的解决问题的方法。Create a special "Tool" (an object in the context) with a method that performs escaping, for example $escape.html($usertext). This is conceptually the easiest way to solve this problem.
2. 创建一个自定义的ReferenceInsertionEventHandler ，能自动的去掉所有引用中的HTML标签。如果所有的引用中的内容都需要被检查并去掉HTML标签，那么这样做是最省事的。Create a custom ReferenceInsertionEventHandler that automatically escapes every reference. If all references need to be escaped, this is the most painless method.
3. 创建一个自定义的标识，比如#escape，来去掉在该标识对里面的所有引用中的HMTL标签。Create a custom directive (e.g. #escape) that escapes all text within the directive block.

注意，有时候其他的标记也需要被去掉。比如在CSS里面，@需要被去掉，在Javascript，单独的'符号需要从字符串中去掉或替换。Note that other kinds of escaping are sometimes required. For example, in style sheets the @ character needs to be escaped, and in Javascript strings the single apostrophe ' needs to be escaped.

应用的安全Securing the Application

当一个web应用在服务器上开始运行了，有了若干的用户和一些受保护的资源，这时候，应用的安全性方面的要求就显现出来了。Velocity中已经涵盖了大多数标准的web安全性标准。一些特别的问题（比如系统配置，跨站点脚本，或者方法自省）等都在Building Secure Applications with Velocity 这篇文章上有所介绍。Since a web application is running on a central server, that typically has multiple users and confidential resources, care must be taken to make certain that the web application is secure. Most standard web security principles apply to a web application built with Velocity. A few specific issues (such as system configuration, more on cross-site scripting, and method introspection) are written up in this article on Building Secure Applications with Velocity.

日志文件Log Files

还有一点就是Velocity在日志方面的配置比较缺乏。他总是在当前文件夹中创建一个日志文件。当Velocity用在Web应用中的时候，当前文件夹指的是应用开始的那个文件夹。如果你发现"velocity.log"这个文件出现在你文件系统的不固定位置，请检查你的Velocity 日志的配置。一般情况下，出现这个问题的原因是在除了页面生成之外的其他地方还使用了Velocity（比如发送邮件）。A minor point is that Velocity, in the absence of any log-related configuration, creates a log file in the current directory. When Velocity is used in a web application the "current directory" is usually the current directory from which the application server is started. If you start seeing the file "velocity.log" files in random places on your server filesystem, check the Velocity log configuration. Typically this occurs when Velocity is used within a web application outside of web page generation (e.g. for sending email).

指南Tutorial

下面是一个介绍使用VelocityViewServlet来建立一个简单的web应用的简要教程。更多的信息请参见Velocity Tools 的文档。What follows is a brief tutorial on building a simple web app with VelocityViewServlet. For more information, consult the Velocity Tools documentation.

1. 从 download page 下载Velocity Tools项目的源代码。里面包含了下面介绍的这个例子的代码。Download the Velocity Tools project source (you need the source for the examples) from download page .
2. 请确保你的 Apache Ant 环境安装正确。If you haven't already installed Apache Ant . do so now.
3. 使用下面的指令来构建VelocityTools的jar包和"simple"示例。Build the Velocity Tools jar and the "simple" example by typing: ant example.simple
4. 察看"examples"文件夹，在里面你会发现一个叫"index.vm"的文件，下面是这个文件的摘录：Take a look at the "examples" directory. You will see a file "index.vm". Here's an excerpt: <html> <body> I'm a velocity template.
   #if( $XHTML )
   #set( $br = "<br />" )
   #else
   #set( $br = "<br>" )
   #end
   $br $br
   Here we use a custom tool: $toytool.message
   $br $br
   Here we get the date from the DateTool: $date.medium
   </body>
   </html>
   你可以复制其他的velocity模版文件到这个文件夹里面。在examples/WEB-INF文件夹下，你会发现一个"toolbox.xml"文件，在这个文件里面就定义了自动放在Velocity上下文中的对象的列表。You can copy any additional velocity files into this same directory. In examples/WEB-INF you will see a file "toolbox.xml". This specifies a list of "Tools" that are automatically included in the context. <toolbox> <xhtml>true</xhtml>
   <tool>
   <key>toytool</key>
   <class>ToyTool</class>
   </tool>
   <data type="number">
   <key>version</key> <value>1.1</value>
   </data>
   <data type="boolean">
   <key>isSimple</key> <value>true</value>
   </data>
   <data type="string">
   <key>foo</key> <value>this is foo.</value>
   </data>
   <data type="string">
   <key>bar</key> <value>this is bar.</value>
   </data>
   <tool>
   <key>map</key>
   <class>java.util.HashMap</class>
   </tool>
   <tool>
   <key>date</key>
   <scope>application</scope> <class>org.apache.velocity.tools.generic.DateTool</class> </tool>
   </toolbox>  
   最后，应用的web.xml文件里面定义了接受请求的servlet和toolbox的配置文件位置。And finally the web.xml file specifies the name of the servlet and location of toolbox.properties. <web-app> <servlet>
   <servlet-name>velocity</servlet-name>
   <servlet-class> org.apache.velocity.tools.view.servlet.VelocityViewServlet </servlet-class>
   <init-param>
   <param-name>org.apache.velocity.toolbox</param-name>
   <param-value>/WEB-INF/toolbox.xml</param-value> </init-param>
   <load-on-startup>10</load-on-startup>
   </servlet>
   <servlet-mapping>
   <servlet-name>velocity</servlet-name>
   <url-pattern>*.vm</url-pattern>
   </servlet-mapping>
   <welcome-file-list>
   <welcome-file>index.vm</welcome-file>
   </welcome-file-list>
   </web-app>
5. 将这个文件夹拷贝到你Tomcat的webapps文件夹下，请拷贝整个文件夹（而不光是simple.war）会让你更容易通过改变或者添加一些东西来做些实验。现在，你可以通过下面的地址来访问页面了。（地址随着你的项目的名字改变）Copy this directory into your "webapps" directory on Tomcat. You could also copy "simple.war", but copying in the entire directory will let you experiment with changes. You should now be able to access your simple one-page webapp with this URL. (or something similar): http://localhost:8080/simple/index.vm
6. 尝试添加一些新的Velocity页面。注意，你只需要改变访问的URL地址就可以访问新的页面了。尝试改变toolbox.xml中的一些内容，或者向其中添加你自己的Tools。察看examples/WEB-INF的文档，或者Wiki 来得到更多的工具的使用信息。Experiment with adding new Velocity pages. Note that you can access any velocity page just by changing the URL. Try changing the entries in toolbox.xml or creating your own tools. Consult the Velocity Tools documentation and the Wiki for more info on the wide variety of tools available.