Developing Teaming 2.1 Extensions

Teaming will allow application developers to bundle definition and template XML, custom workflow classes that implement the workflow action and condition interfaces, custom JSPS and other web visible resources needed by the application browser interfaces.

The Extension structure:

Application developers create a zip file containing their extension files. The zip file should have a relative directory structure that mirrors the layout of the teaming <tomcat>/webapps/ssf directory.

• Extension meta data is at the root of the archive and contains information about the extension
• Web visible resources (graphics, static html pages, js, css) are stored at the top level. You may include any directory structure that makes sense.  For example, creating a js directory at the root of your archive to contain all of your javascript files.
• Templates should be stored under WEB-INF/classes/config/templates.
• Definitions under WEB-INF/classes/config/definitions.
• Jsps under WEB-INF/jsp
• Jar files under WEB-INF/lib. Individual class files will not be supported, they need to packaged in a jar.

After deploying your extension through the Manage Extensions interface in Teaming's site administration, the extension manager will deploy the extension to a location under your data directory, then it will recognize the new extension and unpack it. The extension name will be the name of the zip file. The WEB-INF contents will be extracted to ssf/WEB-INF/ext/'zoneKey'/'extensionName' and the web visible components will be extracted to ssf/ext/'zoneKey'/'extensionName'. The definitions and templates are loaded into the system at this time. The extension's name is added to all definitions prior to adding them to the system. This name is used during runtime processing of jsps.

Examples:

Here are 2 examples of the archive format.  The first example includes externally referenced files in the swf/, img/, and js/ directories.  The second references everything from within the WEB-INF directory.

Archive: VideoEntry.zip

Path Names
------------------

install.xml
js/
js/flashembed.min.js
swf/
swf/FlowPlayerClassic.swf
swf/FlowPlayerLight.swf
swf/FlowPlayerLP.swf
swf/FlowPlayerDark.swf
WEB-INF/
WEB-INF/classes/
WEB-INF/classes/config/
WEB-INF/classes/config/definitions/
WEB-INF/classes/config/definitions/VideoEntry.xml
WEB-INF/classes/config/definitions/VideoFolder.xml
WEB-INF/classes/config/templates/
WEB-INF/classes/config/templates/Video Folder Template.xml
WEB-INF/jsp/
WEB-INF/jsp/view.jsp
img/
img/no-flash.png
img/no-flash.svg

Archive:  twitter.zip

Path Names
------------------
install.xml
WEB-INF/
WEB-INF/classes/
WEB-INF/classes/config/
WEB-INF/classes/config/definitions/
WEB-INF/classes/config/definitions/_user.xml
WEB-INF/classes/config/definitions/pubToTwitter.xml
WEB-INF/src/
WEB-INF/src/TwitterWorkflowAction.java
WEB-INF/lib/
WEB-INF/lib/TwitterExtension.jar
WEB-INF/lib/commons-httpclient-3.1.jar
WEB-INF/lib/twitter4j-2.0.8.jar
WEB-INF/jsp/
WEB-INF/jsp/password.jsp

Extension Meta Data:

An install.xml file should contain the following information.

<?xml version="1.0" encoding="utf-8"?>
<extension version="1.0" >
<title>Twitter Extension</title>
<author>Author's Name</author>
<creationDate>August 27 2009</creationDate>
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
<authorEmail>nbjensen@novell.com</authorEmail>
<authorUrl>www.mysite.com</authorUrl>
<description>This Plugin is a sample.</description>
<usage>Instructions on how to use this extension.</usage>
</extension>

Runtime:

custom jsps

When an item in a definition is processed that has a custom jsp, the extension name and current zone are used to locate the jsps. Control then passes to the jsp and processing continues as always.

Locating web visible resources

A new jsp tag is needed for the custom jsps to access the web visible components of the extension The tag is named ssf:extensionUrl. It generates the http(s) url need to locate the base of the extensions directory under ssf.

Locating custom classes

In order to 'hot deploy' extensions into a running Tomcat instance we need a custom class loader. This class loader will be used to make extension jar files visible to the running system. We need 1 class loader per zone. The class loader is only used when custom workflow classes need to be instantiated and run. At the end of the workflow processing the system class loader will be restored. On startup the class loader will add the jar files of all deployed extensions to its classpath. When new extensions are deployed they will be dynamically added to the classpath. If an existing extension is redeployed, a new class loader will be created and all deployed extensions added again. The old class loader will be de-referenced and should be garbage collected by the system.

How to deploy:

To deploy an extension log in to Teaming as a site admin and do the following:

1. Go to Manage -> Site Administration -> Manage Extensions -> Add a new extension
2. Browse to your zip file
3. Click Add
4. Your done

Configure:

Now that you deployed your extension you will need to configure Teaming to use your extension.  Each extension should come with it own set of configuration instructions on how to use the extension.

Landing Pages:

When using an extension in a landing page:

1. Go to your landing page
2. Manage -> Modify this workspace
3. Edit the custom jsp
4. * Enter <extension name>/jsp/<jsp file name.jsp>
5. Click OK
6. Click OK on the page

* Note:  You can see the list of files deployed with your extension in the Site Admin -> Manage Extensions by clicking on the extension name in the deployed extensions list.

Manual deployment:

To deploy an extension manually, copy the zip archive to the location on the host filesystem that is defined in the ssf.properties (or ssf-ext.properties) under the variable, data.extension.root.dir.  This directory will have a thread monitoring it, any zip archives copied here will be deployed every 5 minutes or so.  Archives will also be deployed on startup of the instance.

Updating Extensions:

If you update your extension with newer code or resources, simple update the install.xml and any files you want to update and repackage them by zipping them up with the same name as your original extension.  Then  follow the same steps to deploy your extension and the extension manager will automatically update your extension files with the lastest files from your newly deployed extension.

Additional Info:

See the Extension Specification here.

IMPORTANT Delete:

Delete is currently implemented, however, if the extension has definitions are in use by binders or entries then it will not allow the deletion of the extension.  If you still need to remove the extension, you will have to manually delete the files and definitions.

Not included:

Extension management currently does not address the deployment of remote applications, nor specify a UI for adding, removing or managing extensions.