All Viewtools are actually just POJOs (Plain Old Java Objects) that are mapped to the Velocity context in dotCMS. You can think of Viewtools as Java “taglibs” for velocity; just as taglibs expose Java methods to JSPs, Viewtools expose Java methods to Velocity.
You should never need to edit this file, though it can be useful as a key name reference.
Mapping Java Objects as Viewtools
Viewtools are mapped in the toolbox.xml file, which is located in the WEB-INF folder in your dotCMS distribution:
$ROOT/WEB-INF/toolbox.xml
To map a Java class as a Viewtool, you must specify all of the following:
- A key
- A scope
- The Java class that the viewtool maps to
Example Mapping: MathTool
The following example shows how the Apache MathTool Velocity Viewtool is mapped in the toolbox.xml file:
<tool>
<key>math</key>
<scope>application</scope>
<class>org.apache.velocity.tools.generic.MathTool</class>
</tool>
Key
The key specifies how the Java class can be referenced within your Velocity code. You may access the Java class by prepending the key with a $. So, for example, to call the MathTool (which has a key of math), you would write $math followed by the property or method of the MathTool class that you want to access (such as $math.toInteger()).
Scope
The scope defines when an instance of the tool will be instantiated. It takes one of three possible values:
| Value | Description |
|---|---|
application | The Viewtool will be a Singleton within the Application and should be thread safe. The object is instantiated once and reused across requests and contexts. |
request | An instance of the Viewtool is instantiated with every request. Request Viewtools have access to the server's HttpServletRequest and HttpServletResponse objects and can call methods in those objects in their code. |
session | An instance of the Viewtool is instantiated and stored in the user session. |
Java Class
The class value is just the fully qualified class name (please see the MathTool mapping above for an example).
Important Notes:
- For a Java class to be mapped as a Viewtool, it must be added to dotCMS (usually as a plugin).
- The easiest way to develop and add custom Viewtools to your dotCMS installation is to create an OSGi plugin.
- For more information, please see the Example Plugin: Custom Velocity Viewtool documentation.
