Toolbox.xml - Documentation topics on: tab-libs,taglib,toolbox,toolbox.xml,velocity,viewtool,viewtools,.

Toolbox.xml

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:

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:

ValueDescription
applicationThe Viewtool will be a Singleton within the Application and should be thread safe.
The object is instantiated once and reused across requests and contexts.
requestAn 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.
sessionAn 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.