Developing Custom DeskClient Plugins

This tutorial describes in short how to develop custom Sophora DeskClient plug-ins.

Table of Contents

Introduction

The Sophora DeskClient is a rich client application based on the Eclipse RCP framework. Therefore it is possible to extend it with custom plug-ins. This tutorial describes in short when and how to develop your own custom plug-in and how to deploy it to your users. The tutorial does not explain the Eclipse IDE, the Eclipse RCP, the Standard Widget Toolkit (SWT), JFace, or the administration of a Sophora installation (see References).

Preconditions

For developing your own Sophora DeskClient plug-in you need:

When Do I Need A Custom Plug-In?

Typically you need a custom plug-in if users have to link or paste contents from external sources into Sophora documents directly and in a comfortable way, or if (complex) contents have to be edited in a way the Sophora DeskClient does not support yet (e.g. using a special input field).

You should make sure that Sophora does not already support your demands before you begin developing your own plug-in. In many cases you can use

  • fields based on select values
  • dynamic tables
  • custom property tabs
  • custom browser tabs
  • scripts (client scripts, validation scripts, ...)
  • ...

What Can Be Extended By A Custom Plug-In?

Because the Sophora DeskClient is an Eclipse RCP application, it is theoretically possible to extend everything that is extendable by the Eclipse RCP. This includes the main menu, main toolbar, editors, views and so on, e.g. by the Eclipse extension points:

  • org.eclipse.ui.views
  • org.eclipse.ui.editors
  • org.eclipse.ui.actionSets
  • org.eclipse.ui.commands
  • ...
Please note that the Sophora DeskClient does not support an anchor point for third party plug-ins in every menu like the Eclipse RCP does.

Moreover the Sophora DeskClient provides its own extension points for

  • custom input field types
  • editor tabs for the Sophora document editor, and
  • custom (background) jobs running at startup of the DeskClient.

Sophora DeskClient extension points:

  • com.subshell.sophora.eclipse.formInputFields (see Adding Form Input Field Types)
  • com.subshell.sophora.eclipse.editorComponents (see Adding Editor Components)
  • com.subshell.sophora.eclipse.workbenchStartupJobs (see Adding Startup Jobs)

Architecture

Setting Up Your Development Environment

Before you can begin developing a plug-in for the Sophora DeskClient, you have to create a corresponding Eclipse target platform. This platform must contain at least the Sophora DeskClient and additional plug-ins if required, e.g.:

  • Eclipse SDK 4.5.1
  • DeltaPack 4.5.1 (for independent development on/for several platforms, e.g. Windows (32bit/64bit), Linux (32bit/64bit), Mac (32bit/64bit))
  • Babel Language Packs (for the languages you want to support)
  • Any other plug-ins and features your custom plug-in will need

After downloading, extract all the archive files into one folder, e.g. called "[...]/targetplatform", so that you finally have one folder "[...]/targetplatform/eclipse" (overwrite existing files when extracting the archives, if necessary).

Because you want to develop a plug-in for the Sophora DeskClient you will need the Sophora DeskClient in your target platform as well. Extract it to the same "[...]/targetplatform" directory, so you have a folder "[...]/targetplatform/DeskClient".

Now start your Eclipse IDE with a new, fresh and empty workspace. Navigate to Preferences > Plug-in Development > Target Platform and configure a new target platform (e.g. called "Sophora DeskClient Target Platform"), containing only the two folders "[...]/targetplatform/eclipse" and "[...]/targetplatform/DeskClient".

Afterwards create a new Run Configuration for an Eclipse Application. Give the configuration a speaking name like "Sophora DeskClient" and set the product to run to "com.subshell.sophora.eclipse.product" on the Main tab.

Switch to the Plug-ins tab, set Launch with to plug-ins selected below, deselect the whole Target Platform, select all com.subshell.sophora.eclipse.* plug-ins and press the Add required Plug-ins button.

If you now run the application the login dialog of the Sophora DeskClient should appear. A successful login to a running Sophora server completes the setup.

An Example Custom Plug-In

The following custom Sophora DeskClient plug-in provides two new input field types to the Sophora document editor. These fields are for selecting a single person or several persons out of a third party (dummy) database.

Furthermore the plug-in provides a new Sophora Document Editor tab for a custom UI to edit parts of a Sophora document.

A background job running at startup of the Sophora DeskClient (e.g. for filling a cache) is also contained.

Finally a custom view has been added to the view menu and next to the bookmarks view.

Download The Example Plug-In

Download:

There are three Eclipse projects in the archive:

  • The example Sophora DeskClient plug-in (com.subshell.sophora.eclipse.example),
  • a feature project (com.subshell.sophora.eclipse.example-feature) and
  • an update site project (com.subshell.sophora.eclipse.example-site).

