Custom Viewtool Example

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 org.apache.velocity.tools.view.tools.ViewTool 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 Velocity code.

Step 1: Create and Compile Your Java Class

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

package com.dotmarketing.plugins.hello.world;

import org.apache.velocity.tools.view.tools.ViewTool;

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) {

    }
}

Note: You must add your Java class to dotCMS as a plugin before it can be accessed as a Velocity Viewtool. Please see the section covering plugins for more information on the dotCMS plugin architecture, and the Javadocs for more on built-in classes and methods.

Step 2: Register Your Java Class as a Viewtool

In order to use you new viewtool from Velocity, you must register this Java class as a Velocity Viewtool by editing the WEB-INF/toolbox.xml file.

<tool>
    <key>helloWorld</key>
    <scope>application</scope>
    <class>com.dotmarketing.plugins.hello.world.HelloViewTool</class>
</tool>

Step 3: Call Your Java Class from Your Velocity Code

Once you Java class has been declared as a Viewtool in the Toolbox.xml file, you can call it 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:

$helloWorld.hello

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

$helloWorld.getHello("dotCMS")

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:

$helloWorld.getHello().substring(0,5)

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