Changing the Topics Displayed in the WebHelp Responsive Side TOC

Use-Case 1: Customizing the Side TOC Using a WebHelp XSLT-Import Extension Point

Suppose you want to customize this mini table of contents to only include the current topic and its child topics (while excluding its siblings and ancestors).

Example: Filtered Side Table of Contents

The default XSLT template responsible for this functionality is defined in: DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\dita\responsive\navigationLinks.xsl.

<xsl:template
    match="
    toc:topic
    [not(@toc = 'no')]
    [not(@processing-role = 'resource-only')]"
    mode="toc-pull" priority="10">

This templates computes the link for the current topic along with the links for the sibling topics, and then propagates them recursively to the parent topic. For the specific use-case described above, you need to override this template so that it will produce the link for the current topic along with just the child links that the template already receives.

To add this functionality without modifying the sources of the WebHelp plugin, you can implement an external DITA-OT plugin that uses the com.oxygenxml.webhelp.xsl.dita2webhelp extension point. This extension point allows you to specify a customization stylesheet that will override the template described above.

To add this functionality as a DITA-OT plugin, follow these steps:

1. In the DITA_OT_DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.webhelp.custom.sidetoc).
2. Create a plugin.xml file (in the folder you created in step 1) that specifies the extension point and your customization stylesheet. For example:

   <plugin id="com.oxygenxml.webhelp.custom.sidetoc">
       <feature extension="com.oxygenxml.webhelp.xsl.dita2webhelp"
        file="custom_side_TOC.xsl"/>    
   </plugin>

3. Create your customization stylesheet (for example, custom_side_TOC.xsl), and edit it to override the template that produces the side TOC:

   <xsl:template
           match="
           toc:topic
           [not(@toc = 'no')]
           [not(@processing-role = 'resource-only')]"
           mode="toc-pull" 
           priority="10">
           
           <xsl:param name="pathFromMaplist" as="xs:string"/>
           <xsl:param name="children" select="()" as="element()*"/>
           <xsl:param name="parent" select="parent::*" as="element()?"/>
           
           <xsl:apply-templates select="." mode="sideTocEntry">
             <xsl:with-param name="pathFromMaplist" select="$pathFromMaplist"/>
             <xsl:with-param name="children" select="$children"/>
           </xsl:apply-templates>
   </xsl:template>

4. Run the Run DITA OT Integrator transformation scenario.
5. Run a DITA Map WebHelp Responsive transformation scenario to obtain the customized side TOC.

Use-Case 2: Customizing the Side TOC Dynamically with a WebHelp XSLT-Parameter Extension Point

Another use-case might be if you want to control what is displayed in the side table of contents more dynamically, meaning that you can declare XSLT parameters in your customization stylesheet and control the parameter values from the transformation scenario. For this use-case, you can use the com.oxygenxml.webhelp.xsl.dita2webhelp.param extension point.

Suppose that you want to add a parameter to control whether the side TOC will only contain the current topic along with its children or if it will contain all the topics in the default form (with the current, sibling, child, and parent topics all displayed).

To add this functionality, follow these steps:

1. Create a DITA-OT plugin structure by following the first 3 steps in the procedure above.
2. In the customization stylesheet that you created in step 3, declare the side_toc_only_children parameter and modify the template to match the topic only when the side_toc_only_children parameter is set to yes:

   <xsl:param name="side_toc_only_children" select="'yes'"/>
   ...
   <xsl:template
           match="
           toc:topic
           [not(@toc = 'no')]
           [not(@processing-role = 'resource-only')]
           [$side_toc_only_children = 'yes']"
   ...

3. Edit the plugin.xml file to specify the com.oxygenxml.webhelp.xsl.dita2webhelp.param extension point and a custom parameter file by adding the following line:

   <feature extension="com.oxygenxml.webhelp.xsl.dita2webhelp.param" 
    file="custom_params.xsl"/>

4. Create a custom parameter file (for example, custom_params.xml). It should look like this:

   <dummy>
       <param name="side_toc_only_children" expression="${side_toc_only_children}"
        if="side_toc_only_children"/>
   </dummy>

5. Run the Run DITA OT Integrator transformation scenario.
6. Edit a DITA Map WebHelp Responsive transformation scenario and in the Parameters tab, specify the desired value (yes or no) for your custom parameter (side_toc_only_children).
7. Run the transformation scenario.