《Velocity 模板使用指南》中文版

Velocity 是一个基于java的模板引擎(template engine). 它可让视图的设计者在web页面中引用java代码中定义的数据对象和命令。从而使Web designers和java开发者依照MVC思想(Model-View-Controller )开发系统,这意味着Web designers只须将精力注用于良好表现力的视图外观设计，而Java程序员则只要关心着如何写出高效简洁的java对象以实现业务逻辑 -----Velocity会将他们组装到一块儿. 相比传统的jsp、PHP等脚本语言，Velocity完全的将避免了在视图设计中出现的java代码, 从而保证了web site的长期可维护性.

一定要理解，Velocity是一个template engine的意思，它还能够从模板中生成SQL语句或其它脚本提供给web pages. 它也能够独立使用---作为一个工具类(utility class)用来生成源代码、报表、邮件模板等---在有须要重复的视图状况下，你应想到使用Velocity.Apache站点提供的另一个框架Turbine 能够和Velocity有效结合以实现true MVC model.

3.Velocity能为你作什么?

1.一个Mud Store Example

假设你是一个page designer 在为一个在线商店设计页面. 咱们称这个项目为 "The Online Mud Store".业务发展还不错，客户会订购不一样类型的MuD,每一个客户都会用本身的账号密码login,查看选择他们订购的MuD,查看订单，但还有些忠诚用户会购卖不太流行的MuD----这些不须要出如今页面中显眼的地方。固然，The Online MuD Store必须把每一个客户资料及订购信息记录到DB中，如今的问题是，如何让某个客户login后就看到他感兴趣的信息？

使用Velocity!咱们为每一个客户定制一个页面！这听起来工做量巨大，让咱们试试：.

使用Velocity的 VTL 以下来设计 web page:

<HTML>

<BODY>

##指定用户名字

欢迎你： $customer.Name!

<table>

###输出用户喜爱的MuD

#foreach( $mud in $mudsOnSpecial )

#if ( $customer.hasPurchased($mud) )

<tr>

<td>

$flogger.getPromo( $mud )

</td>

</tr>

#end

</table>

使用VTL设计页面就是这么简单！文档《VTL参考中文版》中有更全面的VTL语言介绍，掌握这些，你将会全面体会到Velocity的威力.

4.Velocity Template Language (VTL): 介绍

The Velocity Template Language (VTL)目标是提供一个简洁，易学的方法将动态内容展示到web page上. a web page设计者能够没有任何编程经验就能够在一天内学会使用它加强你的站点的展现力！.

VTL使用引用(references )这种方式将dynamic content(动态内容，通常指java代码生成的数据对象)加入到你的web site,Velocity中的变量(variable)只是refernce中的一种. Variables是用来描述从引入到视图模板中的java数据对象。固然，java代码也能够从模板的VTL中获取数据.如下是一个写在HTML中的 VTL变量:

#set( $a = "Velocity" )

VTL声明( statement),因此的VTL statement都是以#开头，且包含一个指示符（这里是set）,当客户访问你的页面时, the Velocity Templating Engine将搜索页面中的全部 # 符号,若是肯定这是一个VTL声明时就按必定规则处理动态内容, 符号#仅仅只是代表这多是一个VTL声明.

符号# 所跟的set咱们用“指示符”这一名词来称呼它(随后介绍更多的指示符), set 指示符使用一个表达式(expression) (包含在一对括号里) –将一个值 value (这里是Velocity)付给变量a,（变量名在左边，值在右边，用=组合起来）.

在以上的例子中,变量是a ,而符号“$”代表它是一个变量,Velocity中全部变量以符号”$”开头，所付的值要用双引号括起，这个值中还能够再添加Velocity变量，如"Hello $name"，输出的将是name变量所付的值。

这是理解VTL基础的规则:

以$开头的表示“引用”意思是取得一些东东.而”指示”(Directives)则以#开头来表示，有点“作些什么动做”的意思.

