Adding Labels to Topics in the WebHelp Responsive Output
<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.
- 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
<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
<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() < 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.
![](../images/webhelp-labels.png)
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.