Velocity 模板使用指南

《Velocity模板使用指南》中文版田玉兵（整理）目录1.本文目地和使用对象2.什么是Velocity?3.Velocity能为你做什么?1.一个MudStoreExample4.VelocityTemplateLanguage(VTL):介绍5.输出第一个VTL页面!6.Comments(注释)7.References(引用)1.Variables(变量)2.Properties(属性)3.Methods（命令）4.属性引用中的属性查找规则8.FormalReferenceNotation(正规引用格式注意事项)9.QuietReferenceNotation(静态引用输出)10.Gettingliteral(语义问题)1.Currency(货币标志)2.EscapingValidVTLReferences(封装有效的引用)11.CaseSubstitution(可选的格式)12.Directives(指令符号)1.#set指令2.Literals(语义解析)3.Conditionals(条件判断)4.Loops(循环)3.Include(引入)6.Parse(解析模板)7.Stop8.Velocimacros(宏调用)13.注掉VTLDirectives14.VTL:一般使用的格式15.OtherFeaturesandMiscellany(其它特性和细节)1.数学计算2.RangeOperator3.AdvancedIssues:Escapingand!4.VelocimacroMiscellany(关于宏的一些问题)5.StringConcatenation(连结字符串)16.Feedback1.本文目地和使用对象本文主要介绍如何在模板中使用Velocity功能强大的模板语言VTL(VelocityTemplateLanguage)用法有一个全面的认识，并掌握如何在模板中有效使用。同时，本文提供较多的例子帮您来学习它.感谢您选择Velocity帮助您实现纯正的MVC系统构架。2.什么是Velocity?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.3.Velocity能为你做什么?1.一个MudStoreExample假设你是一个pagedesigner在为一个在线商店设计页面.我们称这个项目为TheOnlineMudStore.业务发展还不错，客户会订购不同类型的MuD,每个客户都会用自己的帐号密码login,查看选择他们订购的MuD,查看订单，但还有些忠诚用户会购卖不太流行的MuD----这些不需要出现在页面中显眼的地方。当然，TheOnlineMuDStore必须把每个客户资料及订购信息记录到DB中，现在的问题是，如何让某个客户login后就看到他感兴趣的信息？使用Velocity!我们为每个客户定制一个页面！这听起来工作量巨大，让我们试试：.使用Velocity的VTL如下来设计webpage:HTMLBODY##指定用户名字欢迎你：$customer.Name!table###输出用户喜好的MuD#foreach($mudin$mudsOnSpecial)#if($customer.hasPurchased($mud))trtd$flogger.getPromo($mud)/td/tr#end#end/table使用VTL设计页面就是这么简单！文档《VTL参考中文版》中有更全面的VTL语言介绍，掌握这些，你将会全面体会到Velocity的威力.4.VelocityTemplateLanguage(VTL):介绍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的值就是Velocity.5.输出第一个VTL页面!有你的HTML文档的任何地方，都可以引用一个变量名来输出值,如下例,先给变量名foo赋值为Velocity,然后将它输出到页面中.htmlbody#set($foo=Velocity)Hello$fooWorld!/bodyhtml在这个页面上，你看到的将是HelloVelocityWorld!.为了让查板中的VTL指令更易读,我们强烈建议你每行一条VTL指令,当然这不是必须的.关于setdirective的更多功能我们随后再讨论.6.Comments(注释)Comments可以让你在模板中包含对VTL或其它问题的说明描述以便与阅读和理解.---但它并不会在最终输出的webpages中看到.如下示例是VTL中的一行注释.##Thisisasinglelinecomment.单行注释是以##开头的一行文字.如要写下多行注释，就要像下面那样，将它们放入#*和*#间:Thisistextthatisoutsidethemulti-linecomment.Onlinevisitorscanseeit.#*Thusbeginsamulti-linecomment.Onlinevisitorswon'tseethistextbecausetheVelocityTemplatingEnginewillignoreit.*#不需要太复杂了，这两种方式己足够你给自己的页面加上充分的说明。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也可以达到这个目地。#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(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()3.g