Overriding a WebHelp XSLT Stylesheet from an Ant Build File

To create a WebHelp Responsive XSLT customization that is only available for a certain DITA OT transformation, the extension plugin should declare a custom transtype. The WebHelp Responsive 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 Responsive 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.responsive.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.responsive.custom">
        <feature extension="dita.conductor.target.relative" file="integrator.xml"/>
        <transtype name="webhelp-responsive-custom" extends="webhelp-responsive" 
          desc="WebHelp Responsive Customization"/>
    </plugin>
  3. Create the integrator.xml file that will import the actual plugin Ant build file.
    <project basedir="." name="Webhelp Responsive 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.whr.topic.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce an HTML file for each topic.
    args.whr.create.main.page.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the HTML file associated with the main page.
    args.whr.create.search.page.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the HTML file associated with the search page.
    args.whr.create.indexterms.page.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the HTML file associated index the terms page.
    args.whr.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 Responsive transformation type, the build file should look like:

    <project basedir="." name="Webhelp Responsive Customization">  
     <target name="dita2webhelp-responsive-custom">    
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce an HTML file for each topic 
       -->    
       <property 
         name="args.whr.topic.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.responsive.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.whr.create.main.page.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.responsive.custom.dir}
                                                  /xsl/createMainPageCustom.xsl"/>
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce the search HTML file.
       -->    
       <property 
         name="args.whr.create.search.page.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.responsive.custom.dir}
                                                  /xsl/createSearchPageCustom.xsl"/>
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce the indexterms HTML file.
       -->    
       <property 
         name="args.whr.create.indexterms.page.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.responsive.custom.dir}
                                                  /xsl/createIndextermsPageCustom.xsl"/>
       <!-- 
         Override this property if you want to customize the XSLT stylesheet 
         used to produce the toc.xml file.
       -->    
       <property 
         name="args.whr.createTocXML.xsl" 
         value="${dita.plugin.com.oxygenxml.webhelp.responsive.custom.dir}
                                                  /xsl/createTocXMLCustom.xsl"/>
       <!--
         Now you need to delegate to the main target of the WevHelp Responsive transformation
       -->
       <antcall target="dita2webhelp-responsive"/>
     </target>  
    </project>
  5. Create an xsl directory in the plugin customization directory (that you created in step 1) to store the customized XSLT stylesheets.
  6. Install the extension plugin 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 Responsive stylesheets, you can use the plugin:com.oxygenxml.webhelp.responsive prefix. This prefix is rewritten by an XML catalog to the WebHelp Responsive 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.responsive:xsl/
                                             dita2webhelp/dita2webhelp.xsl"/>
   <!--
     Please add your customization templates here.
   -->
</xsl:stylesheet>
Customizing the createMainPage.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp createMainPage.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.responsive:xsl/mainFiles/
                                               createMainPage.xsl"/>
    <!--
        Please add your customization templates here.
    -->
        
</xsl:stylesheet>
Customizing the createSearchPage.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp createSearchPage.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 search HTML file.
    -->
    <xsl:import href="plugin:com.oxygenxml.webhelp.responsive:xsl/mainFiles/
                                               createSearchPage.xsl"/>
    <!--
        Please add your customization templates here.
    -->
        
</xsl:stylesheet>
Customizing the createIndextermsPage.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp createIndextermsPage.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 indexterms HTML file.
    -->
    <xsl:import href="plugin:com.oxygenxml.webhelp.responsive:xsl/mainFiles/
                                               createIndextermsPage.xsl"/>
    <!--
        Please add your customization templates here.
    -->
        
</xsl:stylesheet>
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.responsive:xsl/toc/tocDita.xsl"/>
    <!--
        Please add your customization templates here.
    -->        
</xsl:stylesheet>