Client and server-side templating with Velocity

By Sing Li
2004-06-13


Deploying Velocity with Tomcat 5
The Velocity distribution comes with an org.apache.velocity.servletVelocityServlet library class that you can extend to quickly create a template processing servlet. Any templates tested on the standalone client application can be deployed on the server using VelocityServlet. Moving your standalone Velocity templates to a Web application is relatively easy. Simply perform the following steps:

1. Derive a Servlet class from the org.apache.velocity.servlet.VelocityServlet class.
2. Override and implement one of the handleRequest() methods.
3. In the implementation of handleRequest(), add data or tools (see the Tools in Velocity sidebar) that you want to use within the template as attributes to the context.

Tools in Velocity
Tools are utility Java objects that are made available to templates through the Velocity context. While you can attach such objects manually to the context, the toolbox manager of VelocityViewServlet can do this in a flexible and structured manner. Typically, tools are used inside templates by invoking their methods. Both VelocityViewServlet and VelocityStruts provide valuable pre-tested tools that are extremely useful when deploying Velocity as a view technology.

4. In the implementation of handleRequest(), fetch the template from a file or a resource (such as a JAR file) and return it.
In the example code distribution, com.ibm.dvworks.velocity.VelTestServlet is a servlet that we have created following the above steps. You can examine the code under the webapps\vservlet\WEB-INF\src directory. If you modify the code, make sure you recompile it using the compile.bat batch file.

The deployment descriptor (the web.xml file) defines the servlet and maps it to the /vServlet URL pattern, as shown in Listing 19:

Listing 19. Tomcat deployment descriptor for custom Velocity-based servlet

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
     PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
     "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
   <servlet>
     <servlet-name>vServlet</servlet-name>
     <servlet-class>com.ibm.dvworks.velocity.VelTestServlet</servlet-class>
   </servlet>

   <servlet-mapping>
     <servlet-name>vServlet</servlet-name>
     <url-pattern>/vServlet</url-pattern>
   </servlet-mapping>
</web-app>

The template to be loaded and processed is placed in the webapps\vServlet directory. In our case, it is called variables.vm. To test, make sure you have the velocity-dep-???.jar file placed in the webapps\vServlet\WEB-INF\lib directory, then start up Tomcat 5 and access the http://localhost:8080/vservlet/Servlet URL.

Deploying VelocityViewServlet
For extensive templating work in a Web application, you should use VelocityViewServlet from the Velocity tools collection. Velocity tools is a subproject of Velocity (see Resources for the URL to download the latest version). This servlet provides more complete support for using Velocity as a view layer technology, either working in conjunction with or instead of JSP technology. Using VelocityViewServlet can save you significant redundant coding, since it provides:

• Direct template access to the request object and attributes, the session object and attributes, and the servlet context and attributes

• A formalized, externally configurable "toolbox" for adding custom tools that can be used by the template (tools in this sense are just compiled Java classes that have public methods)

• A library of versatile, tested, ready-to-use tools

To integrate VelocityViewServlet into your Web application, take a look at the sample velview Web application (in the webapps\velview directory). This application includes the template that we have been working with throughout this article. In addition, it also displays attributes from request, session, and servlet context objects. The integration steps are as follows:

First, make sure that the velocity-tools-view.jar file is in the application's lib directory. Of course, the velocity JAR files should also be located here.

In the deployment descriptor web.xml file, include VelocityViewServlet. The initialization parameter is a toolbox description XML file. The servlet is mapped to handle all files with a .vm extension, as shown in Listing 20:

Listing 20. Tomcat deployment descriptor (web.xml) for VelocityViewServlet

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
   <servlet>
     <servlet-name>velocityView</servlet-name>
     <servlet-class>org.apache.velocity.tools.view.servlet.VelocityViewServlet</servlet-class>
     <init-param>
       <param-name>org.apache.velocity.toolbox</param-name>
       <param-value>/WEB-INF/toolbox.xml</param-value>
     </init-param>
   </servlet>
   <servlet-mapping>
     <servlet-name>velocityView</servlet-name>
     <url-pattern>*.vm</url-pattern>
   </servlet-mapping>
</web-app>

In the toolbox descriptor (toolbox.xml) file of this example, two generic tools from the available Velocity tools library are included and made accessible within the template: DateTool and MathTool. These tools enable us to format date and time information, and perform floating point math within our templates, as shown in Listing 21:

Listing 21. Toolbox descriptor including DateTool and MathTool

<?xml version="1.0"?>
<toolbox>
  <tool>
     <key>date</key>
     <scope>application</scope>
     <class>org.apache.velocity.tools.generic.DateTool</class>
   </tool>
<tool>
     <key>math</key>
     <scope>application</scope>
     <class>org.apache.velocity.tools.generic.MathTool</class>
</tool>
...

A set of commonly used standard tools is available with VelocityViewServlet, as shown in Table 1:

Table 1. Standard tools available with VelocityViewServlet

Tool Name: Description
LinkTool: Works with URIs. Very frequently used. You will need this tool whenever you create a clickable link within your template. It can generate the context-dependent portion of the URI.
CookieTool: Enables templates to create or access browser-cached cookies.
ParameterParser: Simplifies the parsing of incoming request parameters.

There are also two highly specialized, less frequently used tools, as shown in Table 2:

Table 2. Specialized VelocityViewServlet tools

Tool Name: Description
ViewRenderTool: Enables templates to parse strings that contain VTL.
AbstractSearchTool: Provides a skeletal tool (must be extended with your own custom Java code) for the implementation of online searches and search result pagination.

You can use the http://localhost:8080/velview/variables.vm URL to test the velview application. You should examine the template source code to see the Velocity engine, the LinkTool, and the CookieTool at work.

Tutorial Pages:
» Client and server-side templating with Velocity
» Basic template engine operation
» Velocity contexts
» Velocity as a standalone parser
» Velocity vs. JSP technology on the server
» Deploying Velocity with Tomcat 5
» Interoperating with the Struts framework
» Conclusions
» Resources


First published by IBM developerWorks

Related Tutorials: » All about JAXP, Part 1 » Make Database Queries Without the Database » Load List Values for Improved Efficiency » 2 Ways To Implement Session Tracking » A Simple Way to Read an XML File in Java » Develop Aspect-Oriented Java Applications with Eclipse and AJDT