Custom Velocity Viewtool Plugin

Last Updated: Jun 13, 2019
documentation for the dotCMS Content Management System

This bundle plugin is an example of how to create a Viewtool and register it in Velocity's context.

How to create a bundle plugin using viewtools

Let’s review the file organization on the Viewtool (com.dotcms.viewtool) example:

META-INF/MANIFEST.MF: The manifest file is very important for the deployment, it lists the Bundle Name, Version and Packages.

In this MANIFEST you must specify (see template plugin):

  • Bundle-Name: The name of your bundle
  • Bundle-SymbolicName: A short an unique name for the bundle
  • Bundle-Activator: Package and name of your Activator class (example: com.dotmarketing.osgi.servlet.Activator)
  • Import-Package: This is a comma separated list of package's name. Lists the packages that you are using inside the bundle plugin and that are exported by dotCMS at runtime.

$ more MANIFEST.MF Manifest-Version: 1.0 Bundle-Name: Osgi View Tool Bundle-Activator: com.dotmarketing.osgi.viewtools.Activator Bundle-SymbolicName: Osgi View Tool Bundle-Version: 1.0.0 Bundle-RequiredExecutionEnvironment: OSGi/Minimum-1.0 Import-Package: com.dotmarketing.osgi,,, Provide-Package: com.dotmarketing.osgi.viewtools


In order to work inside the Apache Felix OSGI runtime, the import and export directive must be bidirectional.

dotCMS must declare the set of packages that will be available to the OSGI plugins by changing the file: dotCMS/WEB-INF/felix/osgi-extra.conf.

This is possible also using the dotCMS UI (**Dev Tools -> Plugins** and click **Exported Packages**).

Only after exported packages are defined in this list, a plugin can Import the packages to use


Under the src folder you will find all the Java classes needed to create a new Viewtool:

$ pwd
$ ls -l


Extends This class will add your Viewtool to Velocity’s content through the toolbox. You will need to create a new key for your viewtool and return it on getKey() method.

package com.dotmarketing.osgi.viewtools;


public class MyToolInfo extends ServletToolInfo {

       public String getKey() {
               return "osgitool";

       public String getClassname() {
               return MyViewTool.class.getName();

       public Object getInstance(Object initData) {
               MyViewTool viewTool = new MyViewTool();
               return viewTool;



Extends This is a viewtool class same as all provided in dotCMS under the: com.dotmarketing.viewtools package. This class will expose all public methods to be used in Velocity. In the example, this class creates two public methods: getHelloMessage() and getHelloMessage(String name).

package com.dotmarketing.osgi.viewtools;


public class MyViewTool implements ViewTool {

       public void init(Object initData) {

       public String getHelloMessage() {
               return "Hello dotCMS World";

       public String getHelloMessage(String name) {
               return "Hello " + name;


These methods can be called from Velocity by doing:



This bundle activator extends from com.dotmarketing.osgi.GenericBundleActivator and implements BundleActivator.start().

Gets a reference to the MyToolInfo class and registers the MyViewTool viewtool.

On this page


We Dig Feedback

Selected excerpt: