Blog - XSL Contents

While I was building this website, I thought it would be nice to put a contents page on pages that have multiple sections, such as this one. This would allow people to jump directly to the section that they were interested in, as well as providing a summary of the page. Updating the contents page manually soon became a chore, and I would often forget, or make spelling mistakes that stopped it from working. What was needed was a way of creating contents pages automatically. As I was already using XSLT to create the pages to a standard template it seemed the best way to create the contents list would be to use XSLT.

The Problem

What I wanted to do was to take a document that was structured like this…

<h3>Heading 1</h3>
<p>Text</p>
<p>More text</p>
<h3>Heading 2</h3>
<p>Text</p>
<p>More text</p>

...and transform it into something like this…

 <ul>
  <li>
   <a href="#Heading_1">Heading 1</a>
  </li>
  <li>
    <a href="#Heading_2">Heading 2</a>
  </li>
 </ul>
 <h3 id="Heading_1">Heading 1</h3>
 <p>Text</p>
 <p>More text</p>
 <h3 id="Heading_2">Heading 2</h3>
 <p>Text</p>
 <p>More text</p>

As you can see the contents list is contained in an unordered list, and each list item contains a link to the heading, using id tags. The headings have had their id tags automatically inserted. The id tag names are taken from the headings, so that it is easy to link to them from other pages. However it should also be possible to specify an id tag.

First Attempt

For the initial attempt I’m going to assume that the headers already have id tags, and look like this…

 <h3 id="Heading_1">Heading 1</h3>
 <p>Text</p>
 <p>More text</p>
 <h3 id="Heading_2">Heading 2</h3>
 <p>Text</p>
 <p>More text</p>

I’m also going to assume that the XSL template copies the body of the document across ‘as is’...

 <xsl:template match="html">
   <xsl:copy>
     <xsl:apply-templates select="*" mode="BodyCopy" />
   </xsl:copy>
 </xsl:template>

 <xsl:template match="*" mode="BodyCopy">
   <xsl:copy>
     <xsl:apply-templates select="*" mode="BodyCopy" />
   </xsl:copy>
 </xsl:template>

The mode attribute allows different templates to match the same elements at different times. Thus the above template ensures that all elements are copied when in ‘BodyCopy’ mode. In order to insert the contents somewhere useful we’re going to define a new element type. This will not be copied into the final document, instead it will be replaced with the contents table.

 <xsl:template match="contents" mode="BodyCopy">
   <ul>
     <xsl:apply-templates select="html/body/*" mode="ContentsList" />
   </ul>
 </xsl:template>

 <xsl:template match="*" mode="ContentsList">
   <xsl:apply-templates select="*" mode="ContentsList" />
 </xsl:template>

 <xsl:template match="h3" mode="ContentsList">
   <li>
     <a href="{concat('#', @id)}" title="normalize-space(.)">
       <xsl:value-of select="normalize-space(.)" />
     </a>
   </li>
 </xsl:template>

This creates the <ul> tags, and selects the top of the source document to start the search for <h3> tags. This search is done in ‘ContentsList’ mode, and nothing is copied by default. When it comes across an <h3> it creates a list item that links to an element in the document with the id tag. The text and title of the link are taken from the contents of the header tags.

A More Sophisticated Solution

The problem with the previous example is that all the <h3> tags need to have their id attributes set, which is the kind of tedious task the computer should do for itself. Inserting the attributes can not happen as part of the ‘ContentsList’ mode, as it is only reading elements, and can not edit them. Instead we will change the elements during the main copying routine. A small template is used to create the id, so that it is the same in both places.

 <xsl:template name="getId">
   <xsl:value-of select="normalize-space(@id)" />
   <xsl:if test="not(@id)">
     <xsl:value-of select="translate(normalize-space(.), ' ', '_')" />
   </xsl:if>
 </xsl:template>
 <xsl:template match="h3" mode="ContentsList">
   <li>
     <xsl:variable name="id">
       <xsl:call-template name="getId" />
     </xsl:variable>
     <a href="{concat('#', $id)}" title="normalize-space(.)">
       <xsl:value-of select="normalize-space(.)" />
     </a>
   </li>
 </xsl:template>

 <xsl:template match="h3" mode="BodyCopy">
   <xsl:copy>
     <xsl:attribute name="id">
       <xsl:call-template name="getId" />
     </xsl:attribute> 
     <xsl:apply-templates select="@* | node()" mode="BodyCopy" />
   </xsl:copy>
 </xsl:template>

The XHTML specification does not allow spaces in id names, so the translate() is used to turn them into underscores. If there is already an id specified then that is used.

Conclusion

The template presented is roughly what this site uses, although I have made some improvements. One was to allow some <h3> tags to be excluded from the contents list by adding a list="no" attribute. Another was to allow different a title to be used in the contents than the header text, however I haven’t actually used this on the site.

2007 Update

I no longer use XSL to generate pages for this site, Ruby on Rails handles everything instead. This has meant the loss of the contents boxes, as I haven’t got around to replacing them. I guess a solution would be to add an after_filter to the Posts controller that used regular expressions to search for <h3> tags, add in an id and save them to an array, before creating the contents box.