Velocity 手册 (二) -- 收拾收拾都放一个blog吧

奇怪.原来还可以放一块.现在不让发了.说文章太长..有一次郁闷

 

 

 

 #foreach 元素允许进行循环，例如：

#foreach( $product in $allProducts )

   

• $product

#end

这个#foreach 循环将导致$allProducts 列表 (对象) 为查询所有的产品$products (目标)遍历一遍。每次经过循环，从$allProducts 取得的值将置于$product 变量之中。

$allProducts 变量的内容是一个矢量，一个哈希表或者数组。赋给$product 变量的值是一个Java 对象并且可以从一个类似的变量引用。例如，如果 $product 真是一个Java的产品类，其名称可以通过引用$product.Name 方法来检索(即: $Product.getName())。  

我们假定 $allProducts 是一个哈希表。如果你想检索关键字的值或者在哈希表中的对象，你可以使用以下的代码：

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

   

• Key: $key -> Value: $allProducts.get($key)

#end

Velocity 提供一个更容易的方式或的循环计数，以便你可以做下面类似的工作：

#foreach( $customer in $customerList )

   

#end

$velocityCount

$customer.Name

循环计数变量的缺省名称是$velocityCount，在velocity.properties 配置文件中标明。默认情况下，该变量从1开始计数，但是可以在velocity.properties 文件中设为从0或者1开始。 下面是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

#include 脚本元素允许模板设计人员包含（导入）本地文件， 这个文件将插入到#include 指令被定义的地方。文件的内容并不通过模板引擎来渲染。处于安全的原因，被包含的文件只可以放在TEMPLATE_ROOT下。

#include( "one.txt" )

 #include 指令引用的文件在双引号内。如果超过一个文件，其间用逗号隔开。

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

被包含的文件并不是一定要用文件名来引用，事实上，最好的办法是使用变量而不是文件名。这在根据规则决定何时提交页面时，决定目标输出是很有用的。

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

 #parse 脚本元素允许页面设计员导入包含VTL的本地文件。 Velocity将解析和渲染指定的模板。

#parse( "me.vm" )

就象 #include 指令，#parse 可以使用变量而不是一个实在的模板文件。#parse 引用的模板文件必须包含的TEMPLATE_ROOT指定的目录之下。和 #include 指令不一样， #parse 只有一个参数。

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!

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

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

#macro 脚本元素允许模板设计者在VTL 模板中定义重复的段。 Velocimacros 不管是在复杂还是简单的场合都非常有用。下面这个Velocimacro，仅用来节省击键和减少排版错误，介绍了一些Velocity宏的概念。

#end

#macro( d )

在例子中，Velocimacro定义为d，它可以象调用其他VTL指令一样的形式来进行调用：

#d()

当这个模板被调用时， Velocity 将 #d() 替换为一个单行的空表格。

Velocimacro 可以带一些参数，也可以不带参数（如上例所示）。但在他被调用时，所带的参数必须和其定义时的参数一样。很多Velocimacros 定义为不止一个参数。下面这个宏带有两个参数，一个颜色，一个数组。

#end

#end

#macro( tablerows $color $somelist )

#foreach( $something in $somelist )

   

$something

 

在这个例子中定义的Velocimacro，名为tablerows, 要求两个参数。 第一个参数代替$color, 第二个代替$somelist。

可以写进VTL 模板中的东西都可以写进Velocimacro 的主体部分。tablerows 宏其实是一个foreach 语句。在#tablerows 宏的定义中有两个#ende语句，第一个属于#foreach, 第二个结束宏定义。

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

#set( $color = "blue" )

    #tablerows( $color $greatlakes )

请注意$greatlakes 替换了$somelist。 这样，当#tablerows 宏被调用时，将产生以下输出：

   

   

   

   

   

Superior

Michigan

Huron

Erie

Ontario

Velocimacros 在Velocity 模板语句内定义，这意味着它在同一站点内的其他Velocity 模板中并不有效。定义一个宏，并使其与其他模板共享很具有明显的优点：他减少了在大量的模板内重复定义宏的工作，并减少了出错的机会，并确保对其他宏的改变对其他所有模板有效。

