Clearspace Plugin Development Guide 

Clearspace is a flexible and pluggable application. This document describes one aspect of customization, the plugin framework. Developers can use the plugin framework to execute arbritrary Java code and call the Clearspace APIs, as well as extend or override UI functionality.

• System Requirements
• Plugin Structure
• Creating a New Plugin
• Creating Views with Plugins
• Database Access

System Requirements

To write Clearspace plugins you'll need the following:

• A source, binary or standalone build of Clearspace. This is available from your customer account on the Jive Software website.
• The Java 5 SDK. This is available on many platforms, mainly from the main Java site or from other vendors like Apple. Make sure your JAVA_HOME environment variable is set correctly.
• (Optional) If you're using just the binary or standalone release, you'll need to have Ant installed and available in your PATH.
• (Optional) A Java IDE. Jive Software recommends development environments such as JetBrain's IntelliJ, Eclipse or TextMate. (Of course, plain text editors like vi or Emacs will work just fine as well.)

Plugin Structure

It's important to understand the parts of a plugin. The following is a list of the contents of an example plugin:

• plugin name: In this case "helloworld" is the name of the plugin.
• classes: Java classes are compiled in to this directory.
• PNG images: The two images (logo_large.png, logo_small.png) are optional and act as the plugin icon for the Clearspace admin console.
• plugin.xml: Metadata file for the plugin. Describes main class, resources, mappings and other properties.
• resources: Contains web resources and templates.
• schema.xml: An optional database definition. This will automatically install any tables your plugin uses.
• src: All Java code for the plugin.
• xwork-plugin.xml: A mapping file for any Webwork actions you create.

Creating a New Plugin

Create a new directory under the plugin directory named the plugin name. This will be the base directory of the plugin. All source code will go under the src directory, class files will be compiled to the "classes" directory. All plugins can be compiled using the build.xml inside the build directory by using the "plugins" target. All plugins will be deposited to the "target" directory. Note, it's possible to compile just one plugin by doing "ant plugin -Dplugin=name".

Implement the Plugin Interface

The first step to creating a plugin is to implement the com.jivesoftware.base.plugin.Plugin interface. The interface has two methods to implement: initializePlugin and destroyPlugin.

public class HelloWorldPlugin implements Plugin {

    public void initializePlugin(PluginManager manager, File pluginDirectory) {
        Log.info("Hello World!");
    }

    public void destroyPlugin() {
        Log.info("Good bye cruel world!");
    }

}

Configure

The core plugin configuration is contained in a plugin.xml file. You need to put this file in the root directory of the plugin. This XML file contains the plugin name, plugin class name, version information, and other metadata.

<plugin>
    <class>com.jivesoftware.helloworld.HelloWorldPlugin</class>
    <name>helloworld</name>
    <description>Hello World</description>
    <author>Jive Software</author>
    <version>1.0.0</version>
    <minServerVersion>1.0.0</minServerVersion>
    <databaseKey>helloworld</databaseKey>
    <databaseVersion>1</databaseVersion>
</plugin>

Deploy

Once the plugin.xml is configured, you can deploy the plugin. Use the build/build.xml and its plugin task to build the JAR file under the target/plugins directory. Next, copy this JAR file to your jiveHome/plugins directory. The plugin will be automatically deployed once it is placed inside the directory. You don't need to restart your application server.

Creating Views with Plugins

You can create new pages using WebWork and FreeMarker templates. Also, you can override existing pages by overriding both the WebWork namespace and action name.

Using WebWork

WebWork configuration can be done in the xwork-plugin.xml. To create an action for the admin tool, community-admin-default package; otherwise, extend the community-default package. All pages must be written in FreeMarker. URLs to pages must contain /plugins/<pluginname> in front of the URL. See the following example:

<xwork>
    <package name="helloworld" namespace="/admin" extends="community-admin-default">

        <action name="hello" class="com.jivesoftware.helloworld.HelloWorldAction">
            <result name="success" type="freemarker">/plugins/helloworld/resources/helloworld.ftl</result>
        </action>

    </package>
</xwork>

Using FreeMarker

FreeMarker pages should be placed in the directory resources, along with any other images, etc. When referencing images with pages you should add the prefix /plugins/<pluginname> to the resources and use the ww.url WebWork FreeMarker transform:

<html>
    <head>
        <#assign pageTitle="Hello World" />
        <title>${pageTitle}</title>
        <content tag="pagetitle">${pageTitle}</content>

        <content tag="pageID">settings-binarybody</content>
        <content tag="pagehelp">
            <h3>${pageTitle}</h3>
            <p>
                This is the hello world test plugin
            </p>
        </content>

    </head>
    <body>

    <p><img src="<@ww.url value='/plugins/helloworld/resources/logo_small.png' />" alt=""/> ${message}</p>

    </body>
</html>

The following Clearspace utilities are always available to FreeMarker plugin pages.

Database Access

Schema Installation Scripts

Database schema installation is performed by using SQLGen. SQLGen uses an XML format for table descriptions. There should be a file called schema.xml placed in the plugin home. Its format is as follows:

<schema name="Hello World">
    <table name="HelloWorld" description="Hello World Table">
        <column name="hwID" type="bigint" nullable="false" description="Primary Key"/>
        <column name="name" type="varchar" size="255" nullable="false" description="The name"/>
        <index type="primary" name="hw_pk" column="hwID" />
    </table>
</schema>

Acquiring Database Connections

Database connections can be acquired by accessing the static getConnection() method of the com.jivesoftware.base.database.ConnectionManager class. This method will return a new connection from the underlying database pool. The connection must be released properly after use:

Connection con = null;
PreparedStatement psmt = null;
try {
   con = ConnectionManager.getConnection();
   ....
}
finally {
   ConnectionManager.close(psmt, con);
}

Note, the ConnectionManager has a number of overloaded close(..) methods.