Velocity is a template Java template language.
For more information on Velocity itself, please visit the Velocity website.
 | Velocity is very similar to FreeMarker, as both are template languages that can be used outside of a Servlet container. The WebWork team recommends FreeMarker over Velocity simply because FreeMarker has better error reporting, support for JSP tags, and slightly better features. However, both are good alternatives to JSP. |
Getting Started
Getting started with Velocity is as simple as ensuring all the dependencies are included in your project's classpath. Other than that, webwork-default.xml already configures the Velocity Result needed to map your actions to your templates. You may now try out the following xwork.xml configuration:
<action name="test" class="com.acme.TestAction"> <result name="success" type="velocity">test-success.vm</result> </action>
Then in test-success.vm:
<html> <head> <title>Hello</title> </head> <body> Hello, ${name} </body> </html>
Where name is a property on your action. That's it! Read the rest of this document for details on how templates are loaded, variables are resolved, and tags can be used.
Template Loading
WebWork looks for Velocity templates in two locations (in this order):
- Web application
- Class path
This ordering makes it ideal for providing templates inside a fully built jar, but allowing for overrides of those templates to be defined in your web application. In fact, this is how you can override the default UI tags and Form Tags included with WebWork.
Variable Resolution
In Velocity, variables are looked up in several different places, in this order:
- The value stack
- The action context
- Built-in variables
Note that the action context is looked up after the value stack. This means that you can reference the variable without the typical preceding has marker (#) like you would have to when using the JSP ww:property tag. This is a nice convenience, though be careful because there is a small chance it could trip you up.
#wwurl "id=url "value=http://www.yahoo.com" Click <a href="${url}">here</a>!
The built-in variables that WebWork-Velocity integration provides are:
| Name | Description |
|---|---|
| stack | The value stack itself, useful for calls like ${stack.findString('ognl expr')} |
| action | The action most recently executed |
| response | The HttpServletResponse |
| res | Same as response |
| request | The HttpServletRequest |
| req | Same as request |
| session | The HttpSession |
| application | The ServletContext |
| base | The request's context path |
Tag Support
See the Velocity Tags documentation for information on how to use the generic Tags provided by WebWork.
Tips and Tricks
There are some advanced features that may be useful when building WebWork applications with Velocity.
Extending
Sometimes you may with to extend the Velocity support provided with WebWork. The most common reason for doing this is that you wish to include your own Tags, such as those that you have extended from the built in WebWork Tags.
To do so, write a new class that extends com.opensymphony.webwork.views.velocity.VelocityManager and overrides it as needed. Then add the following to webwork.properties:
webwork.velocity.manager.classname = com.yourcompany.YourVelocityManager
Configuring
You can configure Velocity by placing configuration items in velocity.properties.