如上便, #set 用来指定值给一个变量名$a, 以“$”标示的变量名a的值就是"Velocity".

5.输出第一个VTL页面!

有你的HTML文档的任何地方，均可以引用一个变量名来输出值, 以下例, 先给变量名foo 赋值为Velocity,而后将它输出到页面中.

<html>

<body>

#set( $foo = "Velocity" )

Hello $foo World!

</body>

<html>

在这个页面上，你看到的将是 "Hello Velocity World!".

为了让查板中的VTL指令更易读, 咱们强烈建议你每行一条VTL指令,固然这不是必须的. 关于 set directive的更多功能咱们随后再讨论.

6.Comments(注释)

Comments可让你在模板中包含对VTL或其它问题的说明描述以便与阅读和理解.---但它并不会在最终输出的web pages中看到.以下示例是VTL中的一行注释.

## This is a single line comment.

单行注释是以## 开头的一行文字.如要写下多行注释，就要像下面那样，将它们放入#* 和*#间:

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.

不须要太复杂了，这两种方式己足够你给本身的页面加上充分的说明。

7.References(引用)

VTL 中有三种references：变量引用(variables),属性引用(properties)和命令引用(methods). 作为一个使用VTL的设计者, 你和你的java软件工程师必须就模板中引用的特定名了(就是$后的名字)达成一致的协议！这样，模板和java代码才可按照大家的意图去结合以输出正确的内容.

全部的引用在模板中都表现为一个字符串. 假设一个引用变量 $foo 的值事实上是一个int, Velocity engine在处理时将调用它的.toString() 去解析这个字符串所表明的对象(int).

1.Variables(变量)

简单的说变量以"$" 开后，后面跟一个VTL指示符( Identifier).一个合法的VTL指示符是以字母开头，后面能够是如下任意字符:

alphabetic (a .. z, A .. Z)

numeric (0 .. 9)

hyphen ("-")

underscore ("_")

如下是正确的VTL变量名:

$foo

$mudSlinger

$mud-slinger

$mud_slinger

$mudSlinger1

当VTL中的一个变量如 $foo, 这个变量能够在模板中提取它本身的值经过set 指示符,或者从java代码中.好比，若是需java中的变量foo的值为bar,给模板中全部输出$foo声明的值都成为bar.固然，在模板中使用以下VTL也能够达到这个目地。

#set( $foo = "bar" )

2.Properties(属性)

VTL的第二种引用，属性引用,注意”属性”具备相对固定的格式. 它也是以$开头的合法VTL指示符,随后是”变量名字.变量属性”. 以下例:

$customer.Address

$purchase.Total

第一个例子, $customer.Address.咱们设想可能在两种意思.首先它可能在查找customer引用的一个hashtable中的以“Address”为key关联的一个数据对象.另外他可能表示的是java对象customer中的getAddress()这个命令取得的结果(固然也可写成 $customer.getAddress()). 当客户请求Web页面中Velocity将根据具体的customer类型输出.

3.Methods（命令）

在java 代码中定义命令是最一般的事, 像执得一组方程式计算成本，读取一个文件等. 命令引用和其它引用一个也是一个通常的VTL声明,看以下的例子可能会更快的理解:

$customer.getAddress()

$purchase.getTotal()

$page.setTitle( "My Home Page" )

$person.setAttributes( ["Strange", "Weird", "Excited"] )

前两个例子 -- $customer.getAddress() and $purchase.getTotal() – 能够等同与属性引用状况： $customer.Address and $purchase.Total. 如你猜对了这点，呵，你还蛮聪明！同时，他们是等同与java对象coustomer的getAddress（）命令调用。后面两个引用呢，也会直接对应java对象的对应命令，不一样的是传入了命令参数。

4.属性引用中的属性查找规则

前己说起,属性能够引用到对象的命令. Velocity会使用合适的策略选择引用到的命令. 它会根据协定的命令命令格式查找. 不管属性引用的的名字是否大小写，Velocity都有固定的查找规则.如在$customer.address引用时，查找顺序是：

