The servlet configuration (web.xml) must be modified to include a reference to the special Velocity-based servlet which will perform the rendering. All *.vm files are mapped to this servlet which will populate the 'context' with Request, Session, and Application scopes plus additional tools specified in the toolbox.xml file. The servlet will use this contextual information and the Velocity Engine to render the template file.

Note: Additional functionality can be achieved through subclassing this servlet, and will be discussed further in the VelocityLayoutServlet below.

web.xml

<!-- Define Velocity template compiler -->
<servlet>
  <servlet-name>velocity</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>

  <init-param>
    <param-name>org.apache.velocity.properties</param-name>
    <param-value>/WEB-INF/velocity.properties</param-value>
 </init-param>

 <load-on-startup>10</load-on-startup>
</servlet>

<!-- Map *.vm files to Velocity -->
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

Velocity configuration is optional, and for most applications the defaults will work fine. The velocity.properties file contains settings that affect logging, encoding, and macro settings.

The default configuration specifies the location of a 'global' Velocimacro template. This file can contain macros which will be made available to all templates.

The location of the configuration file is specified in web.xml, and it is recommended the file be placed inside the hidden WEB-INF directory of the web application. An example configuration file is included with the distribution.

Please see the Velocity User's Guide for more information on Velocity configuration.

  velocimacro.library = /WEB-INF/VM_global_library.vm
  velocimacro.permissions.allow.inline = true
  velocimacro.permissions.allow.inline.to.replace.global = false
  velocimacro.permissions.allow.inline.local.scope = false  
  velocimacro.context.localscope = false

The toolbox file, WEB-INF/toolbox.xml in our example, maps names of our choosing to the classes that they will represent. It's easier than that sounds.

Think about asking our friend Jon to grab us a 'wrench' from a real toolbox. Jon just needs to know which wrench we want (metric, pipe, crescent etc,). He doesn't need to know what the wrench does nor what we are planning to do with it.

The Velocity Toolbox works the same way, we must only specify which tool to assign to a name, and then the Velocity engine takes care of the rest by making any public method available to the template. For example, from the definitions below, the template could call $wrench.getSize() or $wrench.size .

PipeWrench.java

public class PipeWrench {
  public String getSize() {
	return "Large Pipe Wrench!";
  }
} 

toolbox.xml

<?xml version="1.0"?>
<toolbox>
  <tool>
     <key>wrench</key>
     <scope>application</scope>
     <class>PipeWrench</class>
  </tool>
</toolbox>

Tool Scopes

The toolbox support built into the VelocityViewServlet also provides support for specifying the scope of your tool with regards to the servlet environment. Tools may be placed within the request, session, or application scopes of your web app.

The scope that you set for your tool will determine both its lifecycle and, if it implements the ViewTool interface, then the scope will also determine what data is passed to the init(Object) method:

• application scoped tools will be instantiated only once and then reused for each request. Due to this, it is strongly encouraged that your application scoped tools be completely threadsafe. The MathTool in the GenericTools section is a good example of tool meant to be application scoped. If an application scoped tool implements ViewTool, then the javax.servlet.ServletContext for the webapp will be passed to its init(Object) method after it is instantiated.
• session scoped tools are instantiated once per unique session and are then reused for every request associated with that particular session. If a session scoped tool implements ViewTool, then its init(Object) method will be passed the ViewContext of the request during which the session was created.
• request is the default scope. If no scope is specified for a <tool> in your toolbox.xml, then it will be automatically set as request scope. Tools with this scope are instantiated for every servlet request fed to the VelocityViewServlet. If a request scoped tool implements ViewTool, then its init(Object) method will be passed the current ViewContext.

You can specify the scope of your tools by adding a <scope> element to your toolbox.xml entries like this:

<tool>
   <key>math</key>
   <scope>application</scope>
   <class>org.apache.velocity.tools.generic.MathTool</class>
</tool>

Tool Parameters

The toolbox support built into the VelocityViewServlet also provides support for passing configuration parameters to tools that implement the Configurable interface. This interface consists of only a void configure(java.util.Map params) method which will only be called if parameters have been specified for the tool.

You can specify parameters for your tools by adding a <parameter> element to your toolbox.xml entries like this:

<tool>
   <key>math</key>
   <scope>application</scope>
   <class>com.foo.tools.MyTool</class>
   <parameter name="my.parameter.name" value="my.parameter.value"/>
</tool>

Toolbox Data

In addition to specifiying arbitrary Java classes as tools to be automatically available to your templates, the toolbox support also includes the ability to specify arbitrary strings, booleans, and numbers to be automatically available in your templates. The format is as follows:

<?xml version="1.0"?>
<toolbox>
  <data type="number">
     <key>app_version</key>
     <value>0.9</value>
  </data>
  <data type="string">
     <key>app_name</key>
     <value>Jon's Tool Shop</value>
  </data>
  <data type="boolean">
     <key>debug</key>
     <value>true</value>
  </data>
</toolbox>

As with your tools, your data will be exposed to your templates under the specified key (e.g. $app_version, $app_name, $debug).