VelocityTools is not meant to be a framework in itself, but rather should ideally be integrated with other frameworks for applications of much size. The simplest means of integration is to have your framework handle requests, placing contextual data into the request, session or servlet context attributes where templates and/or tools can find them, then forward those requests to a VelocityViewServlet or VelocityLayoutServlet, letting those servlets manage your VelocityView support for you and render your templates into the response. If, however, your framework is one like Spring MVC and you either cannot or do not wish to forward requests to one of the provided servlets, then the instructions, tips and code below should make it easy for you to integrate VelocityTools support into your framework of choice.
VelocityView supports the following configuration parameters as <init-param>s in web.xml:
/WEB-INF/velocity.properties. If no file is found there, then Velocity is initialized with the settings in the classpath at
The VelocityView instance is typically the heart of any VelocityTools-using application. It encapsulates all necessary VelocityEngine and ToolboxFactory configuration and provides a simple API for processing templates or other VTL (e.g. VelocityViewTag body content).
You can, of course, simply create a VelocityView instance
for your framework to use, but if you are supporting multiple
ways of using Velocity (e.g. VelocityViewTag and separate templates)
or if you suspect your users might want access to the VelocityView
facilities, it is better to get your VelocityView instance using
the getVelocityView(...) methods of the
These methods will automatically create an instance, store it for
you, return it, and then retrieve it again on subsequent calls to
any of those methods. This allows the VelocityView (which is a
rather heavy object) to be shared across multiple
servlets, tags, and filters in the same application. Of course,
if you do not wish to share your VelocityEngine configuration
(template cache, global macros) or Toolbox configuration(s),
then you should explicitly avoid using these methods and
construct and manage your own VelocityView instance.
If you are using VelocityViewServlet, VelocityLayoutServlet,
and/or VelocityViewTag in the same application and do not want
them to share a VelocityView instance for some reason, you
can tell them to keep their VelocityViews private by setting
false in the
init-params of the
The so-called "standalone" methods of tool use developed from a desire to use tools directly, particularly the GenericTools which had no servlet dependencies. However, now many VelocityView tools can also be used "standalone" with varying degrees of effort and no need to create any VelocityView instances. Most of the time, you just treat them like any other POJO--create an instance, provide any need values/objects and use it.
If you want a little more help with things, consider using a ToolManager.