getaddress()
getAddress()
get("address")
isAddress()

对于ＶＴＬ中大写的属性名Address引用，将是:

getAddress()
getaddress()
get("Address")
isAddress()

8.Formal Reference Notation(正规引用格式注意事项)

以上是简洁格式引用的介绍，规则的格式像下面，如你看到的变量名须要放到{}中:

${mudSlinger}

${customer.Address}

${purchase.getTotal()}

大多数状况下，简洁格式引用足以知足使用,但有些状况下，必须使用正规格式引用.

假设你构造的一个字符串中要包括有 $vice 变量的值. 你以为如下两种写法会是一样的结果吗:

1.Jack is a $vicemaniac.

2.Jack is a ${vice}maniac.

这样，Velocity就知你要的是 $vice, 而不是 $vicemaniac变量，正规引用格式通常用于在模板中直接调整字符串内容.

9.Quiet Reference Notation(静态引用输出)

Velocity遇到一个不能处理的引用时，通常他会直接输出这个引用$email的写法,页面上会看到的是$email，以下例,咱们能够在$后面加上一个!号，那么就会输出空白:.

正式的写法是:.

10.Getting literal( 语义问题)

通常状况下，velocity使用$,#字符来标志它的声明，但有时，ＨＴＭＬ中由于某种其它意图，也会写出这样的字符，咱们讨论如何消除这种语义歧义问题.

1.Currency(货币标志)

如美圆 $2.50!这样的写法出现到模板中, VTL处理时是不会出错，会正确的输出$2.50!这个你想要的结果。为何呢？一个合法的VTL标示符是以一个字母开头的，咱们前面己说过.

2.Escaping Valid VTL References(封装有效的引用)

以下示，若是没有#set( $email = "foo" )这一行且java代码中Context对象中没有放放email对象，将直接输出$email.

#set( $email = "foo" )

$email

若是email己定义了 (好比它的值是 foo),而这里你却想输出 $email. 这样一个字符串,就须要使用转义字符”\”.

## The following line defines $email in this template:

#set( $email = "foo" )

$email

\$email

\\$email

\\\$email

上面的模板在web页面上的输出将是:

foo

$email

\foo

\$email

但若是email并无定义，咱们这样写：.

$email

\$email

\\$email

\\\$email

输出就原封不动了：

$email

\$email

\\$email

\\\$email

注意：当己定义变量和未定义变量一块儿输出时，会输出字面意思,以下便，$moon是未定义的：

#set( $foo = "gibbous" )

$moon = $foo

输出到web页面中将是

$moon = gibbou

11.Case Substitution(可选的格式)

至此，你对velocity的refenerce己比较熟悉了, 你能够在你的模板中开始应用这些功能. 但你还能够知道的是Velocity references从java语法中汲取了一些优势以便模板设计者更容易使用VTL.好比:

$foo

$foo.getBar()

## 等同于

$foo.Bar

$data.setUser("jon")

##等同于

#set( $data.User = "jon" )

$data.getRequest().getServerName()

##等同于

$data.Request.ServerName

## is the same as

${data.Request.ServerName}

这里示例了你可选的一些引用方式. VTL汲取了java语法和java bean的一些简洁语法以解析java代码中Context中的对象和这些对象的命令及属性---这样，一个java对象的全部功能均可以展现到视图中了.

Velocity也借见了java Bean的规范(Bean specifications defined by Sun Microsystems), 是大小写敏感的; 但Velocity会尽量的帮你修正错误. 当命令 getFoo() 经过指令 $bar.foo在模板中引用时,Velocity的搜索规则咱们在前面己讲了，你还记得是什么吗？.

注意:模板中引用的必须是经过java Bean中的getter/setter 实现的，而直接的java对象的数据域是不能直接引用的,如$foo.Name 会解析到 class Foo's getName() 的实例方法,但不会解析到Foos类的 public Name 这个实例变量.