但如果 #tablerows($color $list) 宏是在一个Velocimacros 模板库内定义的，它就可以被其他常规模板所用。当然，它可以用于各种目的，也可重用多次。在表示所有真菌类（fungi）的mushroom.vm 模板中，#tablerows 宏可以被用来列出典型的蘑菇。

#set( $parts = ["volva","stipe","annulus","gills","pileus"] )

#set( $cellbgcol = "#CC00FF" )

#tablerows( $cellbgcol $parts )

我们对mushroom.vm执行请求，Velocity 将在模板库内找到#tablerows 宏 (在velocity.properties 文件中定义)并产生以下输出：

   

   

   

   

   

volva

stipe

annulus

gills

pileus

Velocimacro 参数

Velocimacros 的参数可以是以下的VTL元素：

引用（Reference）: 以 '$' 打头的元素

字面字符串（String literal） : 比如"$foo" 或 'hello'

字面数字: 1, 2 ….

整数范围: [ 1..2] 或 [$foo .. $bar]

对象数组: [ "a", "b", "c"]

布尔真

布尔假

当把引用作为参数传递给Velocimacros时，请注意引用是按“名字”传递的。这意味着他们的值在每次使用他们的Velocimacro中产生。这个特性允许你在方法调用是传递引用，并在每次使用时进行方法调用。例如，Fo，当调用下面的Velocimacro 时，

#macro( callme $a )

         $a $a $a

     #end

 

     #callme( $foo.bar() )

结果是，在方法bar() 中，引用 $foo 被调用了3次。

咋看时，这个特征让人吃惊，当当你考虑一下Velocimacros的原本动机 – 在VTL模板中避免很多“剪切复制”操作—你就会明白。它允许你将无状态对象，比如在一个颜色表格行内重复产生一些颜色次序的对象，传递给Velocimacro。

如果你需要使用这个特征，你通常可以从方法内取得一个值，作为一个新的引用传递给宏：

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

     #callme( $myval )

Velocimacro 属性

在velocity.properties 文件中有数行定义可以用来灵活实现Velocimacros。详细情况请参见开发指南（Developer Guide）。

velocimacro.library – 是一个逗号分隔的所有Velocimacro 模板库的列表。默认情况下， Velocity 搜寻一个单一的库VM_global_library.vm.。预先配置的模板路径用来查找Velocimacro 库。

velocimacro.permissions.allow.inline – 这个属性决定Velocimacros 是否可以在常规模板内定义，取值为逻辑True或者False。默认情况下，设置为true，允许设计者在产规模板内定义宏。

velocimacro.permissions.allow.inline.to.replace.global – 逻辑true 或者false，允许标明是否允许在常规模板内定义的Velocimacro 代替在模板库中定义并通过velocimacro.library属性在启动时装入的全局宏。默认设置为false。

velocimacro.permissions.allow.inline.local.scope – 逻辑true 或者false，默认值为false。 控制是否 在模板内定义的Velocimacros 仅在定义它的模板内可见。换句话说，如果设置为true，一个模板可以定义仅能被他所用的宏。你可以用它来做一些漂亮的宏，如果一个全局调用另一个全局宏，在局部（inline）范围内，当被一个模板调用时，该模板可以定义一个被第一个全局宏调用的第二个全局宏的私有实现。其他所有模板都不受影响。

velocimacro.context.localscope – 逻辑值true 或者 false，缺省值为false。但设置为true时，所有在Velocimacro 内通过 #set() 进行的修改都将被视为Velocimacro 的本地行为，不会影响到其上下文。

velocimacro.library.autoreload – 此属性控制Velocimacro 库的自动载入。缺省值为false。如果设置为true，被调用的Velocimacro得源库将被检查是否改变，并在必要是重新载入。这将使你可以改变和测试Velocimacro 库，而不必重新启动应用服务器或者servlet容器，就象你工作在常规模板一样。这个模时仅在资源载入器的缓存模时被关闭的情况下有效 (如 file.resource.loader.cache = false )。此特征为开发时设计，不要在生产模式时使用。

