Custom Velocity Viewtool Plugin

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, org.apache.velocity.tools, org.apache.velocity.tools.view, org.apache.velocity.tools.view.tools Provide-Package: com.dotmarketing.osgi.viewtools

Beware!

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

Source

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

$ pwd
/dotserver/docs/examples/osgi/com.dotcms.view.tool/src/com/dotmarketing/osgi/viewtools
$ ls -l
-rw-r--r--@ Activator.java
-rw-r--r--@ MyToolInfo.java
-rw-r--r--@ MyViewTool.java

com.dotmarketing.osgi.viewtools.MyToolInfo

Extends org.apache.velocity.tools.view.servlet.ServletToolInfo. 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;

import org.apache.velocity.tools.view.context.ViewContext;
import org.apache.velocity.tools.view.servlet.ServletToolInfo;

public class MyToolInfo extends ServletToolInfo {

       @Override
       public String getKey() {
               return "osgitool";
       }

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

       @Override
       public Object getInstance(Object initData) {
               MyViewTool viewTool = new MyViewTool();
               viewTool.init(initData);
               setScope(ViewContext.APPLICATION);
               return viewTool;
       }

};

com.dotmarketing.osgi.viewtoolsMyViewTool

Extends org.apache.velocity.tools.view.tools.ViewTool. 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;

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

public class MyViewTool implements ViewTool {

       @Override
       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:

$osgitool.getHelloMessage()

Activator

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.