12.Directives(指令符号)

模板设计者使用“引用“生成动态内容, 指令(directives) – 简单的说就是设计者在模板中操做java对象—让视图设计者全面控制输出内容的格式.

指令老是以 #开头后面紧跟具体的指令符. 就像引用同样（指令的一种）,能够将指令理解为”表示这里是一个什么东东).以下例生成一个出错提示:

#if($a==1)true enough#elseno way!#end

这个例子中应使用括号将else分开.

#if($a==1)true enough#{else}no way!#end

1.#set指令

#set 用来给一个引用赋值.值能够被赋给变量引用或属性引用, 但要将它们放入括号中，以下示:

#set( $primate = "monkey" )

#set( $customer.Behavior = $primate )

“左操做数被赋值“是引用操做的一个规则.=号右侧多是如下类型之一:

Variable reference变量引用
String literal字符串
Property reference 属性引用
Method reference 命令引用
Number literal 数字
ArrayList 数组
Map 映射

下面是对上述类型设置的示例:

#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

#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) ## Map

注意: 在ArrayList类型引用的例子中，其原素定义在数组 [..]中, 所以，你可使表 $monkey.Say.get(0)访问第一个元素.

相似的,引用Map 的例子中, 原素定义在 { } 中，其键和值间以:隔成一对，使用 $monkey.Map.get("bannana") 在上例中将返回 'good', ( $monkey.Map.banana也会有一样效果).

下面是通常的计算表达式:

#set( $value = $foo + 1 )

#set( $value = $bar - 1 )

#set( $value = $foo * $bar )

#set( $value = $foo / $bar )

但注意：若是右边的操做数是一个属性或命令的引用而返回null,那么赋值将不会成功，且在随后的VTL中也不能再取出使用. 以下例:

#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, 上面的TVL输出结果将是:

The result of the first query is bill

The result of the second query is bill

这对与初学者的理解有些麻烦,好比在 #foreach loops中，你使用 #set 给一个属性或命令赋值时，以下例示:

#set( $criteria = ["name", "address"] )

#foreach( $criterion in $criteria )

#set( $result = $query.criteria($criterion) )

#if( $result )

Query was successful

#end

在上例中，就不能依赖if( $result )来决定查询是否成功. $result 一但被 #set 为null (context会一样), 它将不能被赋 其它值 (不能从 context中取出).

一个解决办法是，每次都将$result 设为 false. 若是 $query.criteria() 调用成功，就能够检测到.

#set( $criteria = ["name", "address"] )

#foreach( $criterion in $criteria )

#set( $result = false )

#set( $result = $query.criteria($criterion) )

#if( $result )

Query was successful

#end

注意： #set 不须要使用 #end 来声明结尾.

2.Literals (语义解析)

使用#set 指令时,变量若是用 “”引发会被解析，如:

#set( $directoryRoot = "www" )

#set( $templateName = "index.vm" )

#set( $template = "$directoryRoot/$templateName" )

$template

输出的将是:

www/index.vm

但当用单引号引发来时，就不会被解析：:

#set( $foo = "bar" )

$foo

#set( $blargh = '$foo' )

$blargh

输出后会是:

bar

$foo

默认状况下，不会解析单引号中的变量，固然，这能够经过改变Velocity的配置参数来改变：

velocity.properties such that stringliterals.interpolate=false.

另外, 指令 #literal 元素能够用来输出字面意思，以下示.

#literal()

#foreach ($woogie in $boogie)

nothing will happen to $woogie

#end

会输出：:

#foreach ($woogie in $boogie)

nothing will happen to $woogie

#end

3.Conditionals(条件判断)

1.If / ElseIf / Else

#if 指令用来根据条件在页面中输出内容, 以下简单的例子:

#if( $foo )

<strong>Velocity!</strong>

#end

