Xerlin Plugin Development Guide

Version 1.0

July 7, 2002

This version:

http://www.xerlin.org/docs/plugins/plugin-dev-guide.html

Authors and Contributors:

Tim McCune, ChannelPoint

Kelly Campbell, ChannelPoint

Justin Lipton, SpeedLegal

Table of Contents

Appendices

1 Introduction

This document describes the Xerlin Plugin architecture, and how developers can use it to extend Xerlin with their own implementations. The plugin architecture is still rather new, so make sure you have the latest version of this document which matches the latest version of Xerlin you are using. Throughout this document, we will use examples from existing Xerlin plugins.

2 Plugin Overview

Plugins for Xerlin are provided in a bundled jar format similar to Web Applications [SERVLET]. These jar files contain the configuration of the plugin, its classes, and any resources such as icons and DTD files the plugin requires.

2.1 Configuration

Although Xerlin supports different plugin types, all Xerlin plugins contain a "plugin.xml" file, which contains all of the configuration for that plugin.

2.2 Classes

There are two different ways to supply classes in a plugin. Individual classes can be stored in a classes directory. Jar files can be stored in a lib directory. This is basically modeled after the way that Web Applications work. [SERVLET]

3 DTD Plugins

A DTD plugin allows you to customize Xerlin to support your specific DTD. These customizations include custom editors and icons that map to elements of the DTD. This section defines all of the different settings in plugin.xml for a DTD plugin.

3.1 dtd-plugin

The dtd-plugin element is the top-level element in a plugin.xml file for a DTD plugin. It has no attributes. All of the following elements are children of the dtd-plugin element unless otherwise indicated. Any time a resource file is indicated (the DTD file, for instance,) you must specify a relative path. The base directory of this path will be the plugin's root directory. So, for instance, the following entry:

<file>dtd/vxml.dtd</file>

would be found in [xerlin-directory]/plugins/vxml/dtd/vxml.dtd during development, and as an entry in [xerlin-directory]/plugins/vxml.jar once the plugin is deployed.

3.2 name

The name element allows you to specify a short name for your plugin. This will appear as a menu item under the "Help, About plugins" menu item.

<name>VoiceXML</name>

3.3 longName

The longName element allows you to specify a long name for your plugin.

<longName>Voice eXtensible Modeling Language Plugin for Xerlin</longName>

3.4 version

The version element allows you to specify a version number for your plugin.

<version>1.0</version>

3.5 author

The author element allows you to specify an author name for your plugin.

<author>Tim McCune</author>

3.6 url

The url element allows you to specify a URL where users can find out more about your plugin.

<url>http://www.xerlin.org</url>

3.7 dtd

The dtd element allows you to specify the DTD that your plugin is associated with. It contains several subelements.

3.7.1 file

The file element specifies the path to the actual DTD file.

<file>dtd/vxml.dtd</file>

3.7.2 doctype

The doctype element specifies the document type that should be used with this plugin. Xerlin will use this as the root element of your document.

<doctype>vxml</doctype>

3.7.3 publicID

The publicID element specifies the public ID to include in the doctype declaration.

<publicID>-//VoiceXML Forum//Voice eXtensible Markup Language 1.0//EN</publicID>

3.7.4 systemID

The systemID element specifies the system ID to include in the doctype declaration.

<systemID>http://www.voicexml.org/dtd/vxml1.0.dtd</systemID>

3.8 editor

The editor element defines an individual editor class and the elements that it edits. It has two subelements.

3.8.1 class

The class element is the fully-qualified name of the class that implements the org.merlotxml.merlot.MerlotDOMEditor interface.

<class>org.merlotxml.merlot.plugins.vxml.AudioEditor</class>

3.8.1.1 MerlotDOMEditor interface

Custom attribute editors must implement this interface. You can also extend GenericDOMEditor and/or GenericDOMEditPanel if you don't want to implement all the methods required by this interface. Look at GenericDOMEditor for an example of how to use this interface.

Also look at the examples given in the example plugins in CVS.

3.8.2 element

The element element is the name of an element that this editor should be used to edit. Multiple elements can be specified for a single editor.

<element>audio</element>

3.9 defaultEditor

The defaultEditor element defines an individual default editor class for a particular DTD. It has one subelement.

3.9.1 class

The class element is the fully-qualified name of the class that implements the org.merlotxml.merlot .MerlotDOMEditor interface. This editor will be called if none of the element elements match for a particular DTD.

<class>org.merlotxml.merlot.plugins.vxml.AudioEditor</class>

3.10 icon

The icon element defines a custom icon that should appear for one or more elements. The source attribute specifies the path to an image (typically a 32x32 GIF). The smallSource attribute specifies the path to a smaller version of the image (typically a 16x16 GIF).

3.10.1 element

The element element is the name of an element that this icon should be used to represent. Multiple elements can be specified for a single icon.

