Difficulty: ★★☆ (medium)
Keywords: breadcrumbs, navigation

Problem

You want to display a “path” to your current chapter, section etc. to improve fast jumping to parent structures.

Solution

Use breadcrumbs[10] to improve navigation. Use the following procedure to create breadcrumbs for your documents:

  1. Create a customization layer as shown in Section 2.3, “Writing Customization Layers”.

  2. Create a file breadcrumbs.xsl with the following content:

    <xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:d="http://docbook.org/ns/docbook"
      xmlns="http://www.w3.org/1999/xhtml"
      exclude-result-prefixes="d">
    
      <xsl:param name="breadcrumbs.separator" select="' > '"/>
    
      <xsl:template name="generate.breadcrumbs">
        <xsl:param name="current.node" select="."/>
        <div class="breadcrumbs">
          <xsl:for-each select="$current.node/ancestor::*">
            <span class="breadcrumb-link">
              <a>
                <xsl:attribute name="href">
                  <xsl:call-template name="href.target">
                    <xsl:with-param name="object" select="."/>
                    <xsl:with-param name="context" select="$current.node"/>
                  </xsl:call-template>
                </xsl:attribute>
                <xsl:apply-templates select="." mode="title.markup"/>
              </a>
            </span>
            <xsl:copy-of select="$breadcrumbs.separator"/>
          </xsl:for-each>
          <!-- Display the current node, but not as a link -->
          <span class="breadcrumb-node">
            <xsl:apply-templates select="$current.node" mode="title.markup"/>
          </span>
        </div>
      </xsl:template>
    </xsl:stylesheet>
    

    1

    Parameter to separate each component

    2

    Iterates over the ancestor axis

    3

    Creates the href attribute by calling href.target to create appropriate link references even for chunked output

    4

    Inserts the processed title

    5

    Inserts the breadcrumbs separator

    6

    Inserts the processed title of the current node but not as a link

  3. Include breadcrumbs.xsl into your customization layer from Step 1:

    <xsl:include href="breadcrumbs.xsl"/>
  4. Add the following code into your customization layer:

    <xsl:template name="user.header.content">
      <xsl:call-template name="generate.breadcrumb"/>
    </xsl:template>
  5. Build your document with your customization layer.

For example, consider the current topic. It is embedded into this nested structure:

book: The DoCookBook
  chapter: (X)HTML Customizations
     sect1: Implementing “Breadcrumbs”

The above breadcrumbs.xsl stylesheets creates this HTML code when the current node is this topic:

<div class="breadcrumbs">
  <span><a href="...X...">The DoCookBook</a></span>
  >
  <span><a href="...Y...">(X)HTML Customizations</a></span>
  >
  <span class="breadcrumb-node">Implementing “Breadcrumbs”</span>
</div>

Leading to the following appearance:

The DoCookBook > (X)HTML Customizations > Implementing “Breadcrumbs”

Whereas all spans contains links to their respective components except the last one.

Discussion

TBD

See Also


[10] Breadcrumbs are a navigation aid and show the titles from the top page to the current page. The term origins from the trail of breadcrumbs left by Hänsel and Gretel in the popular fairytale written by the Brothers Grimm.


Project@GitHubIssue#10