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

45. Questions?

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!