DITA-OT Sample plug-ins
Before we begin: if you use the toolkit, you owe a huge debt of thanks to Jarno Elovirta. He's been the
primary developer for the toolkit for a couple of years now, and if you've gotten a fix, seen a performance
improvement, or used a new feature, chances are he's the reason. He does it all for free, because he
enjoys it, but I'd encourage everybody to toss a few bucks in his tip jar.
About the samples
This page includes a series of plug-ins intended to guide new DITA-OT developers
through the creation of DITA-OT plug-ins. Most of these were originally created as part of a presentation to
the Boston and RTP DITA User Groups in December 2011; development now continues at
GitHub in the "metadita" repository, but
ready-to-install zip versions are posted here. My long term goal is to have at least one sample
plug-in for each new extension point in the toolkit.
Each plug-in here was tested with DITA-OT 1.8.M2 (release 1.8, patch 2), but should work with version 1.6 and later. For archived versions designed to work with DITA-OT 1.5.4, see the original posting from 2011.
To install any of the plug-ins below, unzip the selected archive into the DITA-OT/plugins/ directory. If you download a bundle with multiple plug-ins, you only need to unzip that bundle into
the same location. Complete documentation for extension points can be found at the DITA-OT landing page; look in
the follow the documentation link and look under Developer Reference -> Creating DITA-OT plug-ins.
What can you override? What samples are available?
Overview of available samples; details are below the table
| Plug-in ID |
What does it extend? |
| XHTML style |
PDF style |
New XSLT parameter |
XML Catalog (Specialization) |
New Ant code |
Extend Ant pre-process |
New transform type |
Add generated text |
Add error messages |
Add Java library |
New extension point |
Builds on pre-requisite |
| org.metadita.xsl.xhtmlbrand |
Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| org.metadita.specialization.cmdref |
Yes | -- | -- | Yes | -- | -- | -- | -- | -- | -- | -- | -- |
| Music |
Yes | Yes | -- | Yes | -- | -- | -- | -- | -- | -- | -- | -- |
| org.metadita.transtype.faketxt |
-- | -- | -- | -- | Yes | -- | Yes | -- | -- | -- | -- | -- |
| org.metadita.xslparam |
Yes | -- | Yes | -- | Yes | -- | -- | -- | -- | -- | -- | -- |
| org.metadita.strings |
-- | -- | -- | -- | -- | -- | -- | Yes | -- | -- | -- | -- |
| org.metadita.strings |
-- | -- | -- | -- | -- | -- | -- | Yes | -- | -- | -- | -- |
| org.metadita.xsl.puffinbrand |
Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | strings |
| org.metadita.bundle-gentext (zip file) |
Bundles org.metadita.strings and org.metadita.xsl.puffinbrand into a single install package. |
| org.metadita.errors |
-- | -- | -- | -- | -- | -- | -- | -- | Yes | -- | -- | -- |
| org.metadita.xsl.validation |
-- | -- | -- | -- | -- | -- | -- | -- | Yes | -- | -- | errors |
| org.metadita.run.validation |
-- | -- | -- | -- | Yes | Yes | -- | -- | Yes | -- | -- | errors; xsl.validation |
| org.metadita.bundle-validation (zip file) |
Bundles org.metadita.errors, org.metadita.xsl.validation, and org.metadita.run.validation into a single install package. |
| org.metadita.samplejava |
-- | -- | -- | -- | Yes | Yes | -- | -- | Yes | Yes | -- | -- |
| org.metadita.fullbundle (zip file) |
Bundles all of the previous plug-ins into a single install package. |
Downloadable packages
- org.metadita.xsl.xhtmlbrand.zip:
Sample XHTML Branding plug-in; overrides the XHTML transform to add a
Puffin image to the top of every output file.
- org.metadita.specialization.cmdref.zip:
Sample specialization plug-in; also includes very simple corresponding XHTML XSLT override.
- Music plug-in:
Plug-in to integrate a more complex specialization, override XHTML XSLT, and override PDF XSLT code:
Use the latest version of the music plug-in. It includes support for a specialization of reference topics,
primarily a specialized simpletable with columns for artist name, album, and related info. It also includes
XHTML and PDF overrides that add default headers to the tables.
- org.metadita.transtype.faketxt.zip:
Sample new transform; defines "faketxt" transform type, with XSLT processing to create fake text
output (basically, just concatenates the content of all topics as a single text file).
- org.metadita.xslparam.zip:
Sample "new XSLT parameter" plug-in; defines a new parameter $DAY that is passed in to XHTML processing. Default value is WEDNESDAY;
builds may change this by setting the Ant parameter ${org.metadita.xslparam.day} to something else. When $DAY='WEDNESDAY'
is passed to the XHTML process, the included XSLT override causes all text to come out in reverse.
NOTE: the default with this plug-in is for DAY=WEDNESDAY. It does not actually
set the current day dynamically. If you set ${org.metadita.xslparam.day} to anything else in your Ant build file,
the output will be normal; if you set that to WEDNESDAY, or leave it unspecified, the output is reversed. If you use Ant to dynamically set ${org.metadita.xslparam.day} to the current day, then as expected, your text will be reversed every Wednesday.
- Set of two plug-ins that build on each other:
- org.metadita.strings.zip:
Plug-in that defines new strings for XSLT processing; specifically, it translates
the string "Puffin" to English, Russian, Swedish, and Icelandic.
- org.metadita.xsl.puffinbrand.zip:
Plug-in that overrides XHTML to create a footer; the footer retrieves the string "Puffin"
from the definitions in the previous plug-in. This plug-in will only be integrated if the
previous plug-in is also available.
- org.metadita.bundle-gentext.zip:
These plug-ins really work together, and can be distributed as a unit. Us this zip to install both at once.
- Set of three plug-ins that build on each other:
- org.metadita.errors.zip:
Defines two new error messages for user by XSLT code.
The first message is silly (warn when there are no links to topics about puffins). The second
message is a real-world sample, warning about topics that do not contain a short description.
- org.metadita.xsl.validation.zip:
This plug-in does not actually integrate into
anything; instead, it provides code that others may use, taking advantage of the previously
defined error messages. Often this code would be bundled with the plug-in that actually calls it,
except in cases where many plug-ins all want access to this validation code.
- org.metadita.run.validation.zip:
This plug-in hooks into the
Ant preprocess routine and adds a new dependency that will always run after the other pre-processing.
This new target runs the validation code supplied by the previous step.
- org.metadita.bundle-validation.zip:
These plug-ins really work together, and can be distributed as a unit. Use this zip to install all three at once.
- org.metadita.samplejava.zip:
Sample Java library integration. The new Java class is added to the OT's classpath (dost.class.path).
The code does nothing but put out a fake info message for the log (essentially, a Hello World program).
Ant code is then added which calls this new Java class before running the conref step; the new message
(for no real purpose) is also integrated in the message list.
Related information