Custom Viewtool Example documentation for the dotCMS Content Management System

Velocity Viewtools give you access to tools and methods which perform useful functions and give you access to dotCMS objects. dotCMS provides a number of built-in Viewtools which you can use out-of-the-box, including a number of Viewtools which are provided as part of the core Apache Velocity package, and many more which give you additional functions and access to dotCMS content and objects.

In addition to the built-in Viewtools, you can create your own Viewtools. A Viewtool is really just a way to access a Java class from within Velocity code; you can thus create a Viewtool from any Velocity class, by adding it to dotCMS as a plugin, and adding just 5 simple lines of text to the Toolbox.xml file. Viewtools provide the easiest way to extend Velocity using Java code.

A Java class which will be used as a Viewtool must implement the interface. Methods and properties in the class can then be called via Velocity. These properties and methods can return other java objects that can be called in your template.

The following is a simple example of a Viewool java class:



public class HelloViewTool implements ViewTool {

  public String getHello() {
    return "Hello World Viewtool";

  public String getHello(String myName) {
    return "Hello " + myName ;

    public void init(Object obj) {


In order to use you new viewtool from Velocity, you must register in the WEB-INF/toolbox.xml file.


Once declared in the Toolbox.xml file, you can call your new Viewtool in the same way as you call all other Viewtools that come with the system.

For example, given the above Java class and Toolbox.xml definitions, the following code:


would print out “Hello World Viewtool“, and the following:


would print out “Hello dotCMS“.

Keep in mind that Viewtools return java Objects, which can be interacted with in Velocity. For example, if we just wanted to say “Hello”, we could call:


which would call the substring method of the String Object and print out “Hello“.

When customizing dotCMS, keep in mind that all this work can and should be done via plugins. See the section on “Development” for more information on the dotCMS plugin architecture.