根据变量 $foo计算后是否为true决定输出, 这会有两种状况: (i) $foo 的是值是一个boolean (true/false)型并有一个true value, 或 (ii) 它是一个非null值. 要记者，Velocity context 中只能包含Objects, 所以当咱们讲 'boolean'时, 它就是一个Boolean (the class).

在 #if 和 #end 的内容是否会输出，由$foo是否为true决定. 这里，若是 $foo is true, 输出将是: "Velocity!". 若是$foo 为null或false,将不会有任何输出.

#elseif 或 #else 能够 #if 和组合使用. 若是第一个表达式为true,将会不计算之后的流程，以下例假设t $foo 是15 and $bar 产 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

输出将会是

Go South.

2.Relational and Logical Operators(关系和逻辑运算)

Velocity使用==来作比较,以下例.

#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

注意：== 计算与java中的 == 计算有些不一样：不能用来测试对象是否相等(指向同一块内存). Velocity中是否相等仅直接的用来比较numbers, strings的值, or objects的toString()结果是否相等. 若是是不一样的对象,会调用它们的toString()命令结果来比较.

Velocity也使用AND, OR and NOT 执行逻辑运算.详细说明请参看《VTL参考中文版》，以下是一些简单示例：

## logical AND

#if( $foo && $bar )

<strong> This AND that</strong>

#end

仅当 $foo $bar 和都为true时，#if()才会输出中间内容.

OR 运算例子

## logical OR

#if( $foo || $bar )

<strong>This OR That</strong>

#end

$foo或$bar只要有一个为true就能够输出。

NOT运算则只有一个操做参数或表达式 :

##logical NOT

#if( !$foo )

<strong>NOT that</strong>

#end

考虑下，下面的例子有几种输出结果？.

#if( $foo == $bar)it's true!#{else}it's not!#end</li>

4.Loops(循环)

Foreach Loop

#foreach 用来建立循环. For example:

<ul>

#foreach( $product in $allProducts )

<li>$product</li>

#end

</ul>

#foreach 会生成包含$products中对象的一个列表. 每一次循环都会将列表中的一个对象赋与变量$product .

$allProducts 或以是一个Vector, a Hashtable or an Array类型的容器. 指定给变量 $product 是一个引用到其中一个java对象的引用. For example, if $product 确实是一个java代码中的Product class i,它能够这样的方法访问$product.Name method (ie: $Product.getName()).

咱们假设 $allProducts 是一个Hashtable.看看取出其中的东东多么简单:

<ul>

#foreach( $key in $allProducts.keySet() )

<li>Key: $key -> Value: $allProducts.get($key)</li>

#end

</ul>

经过引用变量$velocityCount能够访问到Velocity提供的计数器:

<table>

#foreach( $customer in $customerList )

<tr><td>$velocityCount</td><td>$customer.Name</td></tr>

#end

</table>

$velocityCount默认的计数器引用，你能够在配置velocity.properties中改为你喜欢的:

# 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

固然，你还能够设置其它参数，具体见《Velocity Java开发指南中文版》中讲解.

# The maximum allowed number of loops.

directive.foreach.maxloops = -1

3.Include(引入)

#include 脚本元素让模板设计者能够在模板中引入一个本地文件, 这个被引入的文件将不会通过Velocity的解析. 安全起见，能够引放的文件只是是配置参数TEMPLATE_ROOT所定义目录下的，默认为当前目录下.

#include( "one.txt" )

若是须要引入多个文件，能够像下面这样.

#include( "one.gif","two.txt","three.htm" )

固然，还可用一个变量名来代替文件名引入.

#include( "greetings.txt", $seasonalstock )

6.Parse(解析模板)

#parse 元素指示能够引入一个包含TVL的本地文件，这个文件将被Veloict engine解析输出。.

#parse( "me.vm" )

与 #include 指令不一样, #parse 能够从引入的模板中获得变量引用.但#parse指令只能接受一个参数.

VTL templates 被#parse 的模板中还能够再包含#parse声明，默认的深度为10，这是由配置参数directive.parse.max.depth在文件velocity.properties中决定的，你能够修改它以适合项目要求

