Creating a DITA OT Customization Plugin

To describe the steps involved in creating a DITA Open Toolkit plugin, this section uses an example of creating an XSLT customization plugin that provides syntax highlighting when publishing DITA codeblock elements to HTML and PDF output formats. This plugin (com.oxygenxml.highlight) that provides syntax highlighting is available in the DITA Open Toolkit distribution that comes bundled with the latest version of Oxygen XML Author plugin, but these instructions show you how to create it as if it were not included.

The steps to help you to create the plugin are as follows:

1. Create a folder for your plugin in the DITA OT plugins folder (DITA_OT_DIR/plugins/).

   For example, if you are using DITA 1.8.5, the path would look like this:

   [OXYGEN_INSTALL_DIR]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.highlight

2. Create a plugin.xml file (in the same plugin folder) that contains the extension points of the plugin.

   Note

   You can easily create this file by using the DITA OT Plugin new file template that is included in Oxygen XML Author plugin. From the New file wizard you can find this template in Framework templates ⇒ DITA ⇒ plugin.
   For example, our syntax highlighting plugin example contains the following:

   <plugin id="com.oxygenxml.highlight">
     <feature extension="package.support.name" value="Oxygen XML Editor Support"/>
     <feature extension="package.support.email" value="support@oxygenxml.com"/>
     <feature extension="package.version" value="1.0.0"/>
     <feature extension="dita.xsl.xhtml" value="xhtmlHighlight.xsl" type="file"/>
     <feature extension="dita.xsl.xslfo" value="pdfHighlight.xsl" type="file"/>
   </plugin>

   The most important extensions in it are the references to the XSLT stylesheets that will be used to style the HTML and PDF outputs.

   You can find other DITA OT plugin extension points here: http://dita-ot.sourceforge.net/1.5.3/dev_ref/extension-points.html

3. Create an XSLT stylesheet to customize the output types. In our example, to customize the HTML output we need to create an XSLT stylesheet called xhtmlHighlight.xsl (in the same plugin folder).

   Tip

   You can use the Find/Replace in Files to find an XSLT stylesheet with content that is similar to the desired output and use it as a template to overwrite parts of your stylesheet. In our example we want to overwrite the creation of the HTML content from a DITA codeblock element. Since a DITA codeblock element has the class attribute value + topic/pre pr-d/codeblock we can take part of the class attribute value (topic/pre) and search the DITA OT resources for a similar stylesheet.

   Our search found the XSLT stylesheet DITA_OT_DIR/org.dita.xhtml/xsl/xslhtml/dita2htmlImpl.xsl that contains:

   <xsl:template match="*[contains(@class,' topic/pre ')]" name="topic.pre">
     <xsl:apply-templates select="."  mode="pre-fmt" />
   </xsl:template>

   We use it to overwrite our xhtmlHighlight.xsl stylesheet, which results in the following:

   <xsl:template match="*[contains(@class,' topic/pre ')]" name="topic.pre">
       <!-- This template is deprecated in DITA-OT 1.7. Processing will moved into the main element rule. -->
       <xsl:if test="contains(@frame,'top')"><hr /></xsl:if>
       <xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]" mode="out-of-line"/>
       <xsl:call-template name="spec-title-nospace"/>
       <pre>
         <xsl:attribute name="class"><xsl:value-of select="name()"/></xsl:attribute>
         <xsl:call-template name="commonattributes"/>
         <xsl:call-template name="setscale"/>
         <xsl:call-template name="setidaname"/>
        <!--Here I'm calling the styler of the content inside the codeblock.-->
        <xsl:call-template name="outputStyling"/>
       </pre>
       <xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-endprop ')]" mode="out-of-line"/>
       <xsl:if test="contains(@frame,'bot')"><hr /></xsl:if><xsl:value-of select="$newline"/>
     </xsl:template>

   You could also use another XSLT template that applies the XSLTHL library as a Java extension to style the content.

4. Create additional XSLT stylesheets to customize all other desired output types. In our example, to customize the PDF output we need to create an XSLT stylesheet called pdfHighlight.xsl (in the same plugin folder).

   In this case we found an appropriate XSLT stylesheet DITA_OT_DIR/plugins/legacypdf/xslfo/dita2fo-elems.xsl to use as a template that we use to overwrite our pdfHighlight.xsl stylesheet, which results in the following:

   <xsl:template match="*[contains(@class,' topic/pre ')]">
     <xsl:call-template name="gen-att-label"/>
     <fo:block xsl:use-attribute-sets="pre">
       <!-- setclass -->
       <!-- set id -->
       <xsl:call-template name="setscale"/>
       <xsl:call-template name="setframe"/>
       <xsl:apply-templates/>
     </fo:block>
   </xsl:template>

   Note

   You can edit the newly created stylesheets to customize multiple outputs in a variety of ways. For example, in our case you could edit the xhtmlHighlight.xsl or pdfHighlight.xsl stylesheets that we created to customize various colors for syntax highlighting.
5. To install the created plugin in the DITA OT, run the predefined transformation scenario called Run DITA OT Integrator by executing it from the Apply Transformation Scenario(s) dialog box. If the integrator is not visible, enable the Show all scenarios action that is available in the Settings drop-down menu. For more information, see Installing a Plugin in the DITA Open Toolkit.

   Results of running the integrator using our example:

   XSLT content is applied with priority when publishing to both HTML and PDF outputs.

   1. For the HTML output, in the XSLT stylesheet DITA_OT_DIR/xsl/dita2html-base.xsl a new import automatically appeared:

      <xsl:import href="../plugins/com.oxygenxml.highlight/xhtmlHighlight.xsl"/>

      This import is placed after all base imports and thus has a higher priority. For more information about imported template precedence, see: http://www.w3.org/TR/xslt#import.

   2. Likewise, for the PDF output, in the top-level stylesheet DITA_OT_DIR/plugins/org.dita.pdf2/xsl/fo/topic2fo_shell_fop.xsl a new import statement appeared:

      <xsl:import href="../../../com.oxygenxml.highlight/pdfHighlight.xsl"/>

Now, you can distribute your plugin folder to anyone that has a DITA OT installation along with some simple installation notes. Your customization will work provided that the templates you are overwriting have not changed from one DITA OT distribution to the other.