Chapter 10. Writing a plug-in
Prev   Next

Chapter 10. Writing a plug-in

Table of Contents

1. Steps needed to write, package and deploy a plug-in
2. Packaging an add-on for XMLmind XML Editor integrated add-on manager
2.1. Creating useful add-on descriptors

1. Steps needed to write, package and deploy a plug-in

There are three types of plug-ins:

XSL-FO processor plug-in

Converts XSL-FO to another format. Used in process commands (see Chapter 5, Process commands in XMLmind XML Editor - Commands).

Image toolkit plug-in

Allows XMLmind XML Editor to support images formats other than built-in GIF, JPEG and PNG.

Virtual drive plug-in

Allows XMLmind XML Editor to edit documents stored in places other than the local file system. This is done by emulating a hierarchical file system.

In all cases, the steps needed to write, package and deploy a plug-in are exactly the same:

  1. Implement the interface of the plug-in:

    Plug-in typeInterface
    XSL-FO processor plug-incom.xmlmind.foprocessor.FOProcessor
    Image toolkit plug-incom.xmlmind.xmledit.imagetoolkit.ImageToolkit
    Virtual drive plug-incom.xmlmind.xmleditapp.vdrive.DriveFactory

  2. The compiled code of the plug-in (.class files) and all the associated resources must be archived in a JAR file having a special basename:

    Plug-in typeJAR basenameExample
    XSL-FO processor plug-inprefix_foprocessor.jarxfc_foprocessor.jar
    Image toolkit plug-inprefix_imagetoolkit.jarbatik_imagetoolkit.jar
    Virtual drive plug-inprefix_vdrive.jardav_vdrive.jar

  3. The JAR file must define a service, that is, it must contain a file called META-INF/services/interface_name.

    This file is a text file encoded in UTF-8 containing the fully qualified name of the class which implements the interface. Examples:

    Plug-in typeService definition file
    XSL-FO processor plug-in

    META-INF/services/com.xmlmind.foprocessor.FOProcessor contains:

    com.xmlmind.xmleditext.xfc_foprocessor.XFC
    Image toolkit plug-in

    META-INF/services/com.xmlmind.xmledit.imagetoolkit.ImageToolkit contains:

    com.xmlmind.xmleditext.batik_imagetoolkit.BatikImageToolkit
    Virtual drive plug-in

    META-INF/services/com.xmlmind.xmleditapp.vdrive.DriveFactory contains:

    com.xmlmind.xmleditext.dav_vdrive.DAVDriveFactory

  4. Most plug-ins are not self-contained and require support code to run. For example, xfc_foprocessor.jar needs xfc.jar to run, xfc.jar containing the code which actually converts XSL-FOs to RTF, WordprocessingML, OpenDocument, OOXML.

    The JAR files of the support code must be listed in the manifest file of the XSL-FO processor plug-in JAR file using standard attribute Class-Path.

    Example: in xfc_foprocessor.jar, the manifest file contains one line:

    Class-Path: xfc.jar

  5. The JAR file containing the code of the plug-in and the JAR files of the support code must be copied to a place where XXE will find them (see Section 1, “Dynamic discovery of add-ons” in XMLmind XML Editor - Configuration and Deployment). For example, copy them to XXE_user_preferences_dir/addon/. XXE user preferences directory is:

    • $HOME/.xxe4/ on Linux, Mac, and more generally, on Unix.

    • %APPDATA%\XMLmind\XMLEditor4\ on Windows 2000, XP, Vista.

      Example: C:\Documents and Settings\john\Application Data\XMLmind\XMLEditor4\ on Windows 2000 and XP. C:\Users\john\AppData\Roaming\XMLmind\XMLEditor4\ on Windows Vista.

2. Packaging an add-on for XMLmind XML Editor integrated add-on manager

A plug-in is an add-on, but all add-ons are not plug-ins (e.g. configuration, translation, dictionary). Therefore what is described here not only works for plug-ins but also for any kind of add-on.

Packaging an add-on for XMLmind XML Editor integrated add-on manager (menu item Options → Install Add-ons) is not strictly needed. During the development process, it is much quicker to test our extensions by simply copying the relevant files to one of the two addon/ directories scanned by XXE at startup time (more info in Section 1, “Dynamic discovery of add-ons” in XMLmind XML Editor - Configuration and Deployment).

Now you cannot expect the end-user to do the same thing, that's why it is strongly recommended to package add-ons for use by XMLmind XML Editor integrated add-on manager. Fortunately doing so is very easy:

  1. Copy all the files needed by the add-on to a common directory. Example:

    $ mkdir pnm_imagetoolkit-1_0_0
$ cp pnm_imagetoolkit.jar pnm_imagetoolkit-1_0_0

  2. Add an add-on descriptor to this directory.

    An add-on descriptor is a very simple XML file having a .xxe_addon extension and conforming to the RELAX NG schema contained in the add-on called "A configuration for specifying XMLmind XML Editor add-ons".

    Example of minimal add-on descriptor: pnm_imagetoolkit.xxe_addon:

    <a:addon location="pnm_imagetoolkit.zip"
         xmlns:a="http://www.xmlmind.com/xmleditor/schema/addon">
  <a:category><a:imageToolkitPlugin /></a:category>
  <a:name>PBM, PGM and PPM image toolkit plug-in</a:name>
  <a:version>1.0.0</a:version>
