Overriding a WebHelp Classic XSLT Stylesheet from an Ant Build File

To create a WebHelp XSLT customization that is only available for a certain DITA OT transformation, the extension plugin should declare a custom transtype. The WebHelp XSLT stylesheets can be overridden from an ANT file provided by the DITA-OT extension plugin. From the Ant target associated with the plugin, you will specify a custom XSLT stylesheet that imports the original WebHelp stylesheet and add some customization templates.

The following procedure explains how to create a DITA-OT extension plugin that uses this extension method:

  1. In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.webhelp.classic.custom).
  2. Create a plugin.xml file (in the folder you created in step 1) that specifies a new DITA-OT transtype and the build file associated with the plugin. For example:
    <plugin id="com.oxygenxml.webhelp.classic.custom">
        <feature extension="dita.conductor.target.relative" file="integrator.xml"/>
        <transtype name="webhelp-classic-custom" extends="webhelp" 
          desc="WebHelp Classic Customization"/>
    </plugin>
  3. Create the integrator.xml file that will import the actual plugin Ant build file.
    <project basedir="." name="Webhelp Classic Customization">    
        <import file="build.xml"/>
    </project>
  4. Create the build.xml file that overrides the value of properties associated with the XSLT stylesheets used to produce HTML files. The following Ant properties can be overridden to specify your customization stylesheets:
    args.wh.classic.topic.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce an HTML file for each topic.
    args.wh.classic.create.main.files.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the main HTML files.
    args.wh.classic.createTocXML.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the toc.xml file. The toc.xml file contains information extracted from DITA map and it is mainly used to create the WebHelp TOC.

    For example, to customize a WebHelp Classic transformation type, the build file should look like:

    <project basedir="." name="Webhelp Classic Customization">  
     <target name="dita2webhelp-classic-custom">    
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce an HTML file for each topic 
       -->    
       <property 
         name="args.wh.classic.topic.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.classic.custom.dir}
                                                     /xsl/dita2webhelpCustom.xsl"/>
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce the main HTML file.
       -->    
       <property 
         name="args.wh.classic.create.main.files.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.classic.custom.dir}
                                                  /xsl/createMainFilesCustom.xsl"/>
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce the toc.xml file.
       -->    
       <property 
         name="args.wh.classic.createTocXML.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.classic.custom.dir}
                                                  /xsl/createTocXMLCustom.xsl"/>
       <!--
         Depending on which version of WebHelp you want to customize, 
         you need to delegate to different build targets:
         * dita2webhelp-mobile - when you are customizing the Webhelp Mobile
         * dita2webhelp - when you are customizing the Webhelp Classic
       -->
       <antcall target="dita2webhelp"/>
     </target>  
    </project>
    Note: Depending on which version of WebHelp you want to customize, you need to call one of the following build targets:
    • dita2webhelp - For WebHelp Classic (with or without feedback) output.

    • dita2webhelp-mobile - For WebHelp Classic Mobile output (deprecated).

  5. Create an xsl directory in the plugin customization directory (that you created in step 1) to store the customized XSLT stylesheets.
  6. Now that the extension plugin is created, install it in the DITA Open Toolkit.

Referencing the WebHelp XSLT Stylesheets from Your Customizations

Note that your customization stylesheets should import the original stylesheets that they override. To reference the WebHelp stylesheets, you can use the plugin:com.oxygenxml.dita-ot.plugin.webhelp prefix. This prefix is rewritten by an XML catalog to the WebHelp root directory.

Customizing the dita2webhelp.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp dita2webhelp.xsl stylesheet should look like:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:math="http://www.w3.org/2005/xpath-functions/math"
   exclude-result-prefixes="xs math"
   version="2.0">    
   <!--
     Import the original stylesheet used to produce an HTML file for each topic.
   -->
   <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/
                                             dita/classic/dita2webhelp.xsl"/>
   <!--
     Please add your customization templates here.
   -->
</xsl:stylesheet>
Depending on which version of WebHelp you want to customize, you need to import one of the following XSLT stylesheets:
  • dita2webhelp (WebHelp Classic) -

    <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/desktop/dita2webhelp.xsl"/>

Customizing the createMainFiles.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp createMainFiles.xsl stylesheet should look like:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:math="http://www.w3.org/2005/xpath-functions/math"
    exclude-result-prefixes="xs math"
    version="2.0">    
    <!--
        Import the original stylesheet used to produce the main HTML file.
    -->
    <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/
                                               desktop/createMainFiles.xsl"/>
    <!--
        Please add your customization templates here.
    -->
        
</xsl:stylesheet>
Depending on which version of WebHelp you want to customize, you need to import one of the following XSLT stylesheets:
  • dita2webhelp (WebHelp Classic) -

    <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/desktop/createMainFiles.xsl"/>

Customizing the tocDita.xsl File
The XSLT stylesheet that customizes the WebHelp tocDita.xsl stylesheet should look like:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:math="http://www.w3.org/2005/xpath-functions/math"
    exclude-result-prefixes="xs math"
    version="2.0">    
    <!--
        Import the original stylesheet used to produce the toc.xml file.
    -->
    <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/tocDita.xsl"/>
    <!--
        Please add your customization templates here.
    -->        
</xsl:stylesheet>