Velocimacro Trivia

当前， Velocimacros 在其首次在模版中使用前必须首先定义它。这意味着， #macro() 宣称应该在使用Velocimacros之前。

如果你想#parse() 一个包含#macro() 指令的模板，记住这个非常重要。因为#parse() 在运行时发生，解析器在解析时要决定是否模版中一个看起来像VM的元素真是VM，所以解析一系列VM 宣称可能并不能如愿地工作的很好。为避免如此，可以简单地使用velocimacro.library 的办法，使Velocity 在启动时载入VM。

VTL 可以通过反斜杠("\")来进行转义，directives can be escaped with the backslash character  in a manner similar to valid VTL references.

## #include( "a.txt" ) renders as

#include( "a.txt" )

 

## \#include( "a.txt" ) renders as \#include( "a.txt" )

\#include( "a.txt" )

 

## \\#include ( "a.txt" ) renders as \

\\#include ( "a.txt" )

在转义在一个单一指令内包含多个脚本元素（比如f-else-end语句）的指令时应多加小心。下面是一个典型的VTL if语句；

#if( $jazz )

    Vyacheslav Ganelin

#end

如果 $jazz为 true，输出是

Vyacheslav Ganelin

如果 $jazz 为false，将没有输出。转义脚本元素将改变输出。考虑下面的情况；

\#if( $jazz )

    Vyacheslav Ganelin

\#end

不管 $jazz 是真或假，输出都是

#if($ jazz )

     Vyacheslav Ganelin

 #end

 

事实上，因为所有脚本元素都被转义了， $jazz 永远不会被求值。将设反斜杠在被合法转义的脚本元素之前

\\#if( $jazz )

   Vyacheslav Ganelin

\\#end

这时，如果$jazz 为真，输出是

\ Vyacheslav Ganelin

\

为理解这个情况，请注意在一个新行结束是将在输出中忽略新的一行。因此，经过#if()前的'\\' 加工后，#if()块紧跟第一个'\'。最后一个\位于新的一行，因为在'Ganelin'后又一个新行，所以，最后的那个位于#end 之前的。

如果 $jazz 为false，这里将没有输出。注意，在开始破坏了if语句的情况将不能被正确转义：

\\\#if( $jazz )

    Vyacheslave Ganelin

\\#end

这里，#if 被转义，但有一个#end 被保留了；所以有多个结束语句将导致解析错误。

虽然在本指南中的VTL经常显示在新行中或者有空格，但是下面的VTL

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

#foreach( $shogun in $imperial )

    $shogun

#end

和下面的写法同样有效。

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

Velocity的行为并不受空格的影响，前述的指令也可以写成：

Send me

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

#foreach( $a in $foo )

$a

#end

please.

或者

Send me

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

                 #foreach           ($a in $foo )$a

         #end please.

上面每种写法结果都一样。

Velocity 有一些内建的数学功能，可以使用set指令用在模版中。下面的共识分别演示了加减乘除运算：

#set( $foo = $bar + 3 )

#set( $foo = $bar - 4 )

#set( $foo = $bar * 6 )

#set( $foo = $bar / 2 )

当进行除法运算时，结果将会是整数。When a division operation is performed, the result will be an integer. 余数则可以通过模(%)运算获得。

#set( $foo = $bar % 5 )

在Velocity 中，只有整数可以进行数学运算；如果执行非整数的数学运算，将被记录下来，并返回null 。

范围操作符可以和#set 和#foreach 语句一起使用。有助于产生一个整数的目标数组，范围操作符有以下的结构：

[n..m]

n 和 m 都必须是整数或者可以产生整数。不管 m 大于或者小于n 都没关系；在m小于n这种情况下，范围可以向下计数。下面是使用范围操作符的例子：

第一个例子

#foreach( $foo in [1..5] )

$foo

#end

 

第二个例子

#foreach( $bar in [2..-2] )

$bar

#end

 

第三个例子

#set( $arr = [0..1] )

#foreach( $i in $arr )

$i

#end

 

第四个例子

[1..3]

他们分别产生一下输出

1 2 3 4 5

 

2 1 0 -1 -2

 

0 1

 

 [1..3]

范围操作符和#set 和#foreach 指令一起使用时，只是产生数组。

页面设计人员在设计具有相同尺寸的表格时，有时没有足够的数据来填充，他们会发现范围操作符非常有用。

当一个引用被! 字符处于静寂模式，并且! 字符在转义符\ 前出现，应用将用一种特别的方式处理。请注意他和常规转义的不同，下面这种情况\ 先于! 出现:

#set( $foo = "bar" )

$\!foo

$\!{foo}

$\\!foo

$\\\!foo

这样将被加工成

$!foo

$!{foo}

$\!foo

$\\!foo

对比常规转义，\先于 $:

\$foo

\$!foo

\$!{foo}

\\$!{foo}

这是结果是：

\$foo

\$!foo

\$!{foo}

\bar

 

 

 

 

 

 

 

 

 

 

 

本节是关于Velocimacros的一个小型FAQ。 本届内容会不时更新，所以请常来检查新的内容，

注 : 本节中， 'Velocimacro' 将简写为'VM'。

Q:是否可以使用指令directive 或者 VM 作为另一个VM的参数? 例如: #center( #bold("hello") )

A:  不行。指令不能用作指令的参数，而大多数情况下，作为实际的应用，VM就是指令。

不过也有一些办法。一个简单的做法是使用双引号来加工你的内容。所以，你可以这样：

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

#center( $stuff )

甚至可以节省一个步骤：

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

 

请注意，后面这个例子中，参数是在VM内部被求值，不是在调用的那一层次上。换句话说，被传入的VM的参数是整个被传入的，并且在传入的VM内部被求值。所以我们可以这样做：

#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()内部，所以在#outer() 内设置的$bar得值会是其使用的值。

这是一个有意的保护特征—参数按名称传递给VM，所以可以将象状态引用的东西传给VM ，比如：

 

#end

 

#foo( $bar.rowColor() )

#macro( foo $color )

 

Hi

There

rowColor() 被重复调用而不是一次。为避免如此，可以调用VM外部的方法，然后将值传递给VM.

#set($color = $bar.rowColor())

#foo( $color )

Q:是否可以通过#parse()注册VM ?

A：当前， Velocimacros 在其首次在模版中使用前必须首先定义它。这意味着， #macro() 宣称应该在使用Velocimacros之前。

如果你想#parse() 一个包含#macro() 指令的模板，记住这个非常重要。因为#parse() 在运行时发生，解析器在解析时要决定是否模版中一个看起来像VM的元素真是VM，所以解析一系列VM 宣称可能并不能如愿地工作的很好。为避免如此，可以简单地使用velocimacro.library 的办法，使Velocity 在启动时载入VM。

Q. 什么是VM自动载入（Velocimacro Autoreloading）?

A. 这是一个属性，在开发时使用，而不时运行时：

 velocimacro.library.autoreload

默认值为false。当设置为true时，连同.resource.loader.cache 属性设置为false（这里 是使用的资源载入器的名称，比如'file') ，Velocity 引擎在你创建VM库文件是将自动载入其改变，这样你就不必将其导入servlet 引擎（或者应用程序）中，或者用其他手段来使其自动重新载入。

下面是一个简单的设置配置组合：

file.resource.loader.path = templates

    file.resource.loader.cache = false

    velocimacro.library.autoreload = true

注意在生产状态（运行时）不要使其打开。

开发者常问的一个问题是“我如何进行字符串串联？”是否有类似于JAVA中的'+'操作符？

为了串联VTL中的引用，你不得不将它们“放在一起”。而你想要放置在一起的上下文很重要，下面举例说明。

在常规“笨办法”模板中：

       #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 BigTallBen'。