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:

<feature extension="dita.specialization.catalog.relative" value="catalog-dita.xml" type="file" />

(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:

<dummy>
<import file="myAntStuff.xml"/>
</dummy>

Then create the following feature:

<feature extension="dita.conductor.target.relative" value="myAntStuffWrapper.xml" type="file" />

(Note that the dita.conductor.target extension is deprecated.  Use dita.conductor.target.relative instead.)

Add Ant targets to the preprocess pipeline

To add an Ant target myTarget to the preprocess pipeline, choose which pipeline stage it must occur before.  Then create a feature for the extension depend.preprocess.stagename.pre:

<feature extension="depend.preprocess.chunk.pre" value="myAntTargetBeforeChunk"/>

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:

• Override default (X)HTML output (including HTML Help and Eclipse Help) with the following: <feature extension="dita.xsl.xhtml" value="xsl/modifyXhtml.xsl" type="file"/>

• Override default PDF output (formerly known as PDF2) with the following: <feature extension="dita.xsl.xslfo" value="xsl/modifyPdf.xsl" type="file"/>

• Override default DocBook output with the following: <feature extension="dita.xsl.docbook" value="xsl/sample.xsl" type="file"/>

• Override default RTF output with the following: <feature extension="dita.xsl.rtf" value="xsl/sample.xsl" type="file"/>

• Override the step that generates plugin.xml for Eclipse with the following: <feature extension="dita.xsl.eclipse.plugin" value="xsl/sample.xsl" type="file"/>

• Override conref processing: <feature extension="dita.xsl.conref" value="xsl/sample.xsl" type="file"/>

• Override topicpull processing (the step that pulls text into <xref> elements, among other things): <feature extension="dita.xsl.topicpull" value="xsl/sample.xsl" type="file"/>

• Override mapref processing (the step that resolves references to other maps): <feature extension="dita.xsl.mapref" value="xsl/sample.xsl" type="file"/>

• Override mappull processing (the step that updates navtitles in maps and causes attributes to cascade): <feature extension="dita.xsl.mappull" value="xsl/sample.xsl" type="file"/> 

• Override maplink processing (the step that generates map-based links): <feature extension="dita.xsl.maplink" value="xsl/sample.xsl" type="file"/> 

• Override the (now deprecated) original PDF output with the following: <feature extension="dita.xsl.fo" value="xsl/modifyXhtml.xsl" type="file"/>

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:

<feature extension="dita.xsl.strings" value="xsl/common/strings.xml" type="file"/>

The string is now available to the XSLT "getString" template.

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:

<dummy>
<!-- Any Ant code allowed in xslt task is possible. Common example: -->
<param name="paramNameinXSLT" expression="${antProperty}" if="antProperty"/>
</dummy>

Pass the value using the following extensions:

• Pass parameters to HTML and HTML Help XSLT: <feature extension="dita.conductor.html.param" value="insertParameters.xml" type="file"/>
• Pass parameters to XHTML and Eclipse Help XSLT: <feature extension="dita.conductor.xhtml.param" value="insertParameters.xml" type="file"/>
• Pass parameters to conref XSLT: <feature extension="dita.preprocess.conref.param" value="insertParameters.xml" type="file"/>
• Pass parameters to mapref XSLT: <feature extension="dita.preprocess.mapref.param" value="insertParameters.xml" type="file"/>
• Pass parameters to mappull XSLT: <feature extension="dita.preprocess.mappull.param" value="insertParameters.xml" type="file"/>
• Pass parameters to maplink XSLT: <feature extension="dita.preprocess.maplink.param" value="insertParameters.xml" type="file"/>
• Pass parameters to topicpull XSLT: <feature extension="dita.preprocess.topicpull.param" value="insertParameters.xml" type="file"/>

Add Java libraries to the classpath

If your Ant or XSLT extensions require additional Java libraries in the classpath, you can add them to the global Ant classpath.

<feature extension="dita.conductor.lib.import" type="myJavaLibrary.jar" type="file"/>

Add diagnostic messages

To add your own warning and error messages to the set supplied by DITA-OT, create the message in an XML file myMessages.xml:

<dummy>
<!-- See resource/messages.xml for the details. -->
<message id="myMessageId" type="WARN">
<reason>...</reason>
<response>...</response>
</message>
</dummy>

And incorporate them with the extension:

<feature extension="dita.xsl.messages" value="myMessages.xml" type="file"/>

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:

<feature extension="package.support.name" value="Joe the Author"/>
<feature extension="package.support.email" value="joe@example.com"/>
<feature extension="package.version" value="1.2.3"/>

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

<plugin id="org.metadita.specialization.music">
<feature extension="dita.specialization.catalog.relative" value="catalog-dita.xml" type="file"/>
<feature extension="dita.xsl.xhtml"value="xsl/music2xhtml.xsl" type="file"/>
</plugin>