<icon source="icons/audio.gif" smallSource="icons/audio_s.gif">
	<element>audio</element>
</icon>

The following graphic demonstrates an editor from the VoiceXML DTD plugin.

3.11 tree-table

The tree-table element defines custom columns that should appear in the tree-table for this plugin. The text that should appear for each column can also be defined.

3.11.1 column

The column element represents each column of the treetable. Each column has a name specified by the name attribute and a desription specified by the attribute attribute. The attribute may be the name of an attribute such as IDREF or Condition. If the attribute is set equal to ~ the description is determined by the children of the display-text element.

<tree-table>
    <column name="Description" attribute="~"/>
    <column name="Condition" attribute="condition"/>
</tree-table>
                

3.12 display-text

The display-text element defines a custom order to be tried in order to determine the descriptive text for an element.

3.12.1 default-property-order

The default-property-order element specifies the order of the attributes/child text to specify an elements descriptive text.

3.12.1.1 attribute-type

The attribute-type element specifies an attribute to be be tried for the descriptive text. It has one attribute name which specifies the name of the attribute or CHILD_TEXT to use the text of a child.

<display-text>
  <default-property-order>
    <attribute-type name="CDATA"/>
    <attribute-type name="IDREF"/>
    <attribute-type name="CHILD_TEXT"/>
  </default-property-order>
</display-text>

4 Action Plugins

A DTD plugin allows you to specify a custom action that will be performed on the XML document that you are editing in Xerlin. The name, longName, version, author, and url elements in the plugin.xml file are the same as they are for DTD Plugins.

4.1 action

The action element specifies a single action. A single plugin.xml file can contain multiple actions.

4.1.1 menu

The menu element specifies the name that will appear in the Plugins menu for this action.

<menu>XSLT Processor</menu>

4.1.2 class

The class element is the fully-qualified name of the class that implements the org.merlotxml.merlot.plugin.action.Action interface.

<class>org.merlotxml.merlot.plugins.action.xslt.Plugin</class>

4.1.3 icon

The icon element defines the path to a custom icon that should appear in the Plugins menu next to the text specified in the menu element (typically a 16x16 GIF).

4.1.4 tooltip

The tooltip element defines a tool tip that should appear over the menu item for your plugin in the Plugins menu.

4.1.5 config

The config element allows you to store any configuration information that is specific to your plugin. It contains multiple configitem elements.

4.1.5.1 configitem

The configitem element contains plugin-specific configuration items. The name attribute is the name of the item. Its value is a text node.

<configitem name="output-extension">html</configitem>

A References

SERVLET

Sun Microsystems. Java Servlet 2.2 Specification See http://java.sun.com/products/servlet/download.html

B DTD Plugin DTD

<!ELEMENT dtd-plugin (name, longName?, version?, author?, url?, (dtd | editor | icon)*, tree-table?, display-text?>

<!ELEMENT name (#PCDATA)>

<!ELEMENT longName (#PCDATA)>

<!ELEMENT version (#PCDATA)>

<!ELEMENT author (#PCDATA)>

<!ELEMENT url (#PCDATA)>

<!ELEMENT dtd (file, doctype, publicID, systemID)>

<!ELEMENT file (#PCDATA)>

<!ELEMENT doctype (#PCDATA)>

<!ELEMENT publicID (#PCDATA)>

<!ELEMENT systemID (#PCDATA)>

<!ELEMENT editor (class, element*)>

<!ELEMENT defaultEditor (class)>

<!ELEMENT class (#PCDATA)>

<!ELEMENT element (#PCDATA)>

<!ELEMENT icon (element*)>
<!ATTLIST icon source CDATA #REQUIRED
               smallSource CDATA #REQUIRED>

<!ELEMENT tree-table (column+)>

<!ELEMENT column EMPTY>
<!ATTLIST column name CDATA #REQUIRED
                attribute CDATA #REQUIRD>

<!ELEMENT display-text (default-property-order)>

<!ELEMENT default-property-order (attribute-type+)>

<!ELEMENT attribute-type EMPTY>
<!ATTLIST attribute-type name NMTOKEN #REQUIRED>

C Action Plugin DTD

<!ELEMENT action-plugin (name, longName?, version?, author?, url?, action*)>

<!ELEMENT name (#PCDATA)>

<!ELEMENT longName (#PCDATA)>

<!ELEMENT version (#PCDATA)>

<!ELEMENT author (#PCDATA)>

<!ELEMENT url (#PCDATA)>

<!ELEMENT action (menu, class, icon?, tooltip?, config?)>

<!ELEMENT menu (#PCDATA)>

<!ELEMENT class (#PCDATA)>

<!ELEMENT icon (#PCDATA)>

<!ELEMENT tooltip (#PCDATA)>

<!ELEMENT config (configitem*)>

<!ELEMENT configitem (#PCDATA)>
<!ATTLIST configitem name CDATA #REQUIRED>