7.Stop

#stop 指令用来指示在模板的某处，engine中止解析，这通常用来调用。用法很简单.

#stop

8.Velocimacros(宏调用)

#macro 指令让模板设计者能够将些重复、相关的的脚本版判定义为一个功能块.不管在什么状况下. 出于单一意图设计的 Velocimacro都会最大程序的减小模板编写中能够的出错,仍是看个例子来理解一下Velocimacros的概念.

#macro( d )

#end

这样就定义了一个名为d的宏，它能够在其它的模板中像下面那样直接引用:

#d()

Velocimacro能够接收0到任意多的传入参数.如上个例是0个参数,但当它被调用时，也必须传入一样多的参数. 这里定义了一个有两个参数的宏.

#macro( tablerows $color $somelist )

#foreach( $something in $somelist )

<tr><td bgcolor=$color>$something</td></tr>

#end

而后，咱们在页面中来使用：

#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )

#set( $color = "blue" )

<table>

#tablerows( $color $greatlakes )

</table>

注意变量 $greatlakes 取代了宏中变量 $somelist的输出，最终的输出以下:

<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">Ontario</td></tr>

</table>

宏通常被定义在模板中，那么站点上的其它模板中又如何调用呢？如能定义一个能够更大范围内共想的宏就太好了

若是将宏#tablerows($color $list) 定义到一个模板库中(Velocimacros template library), 其它模板就均可以访问它了.

Velocimacro Arguments（宏的参数）

Velocimacros能够从TVL中接受如下参数 :

引用类型 : 全部以'$'开头的
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

当传一个引用参数给宏时, 引用是经过名字传入的('pass by name').

#macro( callme $a )

$a $a $a

#end

#callme( $foo.bar() )

上例中命令 bar() 被调用了3 times.

最后要说的是,这个特性有些难以学习,但当你精心组织规划你的宏库时，消除在VTL中重复功能的脚本时 –你能够像使用一个对象或组件同样使用宏, 好比一个宏对象生成多个表格的重复色彩.

若是你想利用这个特性，你只须要像下面那样简单的编码传一个值给它来调用 :

#set( $myval = $foo.bar() )

#callme( $myval )

Velocimacro Properties(宏的属性)

配置文件 velocity.properties 中有多行相关配置，具体请见《Velocity Java开发指南中文版》.

velocimacro.library –用来指定全局的宏库，多个能够,号分开.

velocimacro.permissions.allow.inline – 默认为true,可让宏定义在一个正规的模板文件中.

velocimacro.permissions.allow.inline.to.replace.global – 用来指定模板内定义的宏的功能是否要以替换全局库，默认为false.

velocimacro.permissions.allow.inline.local.scope –模板中定义的宏的使用范围是否只是本模板可用.

velocimacro.context.localscope –若是为true,宏经过#set赋值时.宏中将保持一个，且不会因为context中的数据被修改而变化,一样，宏中的修改也不会改变context中的。

velocimacro.library.autoreload – 是否自动从新载入，用于调试环境,默认false,如为true,须要取掉chcheing:. file.resource.loader.cache = false ).

一些细节：

宏必须在模板中使用#macro()指令前定义.

尽可能不要直接在模板中使用#parse() 包含 #macro() 指令.由于 #parse() 动做在运行时执行,时会有一个在VM中查找元素的过程.

13.注掉 VTL Directives

嗯，你学下英语吧，一看就懂J

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" )

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

If $jazz is true, the output is

Vyacheslav Ganelin

If $jazz is false, there is no output. Escaping script elements alters the output. Consider the following case:

\#if( $jazz )

Vyacheslav Ganelin

\#end

Whether $jazz is true or false, the output will be

#if($ jazz )

Vyacheslav Ganelin

#end

In fact, because all script elements are escaped, $jazz is never evaluated for its boolean value. Suppose backslashes precede script elements that are legitimately escaped:

\\#if( $jazz )

