Related Link Handling

Link Groupings

The default template for <related-links> looks like this:

<xsl:template match="&related-links;[.//&link;]"
  priority="-20" mode="#default html">
  <div>
    <xsl:call-template name="generate-common-attrs" />
    <xsl:call-template name="do-child-links" />
    <xsl:call-template name="do-sequence-links" />
    <xsl:call-template name="do-sibling-links" />
    <xsl:call-template name="do-link-groups" />
    <xsl:call-template name="do-other-links" />
    <xsl:call-template name="do-parent-links" />
  </div>
</xsl:template>

It calls the following named templates, in this order.

1. do-child-links (role="child")
2. do-sequence-links (role="previous" and role="next")
3. do-sibling-links (role="sibling")
4. do-link-groups (links wrapped in <linklist>)
5. do-other-links (all other links except @role="parent")
6. do-parent-links (role="parent")

You can override this template to change the order of links in HTML output, or to eliminate various groups of links.

Default Link Structures

The <linklist> element is converted into an <ol>, and each link it contains is wrapped in <li>. Other links are simply placed within <div> elements. Within its container, each link consists of

1. An <a> tag, with the link itself.
2. For child links, a <div> containing the short description of the topic, if present. (The DITA engine also generates or populates <desc> tags for related links when possible in the XML presented to the stylesheet.)

Customizing Link Presentation

The built-in related links module includes two special modes for customizing link presentation.

get-link-label

Used to get a label for the link. This is separate from the link text. By default, the module provides "Previous Topic," "Next Topic," and "Parent topic" for @role='previous', @role='next', and @role='parent' links, respectively.

get-link-class-tokens

This mode is used to retrieve any additional HTML @class attribute tokens to include on the generated wrapper element for the link. By default, the @class attribute will include the link tag's specialization hierarchy as well as the value of the @role attribute.

For example, to provide custom @class and label for links whose @role is "sibling", you could add code like the following.

<xsl:template match="&link;[@role='sibling']" mode="get-link-label">
  <xsl:text>Sibling Topic:</xsl:text>
</xsl:template>

<xsl:template match="&link;[@role='sibling']" mode="get-link-class-tokens">
  <xsl:text>sibling-link my-special-class</xsl:text>
</xsl:template>