Velocity Tools

Subprojects

Docs

Development

Velocity News Feed

Overview

A Velocity "tool" is just a POJO (plain old java object) that is "useful" in a template and is not meant to be rendered in the output. In other words, a "tool" (in Velocity-speak) is meant to be used but not seen themselves (e.g. for formatting dates or numbers, url building, etc).

The VelocityTools project is, first of all, a collection of such useful Java classes, as well as infrastructure to easily, automatically and transparently make these tools available to your Velocity templates. Other aims of the project include providing easy integration of Velocity into the view-layer of your web applications (via the VelocityViewTag, VelocityViewServlet) and the Maven Plugin.

In recognition of these varying aims, the VelocityTools project is divided into two parts: GenericTools and VelocityView. Each of these parts builds on the previous one and has its own JAR distribution.

GenericTools

GenericTools is the set of classes that provide basic infrastructure for using tools in standard Java SE Velocity projects, as well as a set of tools for use in generic Velocity templates. Perenial favorites here are the DateTool, NumberTool and RenderTool, though there are many others available as well.

VelocityView

VelocityView includes all of the GenericTools structure and specialized tools for using Velocity in the view layer of web applications (Java EE projects). This includes the VelocityViewServlet or VelocityLayoutServlet for processing Velocity template requests, the VelocityViewTag for embedding Velocity in JSP and a Maven plugin to embed JSP tag libraries in Velocity templates. Popular tools here are the LinkTool and the ParameterTool.

What's new in 3.1

Velocity Tools 3.1 new features:

  • Added an optional 'factory' attribute to tools with the classname of a factory for creating new tools instances.
  • Added a new BreadcrumbTool meant to help displaying UI breadcrumb trails.

See the Upgrading section for a complete list of changes.

Sources Repository

All VelocityTools project code is maintained in the Apache gitbox repository and mirrored on github, see the downloads section.

Helping Out

Feedback about the project, whether positive or gently critical, is always helpful to those working on the project. Such feedback may be sent to either the user@velocity.apache.org or dev@velocity.apache.org mailing lists.

Another great way to help is to simply participate in conversations on the mailing list. On the user list, you can help answer questions that other users have. This frees the developers to focus on development more than user support. On the dev list, you can participate in design discussions and release votes to help maintain the high quality of the releases and direct the future directions of the project.

Contributions

Those interested in furthering the development of this project have an open invitation to jump in and help out. We welcome your contributions! Patches can be sent to the mailing list or attached to a [JIRA](http://issues.apache.org/jira/browse/VELTOOLS issue. The Wiki can also be a good place to discuss and develop ideas.

A few good places to get started include:

  • Documentation (patches for the site or additions to the Wiki)
  • Improving the example apps
  • Working on unresolved tasks in JIRA
  • Contributing to the VelocimacroLibrary

Code

When contributing code, it helps immensely if you follow through with the things on this checklist, especially the coding conventions. Keeping our code style consistent, our codebase stays easy to read and easy to patch. Adding javadoc (and examples therein) simplifies the documentation process and reduces confusion about the purpose of various methods and classes. Tests make sure that things work as expected, especially as development continues down the road. Of course, contributions that don't follow the checklist will be considered and often accepted, but you can expect the project committers to be slower and less enthusiastic in doing so. :)

Checklist for Code Contributions:

  • Velocity coding conventions
  • Javadoc included (the more detailed the better)
  • Examples included (in JavaDoc or as stand-alone template example)
  • Tests included (not required but GREATLY appreciated)