Run The Example

To run the Sophora DeskClient with the example plug-in:

  • Set up your development environment like described in Setting Up Your Development Environment.
  • Download the example projects archive (see Download The Example Plug-In) and import the contained Eclipse projects into your Eclipse IDE workspace.
  • Add the example plug-in to your Run configuration and start the Sophora DeskClient from within your Eclipse IDE.
  • Connect to a running Sophora server as administrator.
  • Navigate to the Administration view and import the node types and node type configuration files you can find in the example Sophora DeskClient plug-in project in folder "[...]/com.subshell.sophora.eclipse.example/nodetypes".

Now you can create a new Sophora document that contains the new input field types and editor tab added by the example plug-in using File > New > Demo > Extended fields.

Creating A Custom Plug-In

If you create your own plug-in project it is necessary that your plug-in depends on the com.subshell.sophora.eclipse plug-in to use the Sophora DeskClient extension points and classes. Do not forget to add your plug-in (and all its dependencies) to the Run Configuration created in Setting Up Your Development Environment. Otherwise your custom plug-in will not be started within the Sophora DeskClient if you run the product from within the IDE.

Adding Input Field Types

The Sophora document editor works with two kinds of input field types:

  • Form Input Fields: "Simple" input fields that can read/write values from/to a single-value or a multiple-value property of a Sophora document.
  • Editor Components: "Complex" input fields, that can read/write values from/to existing or new child nodes of a Sophora document.

Adding Form Input Field Types

If you only want to read and write single data in Sophora documents, you can handle this with a simple property in the document's node type. To add new input field types working on properties your plug-in has to extend the extension point com.subshell.sophora.eclipse.formInputFields and add a formInputField for each new field. Every form input field type needs a unique ID (unique in plug-in scope) and a human-readable name. The ID is stored internally and the name is displayed in the node type configuration when configuring the field type for a node type's property. Moreover the form input field type has to declare which property type(s) it supports (e.g. string, boolean, date, ...; single or multiple). It also can optionally declare whether it supports a character counter or a minimum number of rows and whether it requires a select value provider. If not declared, the default is true meaning that you can configure these attributes in the property configuration of your new form input field type. If set to false these fields won't appear in the property configuration.

Finally there has to be an implementing class that implements the interface com.subshell.sophora.eclipse.editor.form.IFormField. Although it is possible to implement the interface directly, it is generally recommended to extend com.subshell.sophora.eclipse.editor.form.AbstractFormField instead. (See plugin.xml and com.subshell.sophora.eclipse.example.formfields.PersonFormField from the example custom plug-in.)

Adding Editor Components

If your data model demands a more complex UI structure than can be handled and stored in a simple property, you might need to use child nodes in a Sophora document type and an input field that works on that structure. In this case you have to extend the extension point com.subshell.sophora.eclipse.editorComponents with an editorComponent. Like form input fields, every editor component needs a unique ID (unique in plug-in scope) and a human readable name. The ID is stored internally and the name is displayed in the node type configuration when configuring the editor component for a node type's child node.

Among other things, the editor component needs an implementing class that implements the interface com.subshell.sophora.eclipse.editor.extension.IEditorComponent. Although it is possible to implement the interface directly, it is generally recommended to extend com.subshell.sophora.eclipse.editor.extension.AbstractEditorComponent instead. (See plugin.xml and com.subshell.sophora.eclipse.example.editorcomponents.PersonEditorComponent from the example custom plug-in.)

Also note that changes in the model (CND) affect the implementation of the editor component and vice versa.

Adding Editor Tabs

Editor components may optionally provide a new custom tab to the Sophora document editor. These tabs have to implement the interface com.subshell.sophora.eclipse.editor.IExtendedEditorPart. They have to be provided by a com.subshell.sophora.eclipse.editor.extension.IEditorComponentTabProvider that is returned by the method getEditorTabs() in your IEditorComponent. (See com.subshell.sophora.eclipse.example.editorcomponents.PersonEditorComponent.getEditorTabs() and com.subshell.sophora.eclipse.example.editorcomponents.PersonEditorPart from the example custom plug-in.)

Testing Input Field Types

To test your custom input field types manually you have to add the needed properties and child node definitions to a document's node type in your server repository. Then configure the document's node type to use the new input field types. Afterwards create or open a document of the configured node type and your input fields will be shown in the editor.

Of course you can also test your custom input fields automatically using JUnit or plugin-in tests to see if the fields are modifying the model in a correct way.

Adding Startup Jobs

