Velocity is a template engine implemented in Java. Velocity templates typically are HTML pages with embedded scripts (although Velocity has been used for many other application scenarios). Scripts are written in the Velocity Template Language (VTL). Following is a simple example of a HTML view with embedded VTL statements:

When processed this will produce output similar to the following.

VTL has been designed from the ground up as a simple template language for view designers. With less than ten supported directives it is easy to learn. In fact, most people are up and productive within less than a day.

Velocity does not allow Java scriptlets, which helps enforce a strict MVC separation.

Please consult the following two documents for an in-depth coverage of VTL:

• Velocity User's Guide
• VTL Reference Guide

The main purpose of Velocity in a web application is typically to merge HTML templates with dynamic application data to generate dynamic views. An essential aspect of Velocity is therefore the mechanism that allows the application controller (in MVC speak) to expose data to the template.

It is important to understand the relationship between a Struts-based application and the Velocity template servlet. Both are simply Java Servlets which perform a specific task.

Requests to the Struts application are processed, application data is manipulated and eventually all data and control is forwarded to a View layer.

The Velocity servlet in this case is responsible for merging the provided application data with a template to produce HTML output.

We should note that the Velocity servlet is not exclusively tied to the Struts application. It can serve requests from web clients directly or any other servlet application as well. Technically, the Struts application hands over a request to Velocity through the forward method of javax.servlet.RequestDispatcher.

Application data is passed from the Struts servlet to the Velocity servlet as attributes of either the servlet request, session or context.

Therefore a developer simply needs to set an attribute to pass data to the View layer and make that data available for the template. For example:

request.setAttribute("Customer", CustomerObj); Whatever public methods are available on the CustomerObj instance will be made available to the template designer. Assuming there is a public getName() method, they may for example write: $Customer.name or $Customer.getName().

There is a heirarchy to the objects exposed to the template designer. For instance, if you have set an attribute "foo" in both the session and the request,

then the request attribute will take priority, and using

in the template will give you

Priority is given in the following order:

1. Tools specified in the toolbox.xml (e.g. $link, $tiles, etc.)
2. The servlet classes (e.g. $request, $response, $session, $application)
3. References set locally within the template
4. Request attributes
5. Session attributes
6. Servlet context (application) attributes

This heirarchy allows the developer to reserve control of key references (for tools and servlet resources) from the template designer and allows for values to be set at various servlet scopes in a manner similar to working with JSP and Struts.

VelocityStruts automatically populates the context with the following objects of the Servlet API on each template processing request:

The following examples illustrates how servlet resources are accessed from within Velocity template. The example renders the list of HTTP header fields of the current servlet request. In the same way, any public method of the above listed objects can be called from within templates:

The resulting output is something like this:

The Struts framework provides resources that are useful to template designers. These include logical names for physical resources, internationalized messages, error handling, form handling, etc. The interesting question is now how template designers can gain access these framework resources. In the JSP world, a set of custom tag libraries provide template designers access to the Struts framework resources. In the Velocity world, the equivalent of the JSP custom tag libraries are view tools. View tools are a very simple concept. They are Java objects with public methods that are put into the Velocity context. Tools are accessed by key and allows template designers to call on their public methods.

A set of seven view tools is included with VelocityStruts that provide template designers access to Struts framework resources. These seven view tools essentially achieve the integration between Struts and Velocity and they can be considered the core of this project.

The following example illustrates some of the features of the MessageTool for working with internationalized messages. For the example we assume that the Struts message resources contain the following two key=value pairs:

Then, the following script...

..will produce this output:

Please see the Tool Reference Documentation for more details about the view tools. Furthermore, the Velocity/Struts example application comes with several working examples that show how these tools are used.