Overriding the XSLT Processing Step of a DITA WebHelp Transformation

There are several methods that you can use to customize your WebHelp output. Since WebHelp output is primarily obtained by running XSLT transformations over the DITA input files (through the DITA Map WebHelp transformation scenarios), one possibility would be to override the default XSLT templates that are used for WebHelp transformations by using some extension points.

XSLT-Import Extension Points

You can customize your WebHelp output by overriding the default XSLT templates that are used for each type of WebHelp transformation. This can be done by creating a DITA extension plugin that specifies one of the following extension points:

com.oxygenxml.webhelp.xsl.dita2webhelp: You can use this extension point to override a template of the XSLT stylesheet (dita2webhelpImpl.xsl) that produces an HTML file for each DITA topic. Depending on the type of WebHelp transformation you are currently using, the path to this stylesheet is as follows:

WebHelp Classic Transformations - DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\desktop\dita2webhelpImpl.xsl

WebHelp Classic Mobile Transformations - DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\mobile\dita2webhelpImpl.xsl

WebHelp Responsive Transformations - DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\responsive\dita2webhelpImpl.xsl
com.oxygenxml.webhelp.xsl.createMainFiles: You can use this extension point to override a template of the XSLT stylesheet (createMainFilesImpl.xsl) that produces the WebHelp main HTML page. Depending on the type of WebHelp transformation you are currently using, the path to this stylesheet is as follows:

WebHelp Classic Transformations - DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\desktop\createMainFilesImpl.xsl

WebHelp Classic Mobile Transformations - DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\mobile\createMainFilesImpl.xsl

WebHelp Responsive Transformations - DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\responsive\createMainFilesImpl.xsl

Attention

The customizations you made by using this extension point will affect all WebHelp transformations. If you want to have a customization that is only available for a certain plugin, please use the Overriding the XSLT Stylesheet from a Customized ANT Build File method.

XSLT-Parameter Extension Points

In case your customization stylesheet declares one or more XSLT parameters and you want to control their value from the transformation scenario, you can use one of the following XSLT parameter extension points:

com.oxygenxml.webhelp.xsl.dita2webhelp.param: Use this extension point to pass parameters to the stylesheet specified using the com.oxygenxml.webhelp.xsl.dita2webhelp extension point.
com.oxygenxml.webhelp.xsl.createMainFiles.param: Use this extension point to pass parameters to the stylesheet specified using the com.oxygenxml.webhelp.xsl.createMainFiles extension point.

Overriding the XSLT Stylesheet from a Customized Ant Build File

This method is useful if you want to create a customization that is only available for a certain DITA-OT extension plugin. This method implies that you create a DITA-OT plugin that defines a custom transtype. From the Ant target associated with the plugin transtype, you will specify a custom XSLT stylesheet. This customized XSLT stylesheet will import the original WebHelp stylesheet and will also add some customization templates.

If you want to use this method, you need to create a DITA-OT extension plugin, as in the following sample procedure for customizing WebHelp Responsive output:

In the DITA_OT_DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.webhelp.responsive.custom).

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.customization">
    <feature extension="dita.conductor.target.relative" file="integrator.xml"/>
    <transtype name="webhelp-responsive-custom" extends="webhelp-responsive" 
      desc="WebHelp Responsive Customization"/>
</plugin>

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>

Create the build.xml file that overrides the value of properties associated with the XSLT stylesheets used to produce HTML files. The following two Ant properties can be overridden to specify your customization stylesheets:

args.wh.xsl: Override this property if you want to customize the XSLT stylesheet used to produce an HTML file for each topic.
args.create.main.files.xsl: Override this property if you want to customize the XSLT stylesheet used to produce the main HTML file.

For customizing the WebHelp Responsive, the build file should look like:

<project basedir="." name="Webhelp Responsive Customization">  
 <target name="dita2webhelp-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.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.create.main.files.xsl" 
     value="${dita.plugin.com.oxygenxml.webhelp.responsive.custom.dir}
                                              /xsl/createMainFilesCustom.xsl"/>
   <!--
     Depending on which version of WebHelp you want to customize, 
     you need to delegate to different build targets:
     * dita2webhelp-responsive - when you are customizing the Webhelp Responsive
     * dita2webhelp-mobile - when you are customizing the Webhelp Mobile
     * dita2webhelp - when you are customizing the Webhelp Classic
   -->
   <antcall target="dita2webhelp-responsive"/>
 </target>  
</project>

Note

Depending on which version of WebHelp you want to customize, you need to specify one of the following build targets:

dita2webhelp-responsive - To customize WebHelp Responsive (with or without feedback) output.
dita2webhelp-mobile - To customize WebHelp Classic Mobile output.
dita2webhelp - To customize WebHelp Classic (with or without feedback) output.

Create an xsl directory in the plugin customization directory (that you created in step 1) to store the customized XSLT stylesheets.

Customizing the XSLT Stylesheet to Produce an HTML File for Each Topic

If you want to produce an HTML file for each topic (defined with the args.wh.xsl property), create a dita2webhelpCustom.xsl stylesheet and save it in the newly created xsl directory. This stylesheet will import the original stylesheet and will contain the customization templates. It 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.dita-ot.plugin.webhelp:xsl/
                                             dita/responsive/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-responsive (WebHelp Responsive) -

<xsl:import href="plugin:com.oxygenxml.dita-ot.plugin.webhelp:xsl/dita/responsive/dita2webhelp.xsl"/>
dita2webhelp-mobile (WebHelp Classic Mobile) -

<xsl:import href="plugin:com.oxygenxml.dita-ot.plugin.webhelp:xsl/dita/mobile/dita2webhelp.xsl"/>
dita2webhelp (WebHelp Classic) -

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

Customizing the XSLT Stylesheet to Produce the Main HTML File

If you just want to produce a main HTML file (defined with the args.create.main.files.xsl property), you need to create a createMainFilesCustom.xsl stylesheet and save it in the newly created xsl directory. This stylesheet will import the original stylesheet and will contain the customization templates. It 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.dita-ot.plugin.webhelp:xsl/dita/
                                               responsive/createMainFiles.xsl"/>
    <!--
        Please add your customization templates here.
    -->
        
</xsl:stylesheet>