Edit online

Creating a DITA-OT Plugin

Oxygen XML Author provides the ability to install additional DITA Open Toolkit plugins that can be found from various sources (for example, Oxygen's public GitHub repository includes some DITA-OT plugins). It is also possible to create your own plugin.

CAUTION: Oxygen XML Author support engineers do not officially offer support and troubleshooting assistance for custom DITA-OT distributions or custom installed DITA-OT plugins. If you discover any issues or inconsistent behavior while using a custom DITA-OT or a DITA-OT that contains custom DITA-OT plugins, you should revert to the default built-in DITA-OT.

To create a DITA-OT plugin, follow these steps:

  1. Create a new folder in the plugins folder located in your DITA-OT directory (for example, if you are using DITA 4.1.2, the path would look like this: [OXYGEN_INSTALL_DIR]/frameworks/dita/DITA-OT/plugins/MyNewPlugin).
  2. Create a plugin.xml file in that same folder. This file will contain the extension points for the plugin. For example, references to the XSLT stylesheets that will be used to style the output.
    Note: You can easily create this file by using the DITA-OT Plugin new document template that is included in Oxygen XML Author (from the New document wizard you can find this template in Framework templates > DITA > plugin.
    Example:
    <plugin id="org.metadita.specialization.music">
  <feature extension="dita.specialization.catalog.relative" 
           file="catalog-dita.xml"/>
  <feature extension="dita.xsl.xhtml" file="xsl/music2xhtml.xsl"/>
  <feature extension="dita.xsl.html5" file="xsl/music2xhtml.xsl"/>
</plugin>
    Tip: Oxygen XML Author includes special editing support when adding extension points in the plugin.xml file. If you place the cursor in the value of the @extension attribute and press Ctrl+Space, a list of possible extension points is presented with links to the DITA-OT documentation. For more information about extension points that are available to use in the plugin.xml file, see: http://www.dita-ot.org/dev/extension-points/extension-points-by-plugin.html.
  3. Install the newly created DITA-OT plugin by running the built-in transformation scenario called Integrate/Install DITA-OT Plugins from the Apply Transformation Scenario(s) or Configure Transformation Scenario(s) dialog box.
    Note: If the integrator is not visible, select the Show all scenarios option in the Settings drop-down menu.

You can share your new plugin with other users who have the same DITA-OT distribution by sending them your newly created folder along with the installation instructions.

Edit online

Example: Creating a DITA-OT Plugin for Embedding Video Resources

To offer a detailed example of the steps required to create a new DITA Open Toolkit plugin, this topic uses an example of creating an XSLT customization plugin that provides support for referencing video and audio content using the DITA <object> element and then publishing to HTML and PDF output formats. This plugin (com.oxygenxml.media) is available in the DITA Open Toolkit distribution that comes bundled with the latest version of Oxygen XML Author, but these instructions show you how you could create it if it were not included.

The following procedure is meant to help you with creating the plugin:

  1. Create a folder for your plugin in the DITA-OT plugins folder (DITA-OT-DIR/plugins/).
  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 template that is included in Oxygen XML Author (from the New document wizard you can find this template in Framework templates > DITA > plugin).
    Example: Media Plugin File
    <plugin id="com.oxygenxml.media">
  <feature extension="package.support.name" value="Oxygen XML Editor Support"/>
  <feature extension="package.support.email" value="support@oxygenxml.com"/>
  <feature extension="package.version" value="21.0"/>
  <feature extension="dita.xsl.xhtml" value="xhtmlMedia.xsl" type="file"/>
  <feature extension="dita.xsl.xslfo" value="pdfMedia.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://www.dita-ot.org/dev/extension-points/extension-points-by-plugin.html.

  3. Create an XSLT stylesheet to customize the output types. In this example, to customize the HTML output, it is necessary to create an XSLT stylesheet called xhtmlMedia.xsl (in the same plugin folder).
    Tip: You can use the Find/Replace in Files action 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. For example, suppose you want to overwrite HTML content produced from a DITA codeblock element. Since a DITA <object> element has the @class attribute value - topic/object , you can take part of the class attribute value (topic/object) and search the DITA-OT resources for a similar stylesheet. The search might find the XSLT stylesheet DITA-OT-DIR/plugins/org.dita.xhtml/xsl/xslhtml/xsl/xslhtml/dita2htmlImpl.xsl.
    You can use it as a starting point to overwrite the xhtmlMedia.xsl stylesheet. For example, the results might be:
    <xsl:template 
   match="*[contains(@class, ' topic/object ')][contains(@outputclass, 'video')]">
 <video class="embed-responsive-item">
   <xsl:call-template name="commonattributes"/>
   <xsl:call-template name="setidaname"/>
   <xsl:call-template name="copySource"/>
 </video>
</xsl:template>

  4. Create additional XSLT stylesheets to customize all other desired output types. In this example, to customize the PDF output it is necessary to create an XSLT stylesheet called pdfMedia.xsl (in the same plugin folder).

    In this case, you might find an appropriate XSLT stylesheet called DITA-OT-DIR/plugins/org.dita.pdf2/xsl/fo/topic.xsl to use as a starting point to overwrite the pdfMedia.xsl stylesheet, with results looking something like this:
    <!--Treat video, audio or iframe objects as links-->
<xsl:template 
           match="*[contains(@class,' topic/object ')][@outputclass = 'video']">
    <xsl:variable name="target" select="@data"/>
    <xsl:variable name="baseDir">
      <xsl:call-template name="substring-before-last">
       <xsl:with-param name="text" select="@xtrf"/>
       <xsl:with-param name="delim" select="'/'"/>
      </xsl:call-template>
    </xsl:variable>
  
     <fo:inline xsl:use-attribute-sets="object">
       <xsl:call-template name="commonattributes"/>
        <xsl:if test="exists($target)">
           <fo:basic-link external-destination="url({$target})" 
                                      xsl:use-attribute-sets="xref">
              <xsl:value-of select="$target"/>
           </fo:basic-link>                        
        </xsl:if>
     </fo:inline>
</xsl:template>

  5. To install the created plugin in the DITA-OT, run the built-in transformation scenario called Integrate/Install DITA-OT Plugins by executing it from the Apply Transformation Scenario(s) dialog box. If the integrator is not visible, select the Show all scenarios option that is available in the Settings drop-down menu. For more information, see Installing a DITA-OT Plugin.

    Results of running the integrator using the media plugin 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/plugins/org.dita.xhtml/xsl/dita2html-base.xsl, a new import automatically appeared:
      <xsl:import href="../plugins/com.oxygenxml.media/xhtmlMedia.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.media/pdfMedia.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 the templates you are overwriting have not changed from one DITA-OT distribution to the other.