Velocity 模板使用指南 中文版Word格式.docx
《Velocity 模板使用指南 中文版Word格式.docx》由会员分享，可在线阅读，更多相关《Velocity 模板使用指南 中文版Word格式.docx（32页珍藏版）》请在冰豆网上搜索。
4
6.Comments（注释）5
7.References（引用）5
1.Variables（变量）5
2.Properties（属性）6
3.Methods（命令）6
4.属性引用中的属性查找规则6
8.FormalReferenceNotation（正规引用格式注意事项）7
9.QuietReferenceNotation（静态引用输出）7
10.Gettingliteral（语义问题）8
1.Currency（货币标志）8
2.EscapingValidVTLReferences（封装有效的引用）8
11.CaseSubstitution（可选的格式）9
12.Directives（指令符号）10
1.#set指令10
2.Literals（语义解析）12
3.Conditionals（条件判断）13
4.Loops（循环）16
3.Include（引入）17
6.Parse（解析模板）18
7.Stop18
8.Velocimacros（宏调用）18
13.注掉VTLDirectives20
14.VTL:
一般使用的格式22
15.OtherFeaturesandMiscellany（其它特性和细节）23
1.数学计算23
2.RangeOperator23
3.AdvancedIssues:
Escapingand!
24
4.VelocimacroMiscellany（关于宏的一些问题）25
5.StringConcatenation（连结字符串）26
16.Feedback27
1.本文目地和使用对象
本文主要介绍如何在模板中使用Velocity功能强大的模板语言VTL（VelocityTemplateLanguage）用法有一个全面的认识，并掌握如何在模板中有效使用。
同时，本文提供较多的例子帮您来学习它。
.
感谢您选择Velocity帮助您实现纯正的MVC系统构架。
Velocity是一个基于java的模板引擎（templateengine）.它可以让视图的设计者在web页面中引用java代码中定义的数据对象和命令。
从而使Webdesigners和java开发者依照MVC思想（Model-View-Controller）开发系统,这意味着Webdesigners只须将精力注用于良好表现力的视图外观设计，而Java程序员则只要关心着如何写出高效简洁的java对象以实现业务逻辑-----Velocity会将他们组装到一起.相比传统的jsp、PHP等脚本语言，Velocity彻底的将避免了在视图设计中出现的java代码,从而保证了website的长期可维护性.
一定要理解，Velocity是一个templateengine的意思，它还可以从模板中生成SQL语句或其它脚本提供给webpages.它也可以独立使用---做为一个工具类（utilityclass）用来生成源代码、报表、邮件模板等---在有需要重复的视图情况下，你应想到使用Velocity.Apache站点提供的另外一个框架Turbine可以和Velocity有效结合以实现trueMVCmodel.
1.一个MudStoreExample
假设你是一个pagedesigner在为一个在线商店设计页面.我们称这个项目为"
TheOnlineMudStore"
.业务发展还不错，客户会订购不同类型的MuD,每个客户都会用自己的帐号密码login,查看选择他们订购的MuD,查看订单，但还有些忠诚用户会购卖不太流行的MuD----这些不需要出现在页面中显眼的地方。
当然，TheOnlineMuDStore必须把每个客户资料及订购信息记录到DB中，现在的问题是，如何让某个客户login后就看到他感兴趣的信息？
使用Velocity!
我们为每个客户定制一个页面！
这听起来工作量巨大，让我们试试：
使用Velocity的VTL如下来设计webpage:
<
HTML>
BODY>
##指定用户名字
欢迎你：
$customer.Name!
table>
###输出用户喜好的MuD
#foreach（$mudin$mudsOnSpecial）
#if（$customer.hasPurchased（$mud））
<
tr>
td>
$flogger.getPromo（$mud）
/td>
/tr>
#end
#end
/table>
使用VTL设计页面就是这么简单！
文档《VTL参考中文版》中有更全面的VTL语言介绍，掌握这些，你将会全面体会到Velocity的威力.
介绍
TheVelocityTemplateLanguage（VTL）目标是提供一个简洁，易学的方法将动态内容展现到webpage上.awebpage设计者可以没有任何编程经验就可以在一天内学会使用它增强你的站点的展示力！
VTL使用引用（references）这种方式将dynamiccontent（动态内容，一般指java代码生成的数据对象）加入到你的website,Velocity中的变量（variable）只是refernce中的一种.Variables是用来描述从引入到视图模板中的java数据对象。
当然，java代码也可以从模板的VTL中获取数据.以下是一个写在HTML中的VTL变量:
#set（$a="
Velocity"
）
VTL声明（statement）,所有的VTLstatement都是以#开头，且包含一个指示符（这里是set）,当客户访问你的页面时,theVelocityTemplatingEngine将搜索页面中的所有#符号,如果确定这是一个VTL声明时就按一定规则处理动态内容,符号#仅仅只是表明这可能是一个VTL声明.
符号#所跟的set我们用“指示符”这一名词来称呼它（随后介绍更多的指示符）,set指示符使用一个表达式（expression）（包含在一对括号里）–将一个值value（这里是Velocity）付给变量a,（变量名在左边，值在右边，用=组合起来）.
在以上的例子中,变量是a,而符号“$”表明它是一个变量,Velocity中所有变量以符号”$”开头，所付的值要用双引号括起，这个值中还可以再添加Velocity变量，如"
Hello$name"
，输出的将是name变量所付的值。
这是理解VTL基础的规则:
以$开头的表示“引用”意思是取得一些东东.而”指示”（Directives）则以#开头来表示，有点“做些什么动作”的意思.
如上,#set用来指定值给一个变量名$a,以“$”标示的变量名a的值就是"
有你的HTML文档的任何地方，都可以引用一个变量名来输出值,如下例,先给变量名foo赋值为Velocity,然后将它输出到页面中.
html>
body>
#set（$foo="
Hello$fooWorld!
/body>
在这个页面上，你看到的将是"
HelloVelocityWorld!
"
为了让查板中的VTL指令更易读,我们强烈建议你每行一条VTL指令,当然这不是必须的.关于setdirective的更多功能我们随后再讨论.
6.Comments（注释）
Comments可以让你在模板中包含对VTL或其它问题的说明描述以便与阅读和理解.---但它并不会在最终输出的webpages中看到.如下示例是VTL中的一行注释.
##Thisisasinglelinecomment.
单行注释是以##开头的一行文字.如要写下多行注释，就要像下面那样，将它们放入#*和*#间:
Thisistextthatisoutsidethemulti-linecomment.
Onlinevisitorscanseeit.
#*
Thusbeginsamulti-linecomment.Onlinevisitorswon'
t
seethistextbecausetheVelocityTemplatingEnginewill
ignoreit.
*#
不需要太复杂了，这两种方式己足够你给自己的页面加上充分的说明。
7.References（引用）
VTL中有三种references：
变量引用（variables）,属性引用（properties）和命令引用（methods）.做为一个使用VTL的设计者,你和你的java软件工程师必须就模板中引用的特定名了（就是$后的名字）达成一致的协议！
这样，模板和java代码才可按照你们的意图去结合以输出正确的内容.
所有的引用在模板中都表现为一个字符串.假设一个引用变量$foo的值事实上是一个int,Velocityengine在处理时将调用它的.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也可以达到这个目地。
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（"
MyHomePage"
$person.setAttributes（["
Strange"
"
Weird"
Excited"
]）
前两个例子--$customer.getAddress（）and$purchase.getTotal（）–可以等同与属性引用情况：
$customer.Addressand$purchase.Total.如你猜对了这点，呵，你还蛮聪明！
同时，他们是等同与java对象coustomer的getAddress（）命令调用。
后面两个引用呢，也会直接对应java对象的对应命令，不同的是传入了命令参数。
4.属性引用中的属性查找规则
前己提及,属性可以引用到对象的命令.Velocity会使用合适的策略选择引用到的命令.它会根据协定的命令命令格式查找.无论属性引用的的名字是否大小写，Velocity都有固定的查找规则.如在$customer.address引用时，查找顺序是：
1.getaddress（）
2.getAddress（）
3.get（"
address"
4.isAddress（）
对于ＶＴＬ中大写的属性名Address引用，将是:
1.getAddress（）
2.getaddress（）
Address"
8.FormalReferenceNotation（正规引用格式注意事项）
以上是简洁格式引用的介绍，规则的格式像下面，如你看到的变量名需要放到{}中:
${mudSlinger}
${customer.Address}
${purchase.getTotal（）}
大多数情况下，简洁格式引用足以满足使用,但有些情况下，必须使用正规格式引用.
假设你构造的一个字符串中要包括有$vice变量的值.你觉得以下两种写法会是同样的结果吗:
1.Jackisa$vicemaniac.
2.Jackisa${vice}maniac.
这样，Velocity就知你要的是$vice,而不是$vicemaniac变量，正规引用格式一般用于在模板中直接调整字符串内容.
9.QuietReferenceNotation（静态引用输出）
Velocity遇到一个不能处理的引用时，一般他会直接输出这个引用$email的写法,页面上会看到的是$email，如下例,我们可以在$后面加上一个!
号，那么就会输出空白:
inputtype="
text"
name="
email"
value="
$email"
/>
$!
正式的写法是:
{email}"
10.Gettingliteral（语义问题）
一般情况下，velocity使用$,#字符来标志它的声明，但有时，ＨＴＭＬ中因为某种其它意图，也会写出这样的字符，我们讨论如何消除这种语义歧义问题.
1.Currency（货币标志）
如美元$2.50!
这样的写法出现到模板中,VTL处理时是不会出错，会正确的输出$2.50!
这个你想要的结果。
为什么呢？
一个合法的VTL标示符是以一个字母开头的，我们前面己说过.
2.EscapingValidVTLReferences（封装有效的引用）
如下示，如果没有#set（$email="
foo"
）这一行且java代码中Context对象中没有放放email对象，将直接输出$email.
#set（$email="
$email
如果email己定义了（比如它的值是foo）,而这里你却想输出$email.这样一个字符串,就需要使用转义字符”\”.
##Thefollowinglinedefines$emailinthistemplate:
\$email
\\$email
\\\$email
上面的模板在web页面上的输出将是:
foo
\foo
但如果email并没有定义，我们这样写：
输出就原封不动了：
注意：
当己定义变量和未定义变量一起输出时，会输出字面意思,如下便，$moon是未定义的：
gibbous"
$moon=$foo
输出到web页面中将是
$moon=gibbou
11.CaseSubstitution（可选的格式）
至此，你对velocity的refenerce己比较熟悉了,你可以在你的模板中开始应用这些功能.但你还可以知道的是Velocityreferences从java语法中汲取了一些优点以便模板设计者更容易使用VTL.比如:
$foo.getBar（）
##等同于
$foo.Bar
$data.setUser（"
jon"
）
##等同于
#set（$data.User="
$data.getRequest（）.getServerName（）
$data.Request.ServerName
##isthesameas
${data.Request.ServerName}
这里示例了你可选的一些引用方式.VTL汲取了java语法和javabean的一些简洁语法以解析java代码中Context中的对象和这些对象的命令及属性---这样，一个java对象的所有功能都可以展示到视图中了.
Velocity也借见了javaBean的规范（BeanspecificationsdefinedbySunMicrosystems）,是大小写敏感的;
但Velocity会尽可能的帮你修正错误.当命令getFoo（）通过指令$bar.foo在模板中引用时,Velocity的搜索规则我们在前面己讲了，你还记得是什么吗？
注意:
模板中引用的必须是通过javaBean中的getter/setter实现的，而直接的java对象的数据域是不能直接引用的,如$foo.Name会解析到classFoo'
sgetName（）的实例方法,但不会解析到Foos类的publicName这个实例变量.
12.Directives（指令符号）
模板设计者使用“引用“生成动态内容,指令（directives）–简单的说就是设计者在模板中操作java对象—让视图设计者全面控制输出内容的格式.
指令总是以#开头后面紧跟具体的指令符.就像引用一样（指令的一种）,可以将指令理解为”表示这里是一个什么东东）.如下例生成一个出错提示:
#if（$a==1）trueenough#elsenoway!
这个例子中应使用括号将else分开.
#if（$a==1）trueenough#{else}noway!
1.#set指令
#set用来给一个引用赋值.值可以被赋给变量引用或属性引用,但要将它们放入括号中，如下示:
#set（$primate="
monkey"
#set（$customer.Behavior=$primate）
“左操作数被赋值“是引用操作的一个规则.=号右侧可能是以下类型之一:
∙Variablereference变量引用
∙Stringliteral字符串
∙Propertyreference属性引用
∙Methodreference命令引用
∙Numberliteral数字
∙ArrayList数组
∙Map映射
下面是对上述类型设置的示例:
#set（$monkey=$bill）##variablereference
#set（$monkey.Friend="
monica"
）##stringliteral
#set（$monkey.Blame=$whitehouse.Leak）##propertyreference
#set（$monkey.Plan=$spindoctor.weave（$web））##methodreference
#set（$monkey.Number=123）##numberliteral
#set（$monkey.Say=["
Not"
$my,"
fault"
]）##ArrayList
#set（$monkey.Map={"
banana"
:
"
good"
roastbeef"
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（$v
升级会员 