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 and VelocityViewServlet) and integration with Struts 1.x applications.

In recognition of these varying aims, the VelocityTools project is divided into three parts: GenericTools, [VelocityView](view.html and VelocityStruts. 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 and the VelocityViewTag for embedding Velocity in JSP. Popular tools here are the LinkTool and the ParameterTool.

VelocityStruts¶

[VelocityStruts]struts.html includes both [VelocityView](view.html and GenericTools and adds tools for use in Struts 1.x applications. These tools match the functions of the key Struts taglibs and provide access to Struts resources, messages, tiles, validation functions and more.

It is worth noting that these tools, being POJOs (though some require a little configuration) are generally useful and may be used within your java classes or even other template languages, though you may need to instantiate and configure them manually (not difficult) to do so. VelocityTools 2 has been designed with this in mind. Ask on the user mailing list if you have questions about using VelocityTools without Velocity.

Why 2.0?¶

Those already familiar with VelocityTools 1.x may be curious about the goals and motivations behind developing VelocityTools 2. In planning and developing the 2.0 release, there were three main goals:

• Transparent, on-demand tool instantiation (aka lazy loading for tools) - This allows you to have many tools available (even ones that are expensive to instantiate), but not waste time instantiating or initializing/configuring those you don't use for every request.
• More accessible, reusable infrastructure - This allows easier access to tools outside of your templates and provides better means to integrate VelocityTools support into other web frameworks or even other view technologies (e.g. VelocityViewTag).
• Simpler, more flexible toolbox configuration - Now you can configure via a properties file, plain java, or really whatever you want (though perhaps with a bit more work). No XML required anymore; though, if you do use it, it's now a lot better than it was.

These things could not have been accomplished without rewriting most of the core infrastructure and configuration code. At the same time, we wanted to make it easy for people to upgrade from the 1.x series. This led to the decision to aim for complete backwards compatibility. Granted much has been deprecated and those who directly used or extended the 1.x infrastructure will have to update their code in just a few releases, but for the time being they should be able to use 2.0 in their applications with few problems. Those who merely used the old toolbox.xml format or the old tools directly will be immediately able to take advantage of the new infrastructure without even updating their configuration, though eventually even the old toolbox.xml format may be retired. Don't cry. You'll like the new one better once you get to know it! It can do much more with much less typing.

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

Other project goals and proposals can be found in the project STATUS[http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/STATUS?view=markup] file.

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)