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.
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.