Diff for DITA-OT Plug-in Extension Points

Extensions to the DITA Open Toolkit are supported through a plug-in extension mechanism. Plug-ins may do a number of things, such as adding support for specialized DTDs or Schemas, integrating processing overrides, or providing entirely new output transforms. Extensions are integrated using a file named plugin.xml, located in the plug-in's root directory; the plug-in directory itself is generally located within the demo/ or plugins/ directory inside of the DITA-OT. This document describes all recognized extension points that are available for use within the plugin.xml file.

Extensions to the DITA Open Toolkit are supported through a plug-in extension mechanism. Plug-ins may do a number of things, such as adding support for specialized DTDs or Schemas, integrating processing overrides, or providing entirely new output transforms. Extensions are integrated using a file named plugin.xml, located in the plug-in's root directory; the plug-in directory itself is generally located within the demo/ or plugins/ directory inside of the DITA-OT. This document describes all recognized extension points that are available for use within the plugin.xml file.

+

</p>

+

<p>

+

For more complete examples of the available extension points, see the &quot;Developer reference&quot; section of the DITA-OT 1.5.4 (or later) <a href="http://dita-ot.sourceforge.net/" target="_blank">project documentation</a>. The shipped documentation for plug-ins was significantly updated in release 1.5.4, so earlier versions may not prove as useful.

Extension points for plug-ins to the DITA Open Toolkit

Extensions to the DITA Open Toolkit are supported through a plug-in extension mechanism. Plug-ins may do a number of things, such as adding support for specialized DTDs or Schemas, integrating processing overrides, or providing entirely new output transforms. Extensions are integrated using a file named plugin.xml, located in the plug-in's root directory; the plug-in directory itself is generally located within the demo/ or plugins/ directory inside of the DITA-OT. This document describes all recognized extension points that are available for use within the plugin.xml file.

For more complete examples of the available extension points, see the "Developer reference" section of the DITA-OT 1.5.4 (or later) project documentation. The shipped documentation for plug-ins was significantly updated in release 1.5.4, so earlier versions may not prove as useful.

Plugin configuration file

The root element of the plugin.xml file is <plugin>, and must specify an id attribute. The id attribute is used to identify the plugin, as well as to identify whether pre-requisite plugins are available. The <plugin> element supports the following child elements:

<feature> defines an extension to contribute to a defined extension point. The following attributes are supported:

extension: extension point identifier

value: comma separated string value of the extension

file: file path value of the extension, relative to plugin.xml

type: type of the string value

<require> defines plug-in dependencies. The following attributes are supported:

plugin: vertical bar separated list of plug-ins that are required

important: flag whether plug-in is required or optional

<template> defines files that should be treated as templates. The following attributes are supported:

file: file path to the template, relative to plugin.xml

<meta>defines metadata. The following attributes are supported:

type: metadata name

value: metadata value

Any extension that is not recognized by the DITA-OT is ignored; all elements other than <plugin> are optional. Since version 1.5.3 multiple extension definitions within a plugin configuration file are combined; in older versions only the last extension definition is used.

See the bottom of this page for an example of a plugin.xml file.

XML catalogs

The XML Catalogs extension point may be used to update the XML Catalogs used to resolve DTD or Schema document types. To do this, first create a catalog with only your new values, using the OASIS Catalog format, and place that in your plugin. Next create a <feature> element, with the extension attribute set to "dita.specialization.catalog.relative", the value attribute set to the name of your local catalog file, and the type attribute set to "file". For example:

(Note that the dita.specialization.catalog extension is deprecated. Use dita.specialization.catalog.relative instead.)

New Ant targets

The Ant conductor extension point may be used to make new targets available to Ant processing. To do this, first place your extensions in an Ant project file within your plugin, such as myAntStuff.xml. Create a small wrapper file myAntStuffWrapper.xml in the same directory:

There are also extension points depend.preprocess.pre and depend.preprocess.post to execute a target before or after all preprocessing.

New transtype

The transtype extension point may be used to define a new "transtype", or transform type, which makes use of targets in your Ant extensions. The following feature defines a transform type of "newtext"; using this transform type will cause the build to look for a target dita2newtext, defined previously in your Ant extension:

<feature extension="dita.conductor.transtype.check" value="newtext"/>

XSLT overrides

The XSLT import extension points may be used to override various steps of XSLT processing. For this, the extension attribute indicates the step that the override applies to; the value attribute is a relative path to the override within the current plugin; the type attribute should be set to "file". The plugin installer will add an XSL import statement to the default code, so that your override becomes a part of the normal build. The following XSLT steps are available to override in the core toolkit:

Generated text

The generated text extension point may be used to add new strings to the default set of Generated Text. Copy the file xsl/common/strings.xml to your plugin, and edit it to contain the languages that you are providing translations for ("en-us" must be present). Copy the file xsl/common/strings-en-us.xml to your plugin, and replace the content with your own strings, being sure to give them unique name attributes. Do the same for each language that you are providing a translation for.

Use the following extension code to include your strings in the set of generated text:

Pass parameters to XSLT

You can pass parameters from the Ant build to XSLT pipeline stages, usually to have those parameters avalable as global <xsl:param> values in your XSLT overrides. Create a file insertParameters.xml which contains one or more Ant <param> elements:

Manage plugin dependencies

The <require> element requires the plugin attribute. It is used to identify pre-requisite plug-ins. If the current plugin requires a plugin with id="plugin-id" before it can be installed, it would include the following:

<require plugin="plugin-id">

Prerequisite plugins are integrated before the current plugin is integrated. This does the right thing with respect to XSLT overrides. If your plugin is a specialization of a specialization, it should <require> its base plugins, in order from general to specific.

If a prerequisite plugin is missing, a warning will be printed during integration. To suppress this, but keep the integration order if both plugins are present, add importance="optional" to the <require> element.

If your plugin can depend on any one of several optional plugins, separate the plugin ids with a vertical bar. This is most useful when combined with importance="optional":

<require plugin="pluginA|pluginB" importance="optional"/>

Version and support information

The following conventions are in use by some groups for defining version and support info within a plugin; the toolkit does not currently do anything with these values, but may do so in the future:

Create your own extension points

If your plugin needs to define its own extension point in an XML file, add the string "_template" to the filename before the file suffix. During integration, this file will be processed like the built-in DITA-OT templates. To mark the file as a template file, use the <template> element:

<template file="myTemplateFile_template.xsl"/>

Example plugin.xml file

The following is a sample of a plugin.xml file. This file adds support for a new set of specialized DTDs, and includes an override for the XHTML output processor. It would go into a directory such as DITA-OT\plugins\music\ and referenced supporting files would also exist in that directory. Unfortunately, due to limitations in this wiki, the full code sample does not show up as well formatted as one might wish. A more extensive sample using these values is available in the actual music plug-in, available at the DITA-OT download page at SourceForge