</a:addon>

  3. Zip this common directory (using 7-Zip or Info-Zip for example). Example:

    $ zip -r pnm_imagetoolkit.zip pnm_imagetoolkit-1_0_0

    The common directory must be included in the .zip file. Example:

    $ unzip -v pnm_imagetoolkit.zip
pnm_imagetoolkit-1_0_0/
pnm_imagetoolkit-1_0_0/pnm_imagetoolkit.jar
pnm_imagetoolkit-1_0_0/pnm_imagetoolkit.xxe_addon

  4. Put the .zip file, along with a copy of your add-on descriptor (pointing to the .zip file as shown in the above example), on a public web site of yours.

    Example: http://www.acme.com/pub/pnm_imagetoolkit.zip and http://www.acme.com/pub/pnm_imagetoolkit.xxe_addon.

  5. Tell your users to drag and drop URL http://www.acme.com/pub/pnm_imagetoolkit.xxe_addon onto the list displayed by XXE Preferences dialog box (Options → Preferences, Install add-ons section). This step is done once for all, as user preferences are persistent in XXE.

2.1. Creating useful add-on descriptors

Above example, pnm_imagetoolkit.xxe_addon, is not very informative. It lacks at least an a:abstract element which describes the purpose of the add-on.

Unless you intend to always write minimal add-on descriptors, you'll want to install the XXE configuration which provides support for this document type. This configuration is available as an add-on called "XMLmind XML Editor Configuration Pack". Download and install it using menu item Options → Install Add-ons.

a:addon attributes:

location

URL of the .zip file containing the add-on.

Not required when the .xxe_addon file is itself contained in the .zip file.

Required when the .xxe_addon file is downloaded by the integrated add-on manager in order to show to the user all available add-ons. In such case, location must point to the .zip file.

a:addon elements:

a:category

Required. The category of the add-on. Contains one of the following elements: a:translation, a:dictionary, a:configuration, a:foProcessorPlugin, a:imageToolkitPlugin, a:virtualDrivePlugin or a:otherCategory.

a:otherCategory has a required name attribute (a few words at most).

a:name

Required. The name of the add-on (a few words at most).

a:version

Required. Version number of the add-on. Examples: 1, 1.0, 1.2.1, 2.1.0_05, 1.0.0-alpha1, 2.0.1-beta02.

a:requires

Specifies the name of an add-on required by this add-on. It is possible to have several a:requires elements.

"Apache FOP 1.x XSL-FO processor plug-in" example:

<a:requires>Jimi image toolkit plug-in</a:requires>
<a:requires>Apache Batik image toolkit plug-in</a:requires>

Note that there is no need to specify indirect dependencies. When A requires B and B requires C, just specify B, and not B and C.

a:excludes

Specifies the name of an add-on which cannot be installed together with this add-on. It is possible to have several a:excludes elements.

"RenderX XEP XSL-FO processor plug-in" example:

<a:excludes>Apache FOP 1.x XSL-FO processor plug-in</a:excludes>

Note that there is no need to specify indirect dependencies. When A excludes B and B excludes C, just specify B, and not B and C.

a:author

The author of the add-on. Same content as XHTML p (a subset of XHTML in fact).

a:date

The release date of the add-on in YYYY-mm-dd ISO format[10]. Example: 2006-01-30.

a:abstract

The purpose of the add-on. Same content as XHTML p.

a:documentation

Use this element if the a:abstract is not sufficient to describe the purpose of the add-on. Same content as XHTML div.

a:xxeVersion

Specifies the version of XXE required to run this add-on. Same format as a:version, except that it may be followed by "+" to specify a version number and above.

Example: 3.2.1 means: strictly requires XXE 3.2.1. Will not work with 3.2.0, 3.2.2 or 3.3.0.

Example: 3.2+ means: requires XXE 3.2.0 and above. Works with 3.2.0, but also with 3.2.1, 3.2.2, 3.3, etc.

Without this element, the add-on is assumed to work with any version of XXE.

Important

In order to prevent link errors, any add-on which contains Java™ code (e.g. a jar) must have an a:xxeVersion equals to the version of XXE against which the code has been compiled. Of course, this a:xxeVersion must not have the "+" modifier.

Typically such add-ons are:

  • XSL-FO processor plug-ins.

  • Image toolkit plug-ins.

  • Virtual drive plug-ins.

  • Configurations, customizing XXE for a given document type, which include custom commands written in Java™.

a:platforms

Specifies the platforms required to run the add-on. Contains one of the following elements: a:windows, a:unix (means: a:mac or a:genericUnix), a:mac, a:genericUnix, a:otherPlatform.

a:otherPlatform has a required name attribute. The value of this attribute can be a plain string, for example

<a:otherPlatform name="linux" />

or a regular expression (when attribute regexp is specified with value true), for example:

<a:otherPlatform name="l[^x]+x" regexp="true" />

In both cases, the value of attribute name is matched (case-insensitive) against the value of Java™ system property "os.name" .

Without this element, the add-on is assumed to run on all platforms supported by XXE.

All platform elements may contain a a:postInstallShell child element. This element may be used to specify a script which is to be executed after the add-on has been installed.

<a:platforms>
  <a:unix>
    <a:postInstallShell>chmod a+x xep_finish_install</a:postInstallShell>
  </a:unix>

  <a:windows />
</a:platforms>

Note that the current working directory of this script is the directory where the add-on has been installed.


[10] Note that the CSS style sheet for XXE add-ons allows to specify the date using a more convenient format.

Prev   Next
Chapter 9. Writing a validateHook Home Chapter 11. Extending the GUI of XMLmind XML Editor