Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
SlideShare a Scribd company logo

Apache Velocity 1.6

•
•
Henning Schmiedehausen
Henning Schmiedehausen

This document summarizes an introduction presentation about the Apache Velocity templating engine given at ApacheCon 2009. It discusses how Velocity uses a simple templating language to replace active elements in text templates with values from a data model. It provides examples of how templates specify elements to insert, loops to iterate over, and other control structures. The presentation also compares Velocity to other templating engines and languages like Java Server Pages.

1 of 47
An Introduction to Apache Velocity 1.6 Henning Schmiedehausen henning@apache.org ApacheCon 2009, Oakland, CA, U.S.A.
Templating Engine? • Uses a simple language (Velocity Templating Language = VTL) • Templates are text which contains active elements • Active elements are replaced with values from the Model • No "industry standard" templating language • Templates are processed, not compiled
Templating engines • perl • HTML-Template, Mason • PHP • Smarty, SmartTemplate, TinyButStrong • Ruby • Galena, LiquidMarkup, ERB, lots more • Python • QuickSilver, Cheetah, TurboGears, Airspeed • Java • WebMacro, StringTemplate, FreeMarker, Apache Velocity ApacheCon US 2009
A short history of Velocity • Started in 2000 • One of the first Apache Jakarta projects • ASF-licensed alternative to WebMacro • Language syntax similar and very stable • 100% pure Java, runs on Java 1.3 or better • Apache TLP since 2006, from Jakarta • Current release: 1.6.2 (March '09) ApacheCon US 2009
Velocity Spotting • Velocity is integrated in many other Apache projects • Web Frameworks: Click, Wicket, Struts, Turbine • Other projects: Maven, Camel, Portals, Tiles http://wiki.apache.org/velocity/PoweredByVelocity • Support for IDEs and Editors available (e.g. Eclipse, IntelliJ, emacs...) http://wiki.apache.org/velocity/VelocityEditors • View Component in Web Frameworks • Code Generation (Apache Torque, Eclipse) • Documentation Generation (Maven, Anakia, Texen) • E-Mail Templating (e.g. Spring Framework) ApacheCon US 2009
Velocity vs. JSP • Easier to test • No servlet container required • Better separation of Code and Design • No compilation into Java code • Few, easy to learn language elements • No embedded Java code! • better read- and understandable ApacheCon US 2009
Template Example <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> <div>${addr.town} ${addr.zip}, ${addr.state}</div> <b>Invoice</b> <div>Date: $format.date(${time.currDate})</div> <table> <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
Template Result Mr John Doe 1234 Evergreen Terrace Springfield, 12345, AY Invoice Date: Nov 3rd, 2009 Pos Description Price Qty Total 1 TV Set $499.95 1 $499.95 2 BluRay Player $299.95 1 $299.95 Various BluRay 3 $9.95 5 $49.95 Titles Total $849.97 Tax $49.90 ApacheCon US 2009
Template deciphered <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> <div>${addr.town} ${addr.zip}, ${addr.state}</div> <b>Invoice</b> A "con $format.date(${time.currDate})</div> <div>Date:xt te o bject" contai <table> getter ns the s for t a he fiel ddress. It h <tr><th>Pos</th><th>Description</th><th>Price</th> getTit le(), g ds: as <th>Qty</th><th>Total</th></tr> etFirst #foreach($item n(), (), getLast(), getTo in $invoice.items) w getZip g (), get etStreet(), <tr><td>$velocityCount</td><td>$item.desc</td> State() <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
Template deciphered A ${addr.last}</div> <div>${addr.title} ${addr.first} nother c forma ontex <div>${addr.street}</div> tters f t obje or dat ct con <div>${addr.town} ${addr.zip}, ${addr.state}</div>e and tains Such a curren n obje cy. <b>Invoice</b> ct is c alled a <div>Date: $format.date(${time.currDate})</div> "Tool" . <table> <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
Template deciphered <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> <div>${addr.town} ${addr.zip}, ${addr.state}</div> The "i n iterab voice" obje <b>Invoice</b> le field ct con loop c . The tains a #forea <div>Date: $format.date(${time.currDate})</div> reates n the ite ch...#e mized nd <table> list. <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> Fun fa <td>$format.money($item.price)</td><td>$item.quantity</td> ct: Vel conve o nient city p <td>$format.money($item.total)</td></tr> rovid es a count #end for loo ps! </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
Template deciphered <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> Th ${addr.state}</div> <div>${addr.town} ${addr.zip}, e rema This c inder is just an be <b>Invoice</b> HTML any ki formatted t n <div>Date: $format.date(${time.currDate})</div> d of text , XML ext. or pla , in tex e.g. <table> t. <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
Velocity Template Language • Simple Constructs • #directive() - line directives • #directive() ... #end - block directives • $reference or ${reference} - references • Embedded directly into template files (no open or close tags like php or JSP) • References are "loosely typed" ApacheCon US 2009
Assignments - #set() • #set creates or updates a reference • #set( $foo = “text” ) String value • #set( $foo = 100 ) Numeric value • #set( $foo = [ 1, 2, 3 ] ) Array • #set( $foo = { 1 : 2, 3 : 4 } ) Map • #set( $foo = $bar ) Reference • #set( $foo = $bar.foo ) Bean getter • #set( $bar.foo = "200" ) Bean setter • #set( $foo = $bar.doFoo() ) Method Result ApacheCon US 2009
Demo #1 - References #set( $message = 'Hello World' ) This is a Velocity "$message" program. #set( $favorite = 137 ) My favorite number is not ${favorite}. ApacheCon US 2009
Control structures • Loop • #foreach( $foo in $bars ) ... #end • loops can be terminated with #break • $velocityCount provides loop count • $velocityHasNext allows "peeking ahead" • Conditional • #if ( ) … #elseif ( ) … #else … #end ApacheCon US 2009
Control structures • Inclusion of external elements • #include() Load external file • #parse() Load and parse file • Turn VTL blocks into references • #define(name) ... #end • Evaluate templates on the fly • #evaluate(...) ApacheCon US 2009
Demo #2 - Loops #set( $list = [ 'a ', ' b ', ' c ', ' d ' ] ) #foreach( $alpha in $list ) The current letter is ${alpha}. Hint: O pening #end a bloc k can and cl osing be on el the sa ement of me lin Let’s count: #foreach( $i in [ 1..10 ] )$i #end e! ApacheCon US 2009
Demo #3 - Conditionals #if( $lang eq "DE" ) ##Use german Hallo Welt! #elseif( $lang eq "FR" ) Bonjour Monde! #else #*Use default greeting*# Hello World! #end ApacheCon US 2009
Bonus Slide: Comment Syntax #if( $lang eq "DE" ) ##Use german Hallo Welt! #elseif( $lang eq "FR" ) Bonjour Monde! #else #*Use default greeting*# ThHello World! is is th e Velo city co ## com mmen ments #end to the t synta #* .... x: *# enc end of loses the lin a mult e, iline c omme nt. ApacheCon US 2009
Macros • Builds a block directive on the fly • Create: #macro (name) … #end • Use: #name() … #end • global and local scope supported • Technically some sort of “method call” (please don’t use it like this) • factor out common template code/content ApacheCon US 2009
Macros • Macros can take parameters • Create: #macro( name $arg1 $arg2 ) … $arg1 … $arg2 … #end • Use: #name( $foo $bar ) … #end • Arbitrary number of parameters possible • Number of call parameters must match definition! ApacheCon US 2009
Demo #4: Macros #macro( quote $value ) &quot;$value&quot; #end A macro quotes #quote( 'this phrase' )! Result: A macro quotes &quot;this phrase&quot;! ApacheCon US 2009
Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing ambiguities • If a reference resolves to "null", the reference itself is inserted in the template • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing ambiguities • If a reference resolves to "null", the Yeah, that w as a s reference itself is inserted in the template tupid idea. • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing ambiguities • If a reference resolves to "null", the reference itself is inserted in the template • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing Trivia: C an end onfusing $ less so !{foo} urce o with !$ ambiguities Also !$ !{foo} f fun! {foo} c an be and in lo credib oks awkwa • If a reference resolves to "null", the ly use ful. rd but is vali d VTL reference itself is inserted in the template • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
Velocity Operators • Arithmetic operators • #set ($foo = 5 / 2 ) ## is 2! #set ($foo = 5.0 / 2) ## is 2.5 • The usual suspects: +, -, /, *, % • Range Operator • #set ($numbers = [ 1..100 ]) creates a list of integers from 1 to 100 ApacheCon US 2009
Velocity Operators Fun fa suppo ct: Sin ce Ver rts all si arithm numb on 1.5, Velo er typ etics w as inte es. Be city • Arithmetic operators ger on fore, a ly. ll • #set ($foo = 5 / 2 ) ## is 2! #set ($foo = 5.0 / 2) ## is 2.5 • The usual suspects: +, -, /, *, % • Range Operator • #set ($numbers = [ 1..100 ]) creates a list of integers from 1 to 100 ApacheCon US 2009
Misc.Velocity • Boolean operators for conditionals • !, &&, ||, ==, <=, <, >, >= • not, and, or, eq, ne, gt, ge, lt, le for convenience in e.g. XML templates • For == and !=, if the operands are not of the same class, their toString() values are compared ApacheCon US 2009
Velocity Strings • String interpolation for #set(), macro args and method args: • #set( $foo = 3.5 ) #set( $foo = "Value was $foo" ) $foo is now "Value was 3.5" • Force a reference to be a String: • #set ($foo = "$foo") • Use ' to avoid interpolation: • #set ($foo = '$foo') ApacheCon US 2009
Velocity Context • Context objects are accessible in templates • Map of names (${foo}) to arbitrary objects • Templates can only access what is in the context • There is no way to create Java objects except through context elements • Velocity can restrict which methods and fields on a context object are available ApacheCon US 2009
Velocity Context Example public static void main(String [] args) throws Exceptions{cre Thi ates $ {user} and $ VelocityContext {cliche context = new VelocityContext(); } context.put("user", "Velocity User"); context.put("cliche", "Hello World!"); VelocityEngine engine = new VelocityEngine(); Template template = engine.getTemplate(args[0]); Writer out = new OutputStreamWriter(System.out); template.merge(context, out); out.flush(); } ApacheCon US 2009
Velocity Context Template #if ($!{user}) Hello, ${user}! #end Here is a cliche: ${cliche} ApacheCon US 2009
Velocity Context Template $!{use r}  is a eleme n nt in t ifty way to he con test w text e hether xists a nd is n the user on-nu ll. #if ($!{user}) Hello, ${user}! #end Here is a cliche: ${cliche} ApacheCon US 2009
Velocity Context Result Hello, Velocity User! Here is a cliche: Hello, World! ApacheCon US 2009
Interaction with the Context • The real power of Velocity • Uses runtime reflection • All public methods in public classes are available • Shortcut notation for property access ($a.b vs $a.getB()) • Type promotion as Java does • Method parameters can not be omitted! (this is not perl!) ApacheCon US 2009
Interaction with the Context Trivia: • The real power of Velocity Also, u p • anoth ublic meth er gre Uses runtime reflection o at way ds in publi to spe c sing in nd ho classes! Ign • ner cla All public methods in public classes are sses c urs de an be o buggi ring this is icky. T ng! available ry to a void it . • Shortcut notation for property access ($a.b vs $a.getB()) • Type promotion as Java does • Method parameters can not be omitted! (this is not perl!) ApacheCon US 2009
Velocity Tools • A "tool" is a context object that exposes useful methods to a template, e.g date formatting or localization • A "toolbox" is a collection of useful Java classes • The Velocity Tools sub-project offers: • GenericTools All-purpose tools • VelocityView Webapp centric tools • VelocityStruts Velocity as Struts 1.x View • Other toolboxes on the web ApacheCon US 2009
VelocityViewServlet • VelocityViewServlet renders arbitrary Templates through web.xml mapping • XML config file to define tools • Different tool scopes/lifecycles: • application, session, request • Request, Response, Session and ServletContext objects are exposed to templates ApacheCon US 2009
Demo #5:VelocityView • Uses VelocityTools 2.0 (beta4 is the current release) • VelocityViewServlet does the work • Uses LinkTool, ParameterTool, EscapeTool • ($link, $params, and $esc) • A custom tool: AddressBook is a ~30 line POJO • Only one template: index.vm (~50 lines) • ~20 lines of config (including web.xml) ApacheCon US 2009
Advanced Velocity • Custom directives can be created and integrated in the Velocity parser (org.apache.velocity.runtime.directive.Directive) • Multiple Resource loaders to load templates from different sources (files, classpath, jars, database, remote URLs) • Event Handlers for Exception handling, XML escaping, etc. • Introspector for method and property access can be customized or replaced with user code ApacheCon US 2009
Hacking Velocity • Velocity Template Language (VTL) is defined in JavaCC grammar • VTL itself can be changed or extended (requires recompilation of velocity.jar) • More “Advanced Velocity“ at http:// wiki.apache.org/velocity/HackingVelocity ApacheCon US 2009
Other Velocity uses • Velocity Subprojects • Texen for generic text generation • Anakia for XML to documentation • Apache Torque – generates Java and SQL code from templates • VelocityViewTag – Embed Velocity in JSP • Velosurf – Generate SQL Web Views ApacheCon US 2009
Questions?
Where to go from here • Velocity Web Site • http://velocity.apache.org/ • Velocity Mailing Lists • http://velocity.apache.org/contact.html • Velocity Wiki • http://wiki.apache.org/velocity/ • Slides at the US ApacheCon 2009 web site and on slideshare.net ApacheCon US 2009
Thanks for your interest in Velocity!

More Related Content

Apache Velocity 1.6

  • 1. An Introduction to Apache Velocity 1.6 Henning Schmiedehausen henning@apache.org ApacheCon 2009, Oakland, CA, U.S.A.
  • 2. Templating Engine? • Uses a simple language (Velocity Templating Language = VTL) • Templates are text which contains active elements • Active elements are replaced with values from the Model • No "industry standard" templating language • Templates are processed, not compiled
  • 3. Templating engines • perl • HTML-Template, Mason • PHP • Smarty, SmartTemplate, TinyButStrong • Ruby • Galena, LiquidMarkup, ERB, lots more • Python • QuickSilver, Cheetah, TurboGears, Airspeed • Java • WebMacro, StringTemplate, FreeMarker, Apache Velocity ApacheCon US 2009
  • 4. A short history of Velocity • Started in 2000 • One of the first Apache Jakarta projects • ASF-licensed alternative to WebMacro • Language syntax similar and very stable • 100% pure Java, runs on Java 1.3 or better • Apache TLP since 2006, from Jakarta • Current release: 1.6.2 (March '09) ApacheCon US 2009
  • 5. Velocity Spotting • Velocity is integrated in many other Apache projects • Web Frameworks: Click, Wicket, Struts, Turbine • Other projects: Maven, Camel, Portals, Tiles http://wiki.apache.org/velocity/PoweredByVelocity • Support for IDEs and Editors available (e.g. Eclipse, IntelliJ, emacs...) http://wiki.apache.org/velocity/VelocityEditors • View Component in Web Frameworks • Code Generation (Apache Torque, Eclipse) • Documentation Generation (Maven, Anakia, Texen) • E-Mail Templating (e.g. Spring Framework) ApacheCon US 2009
  • 6. Velocity vs. JSP • Easier to test • No servlet container required • Better separation of Code and Design • No compilation into Java code • Few, easy to learn language elements • No embedded Java code! • better read- and understandable ApacheCon US 2009
  • 7. Template Example <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> <div>${addr.town} ${addr.zip}, ${addr.state}</div> <b>Invoice</b> <div>Date: $format.date(${time.currDate})</div> <table> <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
  • 8. Template Result Mr John Doe 1234 Evergreen Terrace Springfield, 12345, AY Invoice Date: Nov 3rd, 2009 Pos Description Price Qty Total 1 TV Set $499.95 1 $499.95 2 BluRay Player $299.95 1 $299.95 Various BluRay 3 $9.95 5 $49.95 Titles Total $849.97 Tax $49.90 ApacheCon US 2009
  • 9. Template deciphered <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> <div>${addr.town} ${addr.zip}, ${addr.state}</div> <b>Invoice</b> A "con $format.date(${time.currDate})</div> <div>Date:xt te o bject" contai <table> getter ns the s for t a he fiel ddress. It h <tr><th>Pos</th><th>Description</th><th>Price</th> getTit le(), g ds: as <th>Qty</th><th>Total</th></tr> etFirst #foreach($item n(), (), getLast(), getTo in $invoice.items) w getZip g (), get etStreet(), <tr><td>$velocityCount</td><td>$item.desc</td> State() <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
  • 10. Template deciphered A ${addr.last}</div> <div>${addr.title} ${addr.first} nother c forma ontex <div>${addr.street}</div> tters f t obje or dat ct con <div>${addr.town} ${addr.zip}, ${addr.state}</div>e and tains Such a curren n obje cy. <b>Invoice</b> ct is c alled a <div>Date: $format.date(${time.currDate})</div> "Tool" . <table> <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
  • 11. Template deciphered <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> <div>${addr.town} ${addr.zip}, ${addr.state}</div> The "i n iterab voice" obje <b>Invoice</b> le field ct con loop c . The tains a #forea <div>Date: $format.date(${time.currDate})</div> reates n the ite ch...#e mized nd <table> list. <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> Fun fa <td>$format.money($item.price)</td><td>$item.quantity</td> ct: Vel conve o nient city p <td>$format.money($item.total)</td></tr> rovid es a count #end for loo ps! </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
  • 12. Template deciphered <div>${addr.title} ${addr.first} ${addr.last}</div> <div>${addr.street}</div> Th ${addr.state}</div> <div>${addr.town} ${addr.zip}, e rema This c inder is just an be <b>Invoice</b> HTML any ki formatted t n <div>Date: $format.date(${time.currDate})</div> d of text , XML ext. or pla , in tex e.g. <table> t. <tr><th>Pos</th><th>Description</th><th>Price</th> <th>Qty</th><th>Total</th></tr> #foreach($item in $invoice.items) <tr><td>$velocityCount</td><td>$item.desc</td> <td>$format.money($item.price)</td><td>$item.quantity</td> <td>$format.money($item.total)</td></tr> #end </table> <div>Total $format.money($invoice.total)</div> <div>Tax $format.money($invoice.tax)</div> ApacheCon US 2009
  • 13. Velocity Template Language • Simple Constructs • #directive() - line directives • #directive() ... #end - block directives • $reference or ${reference} - references • Embedded directly into template files (no open or close tags like php or JSP) • References are "loosely typed" ApacheCon US 2009
  • 14. Assignments - #set() • #set creates or updates a reference • #set( $foo = “text” ) String value • #set( $foo = 100 ) Numeric value • #set( $foo = [ 1, 2, 3 ] ) Array • #set( $foo = { 1 : 2, 3 : 4 } ) Map • #set( $foo = $bar ) Reference • #set( $foo = $bar.foo ) Bean getter • #set( $bar.foo = "200" ) Bean setter • #set( $foo = $bar.doFoo() ) Method Result ApacheCon US 2009
  • 15. Demo #1 - References #set( $message = 'Hello World' ) This is a Velocity "$message" program. #set( $favorite = 137 ) My favorite number is not ${favorite}. ApacheCon US 2009
  • 16. Control structures • Loop • #foreach( $foo in $bars ) ... #end • loops can be terminated with #break • $velocityCount provides loop count • $velocityHasNext allows "peeking ahead" • Conditional • #if ( ) … #elseif ( ) … #else … #end ApacheCon US 2009
  • 17. Control structures • Inclusion of external elements • #include() Load external file • #parse() Load and parse file • Turn VTL blocks into references • #define(name) ... #end • Evaluate templates on the fly • #evaluate(...) ApacheCon US 2009
  • 18. Demo #2 - Loops #set( $list = [ 'a ', ' b ', ' c ', ' d ' ] ) #foreach( $alpha in $list ) The current letter is ${alpha}. Hint: O pening #end a bloc k can and cl osing be on el the sa ement of me lin Let’s count: #foreach( $i in [ 1..10 ] )$i #end e! ApacheCon US 2009
  • 19. Demo #3 - Conditionals #if( $lang eq "DE" ) ##Use german Hallo Welt! #elseif( $lang eq "FR" ) Bonjour Monde! #else #*Use default greeting*# Hello World! #end ApacheCon US 2009
  • 20. Bonus Slide: Comment Syntax #if( $lang eq "DE" ) ##Use german Hallo Welt! #elseif( $lang eq "FR" ) Bonjour Monde! #else #*Use default greeting*# ThHello World! is is th e Velo city co ## com mmen ments #end to the t synta #* .... x: *# enc end of loses the lin a mult e, iline c omme nt. ApacheCon US 2009
  • 21. Macros • Builds a block directive on the fly • Create: #macro (name) … #end • Use: #name() … #end • global and local scope supported • Technically some sort of “method call” (please don’t use it like this) • factor out common template code/content ApacheCon US 2009
  • 22. Macros • Macros can take parameters • Create: #macro( name $arg1 $arg2 ) … $arg1 … $arg2 … #end • Use: #name( $foo $bar ) … #end • Arbitrary number of parameters possible • Number of call parameters must match definition! ApacheCon US 2009
  • 23. Demo #4: Macros #macro( quote $value ) &quot;$value&quot; #end A macro quotes #quote( 'this phrase' )! Result: A macro quotes &quot;this phrase&quot;! ApacheCon US 2009
  • 24. Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing ambiguities • If a reference resolves to "null", the reference itself is inserted in the template • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
  • 25. Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing ambiguities • If a reference resolves to "null", the Yeah, that w as a s reference itself is inserted in the template tupid idea. • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
  • 26. Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing ambiguities • If a reference resolves to "null", the reference itself is inserted in the template • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
  • 27. Reference Syntax & Evaluation • Any reference represents a Java object • Use ${reference} to avoid parsing Trivia: C an end onfusing $ less so !{foo} urce o with !$ ambiguities Also !$ !{foo} f fun! {foo} c an be and in lo credib oks awkwa • If a reference resolves to "null", the ly use ful. rd but is vali d VTL reference itself is inserted in the template • $!ref or $!{ref} means "be quiet when null" • Evaluation uses toString() method ApacheCon US 2009
  • 28. Velocity Operators • Arithmetic operators • #set ($foo = 5 / 2 ) ## is 2! #set ($foo = 5.0 / 2) ## is 2.5 • The usual suspects: +, -, /, *, % • Range Operator • #set ($numbers = [ 1..100 ]) creates a list of integers from 1 to 100 ApacheCon US 2009
  • 29. Velocity Operators Fun fa suppo ct: Sin ce Ver rts all si arithm numb on 1.5, Velo er typ etics w as inte es. Be city • Arithmetic operators ger on fore, a ly. ll • #set ($foo = 5 / 2 ) ## is 2! #set ($foo = 5.0 / 2) ## is 2.5 • The usual suspects: +, -, /, *, % • Range Operator • #set ($numbers = [ 1..100 ]) creates a list of integers from 1 to 100 ApacheCon US 2009
  • 30. Misc.Velocity • Boolean operators for conditionals • !, &&, ||, ==, <=, <, >, >= • not, and, or, eq, ne, gt, ge, lt, le for convenience in e.g. XML templates • For == and !=, if the operands are not of the same class, their toString() values are compared ApacheCon US 2009
  • 31. Velocity Strings • String interpolation for #set(), macro args and method args: • #set( $foo = 3.5 ) #set( $foo = "Value was $foo" ) $foo is now "Value was 3.5" • Force a reference to be a String: • #set ($foo = "$foo") • Use ' to avoid interpolation: • #set ($foo = '$foo') ApacheCon US 2009
  • 32. Velocity Context • Context objects are accessible in templates • Map of names (${foo}) to arbitrary objects • Templates can only access what is in the context • There is no way to create Java objects except through context elements • Velocity can restrict which methods and fields on a context object are available ApacheCon US 2009
  • 33. Velocity Context Example public static void main(String [] args) throws Exceptions{cre Thi ates $ {user} and $ VelocityContext {cliche context = new VelocityContext(); } context.put("user", "Velocity User"); context.put("cliche", "Hello World!"); VelocityEngine engine = new VelocityEngine(); Template template = engine.getTemplate(args[0]); Writer out = new OutputStreamWriter(System.out); template.merge(context, out); out.flush(); } ApacheCon US 2009
  • 34. Velocity Context Template #if ($!{user}) Hello, ${user}! #end Here is a cliche: ${cliche} ApacheCon US 2009
  • 35. Velocity Context Template $!{use r}  is a eleme n nt in t ifty way to he con test w text e hether xists a nd is n the user on-nu ll. #if ($!{user}) Hello, ${user}! #end Here is a cliche: ${cliche} ApacheCon US 2009
  • 36. Velocity Context Result Hello, Velocity User! Here is a cliche: Hello, World! ApacheCon US 2009
  • 37. Interaction with the Context • The real power of Velocity • Uses runtime reflection • All public methods in public classes are available • Shortcut notation for property access ($a.b vs $a.getB()) • Type promotion as Java does • Method parameters can not be omitted! (this is not perl!) ApacheCon US 2009
  • 38. Interaction with the Context Trivia: • The real power of Velocity Also, u p • anoth ublic meth er gre Uses runtime reflection o at way ds in publi to spe c sing in nd ho classes! Ign • ner cla All public methods in public classes are sses c urs de an be o buggi ring this is icky. T ng! available ry to a void it . • Shortcut notation for property access ($a.b vs $a.getB()) • Type promotion as Java does • Method parameters can not be omitted! (this is not perl!) ApacheCon US 2009
  • 39. Velocity Tools • A "tool" is a context object that exposes useful methods to a template, e.g date formatting or localization • A "toolbox" is a collection of useful Java classes • The Velocity Tools sub-project offers: • GenericTools All-purpose tools • VelocityView Webapp centric tools • VelocityStruts Velocity as Struts 1.x View • Other toolboxes on the web ApacheCon US 2009
  • 40. VelocityViewServlet • VelocityViewServlet renders arbitrary Templates through web.xml mapping • XML config file to define tools • Different tool scopes/lifecycles: • application, session, request • Request, Response, Session and ServletContext objects are exposed to templates ApacheCon US 2009
  • 41. Demo #5:VelocityView • Uses VelocityTools 2.0 (beta4 is the current release) • VelocityViewServlet does the work • Uses LinkTool, ParameterTool, EscapeTool • ($link, $params, and $esc) • A custom tool: AddressBook is a ~30 line POJO • Only one template: index.vm (~50 lines) • ~20 lines of config (including web.xml) ApacheCon US 2009
  • 42. Advanced Velocity • Custom directives can be created and integrated in the Velocity parser (org.apache.velocity.runtime.directive.Directive) • Multiple Resource loaders to load templates from different sources (files, classpath, jars, database, remote URLs) • Event Handlers for Exception handling, XML escaping, etc. • Introspector for method and property access can be customized or replaced with user code ApacheCon US 2009
  • 43. Hacking Velocity • Velocity Template Language (VTL) is defined in JavaCC grammar • VTL itself can be changed or extended (requires recompilation of velocity.jar) • More “Advanced Velocity“ at http:// wiki.apache.org/velocity/HackingVelocity ApacheCon US 2009
  • 44. Other Velocity uses • Velocity Subprojects • Texen for generic text generation • Anakia for XML to documentation • Apache Torque – generates Java and SQL code from templates • VelocityViewTag – Embed Velocity in JSP • Velosurf – Generate SQL Web Views ApacheCon US 2009
  • 46. Where to go from here • Velocity Web Site • http://velocity.apache.org/ • Velocity Mailing Lists • http://velocity.apache.org/contact.html • Velocity Wiki • http://wiki.apache.org/velocity/ • Slides at the US ApacheCon 2009 web site and on slideshare.net ApacheCon US 2009
  • 47. Thanks for your interest in Velocity!

Editor's Notes

  1. mvn exec:java -Dexec.mainClass=org.apache.velocity.contextdemo.ContextDemo -Dexec.args=src/main/templates/Test.vm