Jakarta Project: Velocity Template Engine Tag Library

Version: 1.0

Overview
Requirements
Building the Library
Configuration
Tag Summary
Tag Reference
Examples
Javadocs
Revision History

Overview

The Velocity Template Engine allows the Velocity Template Language to be used within a JSP using JSP custom tags. Velocity is a general templating tool that provides a simple template language that allows easy access to java objects, methods, and data.

By allowing the use of Velocity from within a JSP, it allows a JSP author easy access to all public methods exposed by a Java class, as well as a simple set of control and logical directives.

Requirements

This custom tag library requires no software other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher, and the Jakarta Velocity Template Engine, version 1.1 or higher.

Building the Library

Building the library is fairly straightforward. What to do :

This taglib includes an ant build script. (Ant rocks!) Install ant on your computer (it's easy...)
You will need a servlet API jar. We recommend you get it from here for servlet 2.2 and here for the unreleased servlet 2.3 API. Note - if you are a JSP user, you will have one included with your servlet engine.
A velocity.jar. This can be found here.
The build script expects to find the jars in the lib directory. Modification of the build script is easy if they are in another location. Look for 'servlet.home' and 'velocity.home' in the build.xml.
Once all of the pieces are in place, cd to your distribution directory (where you unpacked this taglib, and where build.xml is, and simply type 'ant'.

Configuration

Follow these steps to configure your web application with this tag library:

Copy the tag library descriptor file to the /WEB-INF subdirectory of your web application. An example of this descriptor file can be found in the /examples directory.
Copy the tag library JAR file to the /WEB-INF/lib subdirectory of your web application. This will be created by the build process.
Copy the Velocity JAR file to the /WEB-INF/lib subdirectory of your web application. Please get from the Jakarta Velocity site.

Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

<taglib>
  <taglib-uri>http://jakarta.apache.org/taglibs/veltag-0.01</taglib-uri>
  <taglib-location>/WEB-INF/veltag.tld</taglib-location>
</taglib>

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="/WEB-INF/veltag.tld" prefix="vel" %>

where "vel" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

velocity	Processes the body as VTL. The body of the tag consists of normal Velocity template content. This content is a free mixture of VTL (Velocity Template Language) references and directives, as well as non-VTL content which is called 'schmoo'.

Tag Reference

velocity

Availability: version 0.01

Processes the body as VTL. The body of the tag consists of normal Velocity template content. This content is a free mixture of VTL (Velocity Template Language) references and directives, as well as non-VTL content which is called 'schmoo'.

Tag Class org.apache.taglibs.velocity.VelocityTag

Tag Body Velocity Template Language

Script Variable No

Restrictions

Attributes

Name	Required	Runtime Expression Evaluation
strictaccess	false	true

Example


<vel:velocity strictaccess="true">
  #set( $name = "Geir")
  Hello $name
</vel:velocity>

Examples

See the example template in the distrubution /examples directory

Java Docs

To create the javadocs, use the 'javadoc' build target. The docs will be here.

Revision History

v0.01