Adding Labels to Topics in the WebHelp Responsive Output

13 Dec 2021

Read time: 6 minute(s)

DITA topics can contain <keyword> elements that are usually placed in a <prolog> element, but they can also be used inside the topic body contents.

<topic id="topicID">
    <title>DITA 1.3 Features</title>
    <prolog>
        <metadata>
            <keywords>
                <keyword>DITA 1.3</keyword>
            </keywords>
        </metadata>
    </prolog>...

The Oxygen WebHelp Responsive output uses these keywords as a way of giving more priority to certain sequences of words when searching for content. By default, keywords do not appear in the published output.

This article is an attempt to add a new concept of a label:

A label is a keyword element with a special @outputclass="label" attribute. The label is always visible in the published output. It can be placed either in a prolog section or anywhere inside the topic where a keyword is allowed.
When a label is selected, the WebHelp output displays all other topics that have the same label value set to them.

Inserting Labels

We can decide to use the DITA <keyword> element with a certain @outputclass attribute value set to label to insert such keywords that should be displayed in the published output.

<topic id="topicID">
    <title>DITA 1.3 Features</title>
    <prolog>
        <metadata>
            <keywords>
                <keyword outputclass="label">DITA 1.3</keyword>
            </keywords>
        </metadata>
    </prolog>...

To make the insertion of such labels easier, you can, for example, create a custom Author action that inserts the labels and add the custom action to the content completion window: Adding a Custom Author Action to the Content Completion Window.

To have special styling for the inserted labels when editing, you can customize the CSS stylesheets used for DITA editing: Customizing the DITA Visual Editing Experience.

Factoring Labels When Publishing

DITA WebHelp output can be customized using a publishing template mechanism. Inside a publishing template folder, there is an opt file that can contain links to various XSLT stylesheets that are useful for customizations. For example, we'll add a link to a stylesheet for processing such special keyword label elements:

<publishing-template>
    <name>.....</name>
    ......
        <xslt>
            ....
            <extension file="xslt/labels-show.xsl" id="com.oxygenxml.webhelp.xsl.dita2webhelp"/>
            .....
        </xslt>
    </webhelp>
</publishing-template>

The labels-show.xsl stylesheet will match all labels and display them after the title of each topic. For each label, it will have a link to search the entire documentation for the same label:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    exclude-result-prefixes="xs"
    version="2.0">
    <xsl:template match="*[contains(@class, ' topic/prolog ')]">
        <!-- create a special div which displays all labels, with a link on each label -->
        <xsl:if test=".//keyword[@outputclass = 'label']">
            <div style="width:100%; text-align: right; font-style:italic; color:gray;">Labels:
                <xsl:apply-templates select=".//keyword[@outputclass = 'label']"/>
            </div>
        </xsl:if>
        <xsl:next-match/>
    </xsl:template>
    
    <!-- Match a label keyword and display it as a span -->
    <xsl:template match="keyword[@outputclass = 'label']">
        <a
            href="{concat('../search.html?searchQuery=label_', normalize-space(translate(text(), ' ', '_')))}">
            <span style="background-color:deepskyblue;color:white;border-radius: 6px;margin:0.2em;padding:0.2em;"
                ><xsl:value-of select="text()"/></span>
        </a>
    </xsl:template>
    
    <!-- Add specific HTML meta elements for each label -->
    <xsl:template match="*" mode="gen-keywords-metadata">
        <xsl:next-match/>
        <xsl:variable name="keywords-content">
            <!-- for each label -->
            <xsl:for-each select="//keyword[@outputclass = 'label']">
                <xsl:value-of
                    select="concat('label_', normalize-space(translate(text(), ' ', '_')))"/>
                <xsl:if test="position() &lt; last()">
                    <xsl:text>, </xsl:text>
                </xsl:if>
            </xsl:for-each>
        </xsl:variable>
        
        <xsl:if test="string-length($keywords-content) > 0">
            <meta name="keywords" content="{$keywords-content}"/>
        </xsl:if>
    </xsl:template>
</xsl:stylesheet>

The end result displays labels defined in each topic and allows you to click on each label and find all topics with the same label.

The Oxygen blog uses this customization and some of the articles in the blog have labels defined on them: DITA 1.3 Branch Filtering - Next Generation of Reuse.

The WebHelp publishing template used for publishing this blog already has a customization to display labels in the blog articles: https://github.com/oxygenxml/blog/tree/master/publishing/webhelpBlogTemplate.