Velocity is a template templating language for Java template language.
For more information on Velocity itself, please visit the Velocity website.
Note |
---|
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 framework uses FreeMarker internally since it has better error reporting, support for JSP tags, and slightly better featuresa richer feature set. 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, action-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:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<action name="test" class="com.acme.TestAction"> <result name="success" type="velocity">test-success.vm</result> </action> |
...
Code Block | ||||||
---|---|---|---|---|---|---|
|
...
| |||
<html> <head> <title>Hello</title> </head> <body> Hello, ${name} </body> </html> |
Where name
is a property on your actionthe Action class. That's it! Read the rest of this document for details on
There are few more details of interest, such as how templates are loaded , and variables are resolved, and tags can be used.
Template Loading
WebWork The framework looks for Velocity templates in two locations (in this order):
- Web application
- Class path
...
The ordering is designed so that a default set of templates can be placed in a JAR (perhaps shared between applications). If a template needs to be overridden, a different version can be placed in the web application.
Tip | ||
---|---|---|
| ||
Unlike JSPs, templates can be loaded from a JAR. Templates are a great way to support "plugins", since the entire module can be delivered in a single JAR, and the views easily customized by the host application. |
Variable Resolution
In Velocity, variables are looked up in several different places, in this order:there are three sources for variables, searched in a specific order.
- The value stack
- The action context
- Built-in variables
Note that Since the action context is looked up resolved 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 that has to be used with the JSP ww saf:property
tag. This is a nice convenience, though be careful because there is a small chance it could Omitting the marker can be convenient, but it can also trip you up, if used carelessly.
Code Block | ||||
---|---|---|---|---|
| ||||
#wwurl "id=url "value=http://www.yahoo.com" Click <a href="${url}">here</a>! |
The builtSAF2-in variables that WebWork-Velocity integration provides are:layer provides several implicit variables.
Variable 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 action.properties:
...
webwork.velocity.manager.classname = com.yourcompany.YourVelocityManager
...
Configuring Velocity
You can configure Velocity by placing configuration items in velocity.properties.