Creating an override template

Before building the plugin, you must separate your hacked changes from the DITA OT XSL stylesheets and create your own stylesheet file.

To create an override template for the list sorting example shown earlier:

1. Create a new XSL stylesheet file to contain the template. In this example, the new file is called sort-ul.xsl.
2. Edit the new stylesheet file and add the standard XML required for an XSL stylesheet:

<?xml version="1.0" encoding="UTF-8" ?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> </xsl:stylesheet>

3. Open the file ditaot/xsl/xslhtml/dita2htmlImpl.xsl, and find the template that contains the new sorting code. The template begins with:

<xsl:template match="*[contains(@class,' topic/ul ')]" mode="ul-fmt">

4. Copy the entire template into the new stylesheet. Add a comment at the beginning of the copied template, indicating that the template overrides the behavior of dita2htmlImpl.xsl. Then save and close the file.
5. The plugin mechanism will invoke the new stylesheet, so your modified template overrides the behavior of the DITA OT version of the template.
6. Restore the old DITA OT template to its previous state. (You did make a backup copy, right?)

Creating a plugin

To create a plugin:

1. Create your XSL, DTD, and Ant files, as appropriate for your changes. In this example, there is only one XSL file containing the template that handles list sorting.
2. Create a new folder for your plugin in the ditaot/demo folder.
3. Create folders inside the ditaot/demo folder that mirror the ditaot/demo/apiref plugin folder. (Actually, you only need folders for the components you’re distributing. Therefore, if you’re only updating the XSL, you only need to create an xsl folder.)
4. Copy the new stylesheet file (sort-ul.xsl) into the xsl folder.
5. Copy the file plugin.xml from the apiref folder. (The existing file is a good place to start because you can take away what you’re not going to use, then make minor tweaks to point to your own files.)
6. Open the plugin.xml file in a text editor. It should look like this:

<?xml version="1.0" encoding="UTF-8"?> <!-- | (C) Copyright IBM Corporation 2005 - 2006. All Rights Reserved. *--> <plugin id="org.dita.specialization.apiref"> <feature extension="dita.specialization.catalog" value="catalog-dita.xml" type="file"/> <feature extension="dita.xsl.xhtml" value="xsl/apiref2xhtml.xsl" type="file"/> <feature extension="dita.conductor.target" value="conductor.xml" type="file"/> </plugin>

7. Delete the first and last <feature> elements, leaving only the <feature> element with extension="dita.xsl.xhtml".
8. Change the value in the remaining <feature> element to point to your new XSL file.

<feature extension="dita.xsl.xhtml" value="xsl/sort-ul.xsl" type="file"/>

9. To specify multiple XSL stylesheet files, add them to the value attribute of the <feature> element, separated by commas:

<feature extension="dita.xsl.xhtml" value="xsl/sort-ul.xsl,xsl/my_heads.xsl" type="file"/>

Installing and testing the plugin

Since DITA OT 1.2, you do not have to run a separate installation step. When you run the DITA OT, it looks for plugins and integrates them, if necessary. To install and test your plugin:

1. Install a new copy of the DITA OT. Rename the folder to something like ditaot-test.
2. Copy your plugin folder to the demo folder of the new ditaot-test folder.
3. Copy the modified version of ditaot/samples/concepts/tools.xml (the one that includes the otherprops="sorted" attribute) to the folder ditaot-test/samples/concepts.
4. Copy the file ditaot/ant/my_xhtml.xml to the folder ditaot-test/ant.
5. Use the startcmd.bat or startcmd.sh file in the ditaot-test folder to start a command line.
6. Run the DITA OT with the command:

ant -f ant/my_xhtml.xml

7. Open the file ditaot/ant/out/samples/xhtml/concepts/tools.html in a browser to see the sorted list.