If you want to do some long-taking operations at each startup of the Sophora DeskClient (like filling a local cache from an external database), you have to extend the extension point com.subshell.sophora.eclipse.workbenchStartupJobs. This extension point provides one or more job factories (workbenchStartupJobs), whose jobs will be executed in the background when the DeskClient is started. (See plugin.xml, com.subshell.sophora.eclipse.example.startupJobs.JobFactory and com.subshell.sophora.eclipse.example.startupJobs.LongTakingJob from the example custom plug-in.)

Adding Custom Views

Of course it is possible to add custom views to the DeskClient by extending the Eclipse extension point org.eclipse.ui.views and implementing your own ViewPart.
Using a perspective extension (org.eclipse.ui.perspectiveExtensions) the custom view can be integrated into the default Sophora DeskClient perspective (ID: com.subshell.sophora.eclipse.perspective).

Getting The SophoraClient

In some cases the current instance of ISophoraClient is needed, e.g. if your plug-in provides an own view that has to communicate with the Sophora server itself. To get it, just use the following line of code:

ISophoraClient client = SophoraPlugin.getDefault().getSophoraClient();

Deployment of Custom Plug-Ins

Once you have created your own DeskClient plug-in, this plug-in has to be deployed to all workstations. Depending on the deploy mechanism you use for the DeskClient, you can

  • pack the built custom plug-ins into the DeskClient deploy package, or
  • set up a separate update site for your custom plug-ins.

For the first case you only need to build your plug-ins (e.g. in the Eclipse IDE) and copy them (and all dependencies) into the "plugins" folder of the DeskClient. Afterwards pack the DeskClient into an archive file and deploy it as you have done with the unmodified DeskClient before.

In the other case you need a feature project that contains your plug-ins (and all dependencies) and a site project that contains your feature. (See the projects com.subshell.sophora.eclipse.example-feature and com.subshell.sophora.eclipse.example-site from the example custom plug-in.) Build the update site and deploy it to a web server (next to the update site you use for the unmodified Sophora DeskClient). Now every DeskClient needs to know the URL of that update site. This can be configured in the user preferences or in the deskclient.ini. The next time the DeskClient is started it will search the new update site for new features and plug-ins to install.

Building A Custom Plug-In With Maven

The custom plug-in can be build head-less using Maven, e.g. to be built by a continuous integration server like Hudson. The example plug-in contains Maven pom.xml files and is built using Maven Tycho. This is an extension to Maven for building Eclipse plugins, features and related artifacts.

Requirements

Setup

The target-platform needs to be converted to two p2 repositories. The first repository will contain the Eclipse SDK, the other one the DeskClient. The following batch file converts an eclipse installation directory into a p2 repository; adapt it to your local paths. The script needs to be run for the eclipse- and the DeskClient-directory in your target-platform.

@echo off
set ECLIPSE_HOME=C:/path/to/eclipse/that/should/build/the/p2-repository/eg/targetplatform/eclipse
set SOURCE=C:/path/to/target/platform/that/should/be/build/as/p2-repository/eg/targetplatform/eclipse
set TARGET=file:%CD%/targetplatform_p2
"%ECLIPSE_HOME%/eclipsec.exe" -debug -consolelog -nosplash -verbose ^
    -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher ^
    -metadataRepository "%TARGET%" ^
    -artifactRepository "%TARGET%" ^
    -source "%SOURCE%" ^
    -compress -publishArtifacts

Note: Mac users have to call ./eclipse ... in path Eclipse.app/Contents/MacOS since the file eclipsec.exe does not exist.

Now, the paths to the two p2 repositories need to be referenced by the Maven pom.xml in the com.subshell.sophora.eclipse.example.parent project. This pom.xml references the p2 repos using the two properties deskclient.targetplatform.p2.url and deskclient.p2.url. Change these to point to the two p2 repositories you just created. The paths are urls, and must therefore be prefixed with "file:" if a path on the local harddisk is referenced. You can also set the properties in your Maven settings.xml instead, using a profile. We recommend this if you are using a continuous integration server, as then the paths need not be checked into your SCM.

Building

Once the p2 repositories are set up, you can build the example plug-in, feature and update-site by changing into the directory com.subshell.sophora.eclipse.example.parent and running the following command on the command-line:

mvn clean package

After the build, the update-site can be found in the directory com.subshell.sophora.eclipse.example-site/target.

References

Books about Eclipse RCP Development

  • Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications by Jeff McAffer, Jean-Michel Lemieux and Chris Aniszczyk (Addison-Wesley) (ISBN-10: 0321603788, ISBN-13: 978-0321603784)
  • Eclipse: Building Commercial-Quality Plug-ins by Eric Clayberg and Dan Rubel (Addison-Wesley) (ISBN-10: 0321553462, ISBN-13: 978-0321553461)
  • http://www.eclipse.org/resources/

SWT

JFace

Maven Tycho