Version Comparison: Building Plugins

By building plugins, you can add new features to Clearspacethe application. This includes new widgets and other UI features, as well as back-end components such as web services or custom authentication providers.

Getting Sample Code

You can use Jive's public Subversion repository to get sample code. Check out the code at the following URL: https://svn.jivesoftware.com/svn/dev/repos/jive/

What You Can Do With Plugins

With a plugin, you can add new features to Clearspace. The plugin framework supports several kinds of components.

• With widgets, Clearspace users can customize the application's overview pages to display the content they want. You can build widgets that give the specialized windows into content and other data.
• Macros provide easy ways to enhance content while editing it. In the content editor, the Insert menu displays macros. (Note: This release doesn't support adding new macros. You'll be able to develop your own in a coming release.)
• Actions can add new links and pages to the user interface.
• Many Clearspace features are implemented as Spring beans. You can override these or provide your own. One example is to override security-related beans. For more information, see Authentication and Authorization.
  

What You Can Do Without Plugins

If you're writing a web service client, you don't need a plugin. For more information, see the REST Web Services Reference and the SOAP Web Services Developer Guide.

Requirements

To write Clearspace plugins you'll need the following:

• An instance of Clearspace to test and debug against, deployed on a supported environment. Take a look at the installation guide for details on supported environments. For example, you'll need to use Java 6 (JDK 1.6).
• (Optional) Building plugins is easier if you use Maven, a Java build tool. Like Ant, Maven provides a way to account for dependencies and to compile your source files.
• (Optional) A Java IDE. Jive Software recommends development environments such as JetBrain's IntelliJ IDEA or Eclipse. You can use Maven to quickly create plugin projects for use with these tools. (Of course, plain text editors like vi or Emacs will work just fine as well.)

Packaging and Deploying a Plugin

However you get your plugin to its finished state, you'll deploy it as a JAR file. When you deploy, Clearspace the application expects the contents of your JAR file to be in a particular hierarchy. Here's a snapshot of how the contents might look:

Configuring a Plugin

Your plugin.xml file contains nearly all of the high-level information about what's included in your plugin. What's not described here could include any Spring beans you're overriding or database tables you're adding.

You'll find references for plugin.xml file elements in Plugin XML Reference and UI Components XML Reference.

<plugin>     <!--         Top-level information: overall plugin name and description,         its version, and the earliest Clearspaceapplication version on which         it's supported.     -->     <name>helloworld</name>     <description>Hello World</description>     <author>ACME Plugins</author>     <version>1.0.0</version>     <minServerVersion>2.1.0</minServerVersion>     <!--         Widgets are user interface components that people can         use to customize parts of the UI. The class attribute         points to the Java class that provides the widget's logic.     -->     <widget class="com.example.clearspacesbs.widgets.CoolWidget"/>     <!--         You can write web services that expose parts of Clearspacethe application         not available as web services by default.     -->     <webservice class="com.example.clearspacesbs.webservices.HandyService"/>     <!--         Specifies that this plugin includes a CSS stylesheet that         should be used throughout the application. This is good         way to add a global CSS class or override one already         included with Clearspacethe application.     -->     <css src="/acme_styles.css"/>     <!--          Key and value for indicating whether database changes are          needed on upgrade.     -->     <databaseKey>helloworld</databaseKey>     <databaseVersion>1</databaseVersion>         <!--         Aside from widgets, you can add elements to the user interface         with Struts actions. You integrate into the UI here, then define         the action itself     -->     <components>         <!--             <component> elements define user interface elements             to be integrated. For a description of these, see             Integrating Plugin UI with Clearspace. This one adds             an Action box link to a user profile; this will be             seen by visiting users, rather than the profile's owner.         -->         <component id="profile-actions">             <tab id="profile-actions-tab">                 <item id="profile-actions-link" name="Example profile action">                     <url>                         <![CDATA[<@s.url value="/example-profile.jspa?userID=${targetUser.ID}"/>]]></url>                 </item>             </tab>         </component>     </components>     <!-- A class that handles Clearspace lifecycle events. -->     <class>com.jivesoftware.plugins.MyPluginLifecycle</class> </plugin>

Handling Lifecycle Events

You can write a class that handles events from the Clearspace application lifecycle. Your lifecycle class implements the interface com.jivesoftware.base.plugin.Plugin, which has two methods: init and destroy. Use the init method to perform actions (such as create connections to resources) that your plugin will likely need throughout its life. Use the destroy method to release resources and perform actions that are the last things your plugin should do.

You specify the presence of a lifecycle class with the plugin.xml class element:

<class>com.example.plugin.MyPluginLifecycle</class>

Adding Database Access

You add database tables to support your plugin. When adding database support, you plug into the Spring context by creating data access object (DAO) Spring beans. You add your tables through a schema.xml file.

For more on adding database access to your plugin, see Accessing the Database from a Plugin.

Deploying Plugins

The best way to deploy a plugin is by using the admin console. In the console, go to System > Plugins > Add Plugin.

Note that whenever you add or remove a plugin, you'll need to restart the application server.