q是关于Velocity模版语言的指南。要得到更多的信息,请参阅Velocity 用户手册。This guide is the reference for the Velocity Template Language (VTL). For more information, please also refer to the Velocity User Guide.
合法的变量规则:Notation:
$ [ ! ][ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, _ ][ } ]
例子QExamples:
合法的规则:Notation:
$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]* .[a..z, A..Z ][ a..z, A-Z, 0..9, -, ]* [ } ]
例子 Examples:
合法的规则Notation:
$ [ { ][ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]* .[ a..z, A..Z ][ a..z, A..Z, 0..9, -, ]*( [ opional parameter list... ] ) [ } ]
例子QExamples:
格式QFormat:
#set( $*ref *= [ ", ' ]arg[ ", ' ] )
其中QUsage:
例子QExamples:
x作数也可以是单的数学表达式,比如QThe RHS can also be a simple arithmetic expression, such as:
格式QFormat:
#if( [condition] ) [output] [ #elseif( [condition] ) [output] ]* [ #else [output] ] #end
其中QUsage:
例子QExamples:
格式QFormat:
#foreach( $ref in arg ) statement #end
其中QUsage:
下面是省略了处理语句?foreach()的例子:Examples of the #foreach(), omitting the statement block :
Velocity提供了一个简单的得到循环ơ数的方法,所以你可以像下面这h作: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>
默认的计数的变量?velocityCountQ不q,你也能在velocity.properties文g中进行自q配置。默认的情况下,计数器是?开始的Q但是这也可以在velocity.properties文g中进行配|,也能?开始计数。下面是在velocity.properties文g中对计数器的名字和v始值配|的代码片断QThe 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
格式QFormat:
#include( arg[, arg2, ... argn] )
例子QExamples:
什么叫不加解释?是说velocity只是把这个文件的内容直接合成到指定的位置Q而如果在q个文g中也有VTL的语句,是不会翻译的。如果要实现q个功能Q要用到下面?parse?/p>
格式QFormat:
#parse( arg )
例子QExamples:
q里允许递归的调用。你可以在velocity.properties中改?em>parse_directive.maxdepth 的值来定允许递归的层数。(默认的gؓ10QRecursion permitted. See parse_directive.maxdepth in velocity.properties to change from parse depth. (The default parse depth is 10.)
格式QFormat:
#stop
Usage:
q个Ҏ能停止执行当前的模版Q很适合用于DEBUG。This will stop execution of the current template. This is good for debugging a template.
格式QFormat:
#macro( vmname $arg1 [ $arg2 $arg3 ... $argn ] ) [ VM VTL code... ] #end
如果宏一旦定义,可以像下面q样调用QOnce 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:
被注释了的内容不会被合成。Comments are not rendered at runtime.
Example:
## This is a comment.
Example:
#*
This is a multiline comment.
This is the second line
*#
Velocity在应用中通常用于生成面Q来直接代替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:
q篇文档中提供了一些将Velocity用于Web应用中的基本信息。This document provides some basic info on getting started with Velocity in a web application.
Velocity引擎的主要功能是Z一个模版生成文本。因此,Velocityq没有包含Q何与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. 要创Z个Web应用Q你需要一个框架来响应HTTPhQ处理用戯证,调用业务逻辑Qƈ且返回响应。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.
Z一提,你可能偶然发?span class=nobr>VelocityServletq个c,该对象是一个在Velocity 1.4版本中不提倡用的servlet?span class=nobr>VelocityServlet
已经不再l护Q所以,我们强烈你用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.
对于Velocity在web的应用,有一些问题需要讨论。这些都是经帔R到的问题中的一些简单的讨论。There are a few issues with Velocity that are specific to web applications. Here is a brief discussion of the most commonly encountered issues.
在Velocity中,如果一个对象作Z个引用,那么Velocity提供了访问该对象的Q何方法的能力。在面中显CZ息的时候,q个功能很有用,但是同时如果对象或者应用的状态被改变了,q样做也是很危险的。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.
举个例子Q下面的代码安全的调用了一个list的size()Ҏq显C结果。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面上,在上下文中的一个对象能计算每一q的数据。方法calculateNextYear()Ҏ能计下一q的数据q将一个内部的计数器做增加操作。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向文本中插入信息。方法调用会是得C息的一个有效的ҎQ但一般说来用一个方法调用来改变对象的状态是一个不良的观念Q来改变应用的状态一定是一个错误的x。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.
如果你必需要改变对象的状态(比如前面的例子)Q可以预先计出所有可能的值ƈ攑օ一个List或则Map对象中。所有的要改变应用的状态的动作应该L攑֜控制器中。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.
一个相关的注意Q你应该在上下文对象中放入一个List或者一个Set对象Q而不是放入一个Iterator或者Enumeration。这样允讔R合对象在没有改变旉复用。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.
M用户d的带有HTML或者XML标记Q比?lt;,>,&Q的文本都应该在填到web面之前被去掉。ؓ了确保页面正显C和避免危险的跨站点脚本Qcross-site scripting一U攻LD,在页面中包含另一个带有木马的面Q。不象JSTLQJava标准标记语言Q,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:
注意Q有时候其他的标记也需要被L。比如在CSS里面Q@需要被LQ在JavascriptQ单独的'W号需要从字符串中L或替换。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.
当一个web应用在服务器上开始运行了Q有了若q的用户和一些受保护的资源,q时候,应用的安全性方面的要求显现出来了。Velocity中已l涵盖了大多数标准的web安全性标准。一些特别的问题Q比如系l配|,跨站点脚本,或者方法自省){都在Building Secure Applications with Velocity q篇文章上有所介绍。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.
q有一点就是Velocity在日志方面的配置比较~Z。他L在当前文件夹中创Z个日志文件。当Velocity用在Web应用中的时候,当前文gҎ的是应用开始的那个文g夏V如果你发现"velocity.log"q个文g出现在你文gpȝ的不固定位置Q请查你的Velocity 日志的配|。一般情况下Q出现这个问题的原因是在除了面生成之外的其他地方还使用了VelocityQ比如发送邮Ӟ。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).
下面是一个介l?a title=VelocityViewServlet >VelocityViewServlet来徏立一个简单的web应用的简要教E。更多的信息请参见Velocity Tools 的文档。What follows is a brief tutorial on building a simple web app with VelocityViewServlet. For more information, consult the Velocity Tools documentation.