Vyacheslav Ganelin

\\#end

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.

If $jazz is false, the output is

Note that things start to break if script elements are not properly escaped.

\\\#if( $jazz )

Vyacheslave Ganelin

\\#end

Here the #if is escaped, but there is an #end remaining; having too many endings will cause a parsing error.

14.VTL: 通常使用的格式

尽可能是这样：

#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )

#foreach( $shogun in $imperial )

$shogun

#end

而不要这样写，虽然它能够运行:

Send #set($foo=["$10 and ","a pie"])#foreach($a in $foo)$a#end please.

Velocity会自动跳过空格，上面的能够这样写：:

Send me

#set( $foo = ["$10 and ","a pie"] )

#foreach( $a in $foo )

#end

please.

or as

Send me

#set($foo = ["$10 and ","a pie"])

#foreach ($a in $foo )$a

#end please.

In each case the output will be the same.

15.Other Features and Miscellany(其它特性和细节)

1.数学计算

以下是四则运算的例子:

#set( $foo = $bar + 3 )

#set( $foo = $bar - 4 )

#set( $foo = $bar * 6 )

#set( $foo = $bar / 2 )

2.Range Operator

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]

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 )

#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]

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 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.

3.Advanced Issues: Escaping and !

When a reference is silenced with the ! character and the ! character preceded by an \ escape character, the reference is handled in a special way. Note the differences between regular escaping, and the special case where \ precedes ! follows it:

#set( $foo = "bar" )

$\!foo

$\!{foo}

$\\!foo

$\\\!foo

This renders as:

$!foo

$!{foo}

$\!foo

$\\!foo

Contrast this with regular escaping, where \ precedes $:

\$foo

\$!foo

\$!{foo}

\\$!{foo}

This renders as:

$foo

$!foo

$!{foo}

\bar

4.Velocimacro Miscellany(关于宏的一些问题)

这是一些简短的问题总结,也许你先要有这样一个概念:. 'Velocimacro' 就像一个‘VM’。

能否用一个指示符作为另一个指示符运算的参数?

如 : #center( #bold("hello") )

No. 指示符不是有效的参数但你能够这样实现你想要的：

#set($stuff = "#bold('hello')" )

#center( $stuff )

或者：

#center( "#bold( 'hello' )" )

上面这个例子中，参数是在调用的宏中生成的.不是调用者传入的. 看看下面的例子 :

#macro( inner $foo )

inner : $foo

#end

#macro( outer $foo )

#set($bar = "outerlala")

outer : $foo

#end

#set($bar = 'calltimelala')

#outer( "#inner($bar)" )

输出将是:

Outer : inner : outerlala

由于 "#inner($bar)" 是发生在 #outer()内部的！

能否经过 #parse()来注册一个宏 ?

宏必须在模板使用前定义好.前面己有一个关于此问题的建议，#parse()是运行时执进的，JVM查找对象的顺序不必定会全按咱们预计的执行。

什么是宏的自动从新装载?

这是由配置参数决定的, 为方例开发者，在生产环境中则不须要 :

velocimacro.library.autoreload

默认的是false.当设为true中，须要设定chcheing参数;

<type>.resource.loader.cache = false

(具体配置请见开发指南，以下是一个配置的例子)

file.resource.loader.path = templates

file.resource.loader.cache = false

velocimacro.library.autoreload = true

注意：Don't keep this on in production.

5.String Concatenation(连结字符串)

很简单，看例子就是 :

#set( $size = "Big" )

#set( $name = "Ben" )

The clock is $size$name.

上面的输出将是

'The clock is BigBen'.

或者：

#set( $size = "Big" )

#set( $name = "Ben" )

#set($clock = "$size$name" )

The clock is $clock.

它们都是一样的输出，最后一个例子以下，:

#set( $size = "Big" )

#set( $name = "Ben" )

#set($clock = "${size}Tall$name" )

The clock is $clock.

输出将是

'The clock is BigTallBen'.