Chapter 12. HTML customizations

Table of Contents

Generate custom class values
HTML headers and footers
Adding extra lines
Navigational labels or graphics
Brief headers and footers
Bread crumbs
Replace headers and footers
Server-side includes
Inserting external HTML code
In the page header
In the HEAD element
In the page content
HTML HEAD elements
Adding CSS style rules
Embedding CSS styles
Adding a date timestamp
Removing the HEAD element
BODY attributes
Changing the <h> levels
HTML frameset
Chunking customization
How chunking works
Chunking templates
Separate legalnotice
Filename of the legalnotice chunk
Footer link to legalnotice
More than one legalnotice
Head links for legalnotice
Separate revhistory
Return to top
Customized hrefs

This chapter describes some of the more commonly used customizations for HTML output. They use the techniques described in Chapter 9, Customization methods. Before you start writing a customization layer for HTML, consider whether you really need one.

Use the methods described in this chapter if neither of the above can meet your needs.

Generate custom class values

The standard method for styling HTML output is with a Cascading Stylesheet (CSS). The Docbook HTML stylesheets help by automatically including a class attribute on many elements in the output. By default, the class name is the same as the name of the element that generated the output, for example <div class="chapter">. Such class names can be used in CSS selectors such as div.chapter.

You might need need to customize the class names themselves, possibly for one of the following reasons:

  • Your class values must match an existing CSS stylesheet with different names.

  • You need to tailor class values based on attribute values or element ancestry in your XML.

  • If the element whose class you want to customize is not covered by the method in the section “Using role as class name”.

Prior to version 1.72 of the stylesheets, changing the default class attribute values required copying the entire template for each element you wanted to change, just to change the class value. Starting with version 1.72, each class attribute is instead generated by processing the current element with a template in mode="class.value". That makes it easier to customize for specific elements.

The mode="class.value" template in the stylesheet that generates the default class values is the following:

<xsl:template match="*" mode="class.value">
  <xsl:param name="class" select="local-name(.)"/>
  <!-- permit customization of class value -->
  <!-- Use element name by default -->
  <xsl:value-of select="$class"/>

The default behavior for all elements (match="*") is to use the local-name() XSL function, which generates the name of the element. Because this feature uses a mode, you can create new templates in that mode that match on only the elements you want to change. The selection can be by element name, or by any other XSL pattern that includes attribute qualifiers or ancestry.

For example, if you wanted to add a style for chapters that have a status="draft" attribute, you could add this template to your customization layer:

<xsl:template match="chapter[@status = 'draft']" mode="class.value">
  <xsl:value-of select="'draft-chapter'"/>

This template outputs a string (note the extra quotes) draft-chapter, which is used to generate div class="draft-chapter" for any such chapters in the HTML output. Then you can add a class selector and styles to your CSS stylesheet.

div.draft-chapter {
  color: blue;

When viewed in a browser, such chapters will display in blue.

This mode is a very powerful tool for customizing the formatting of HTML output generated by DocBook XSL. Since you can define a template for any pattern that you can apply-templates to, you can create any number of class values to completely customize the presentation of the HTML in a browser.

There is also a similar template mode named class.attribute. While the class.value mode generates a string value, the class.attribute mode generates the entire class attribute including the name and value (which it gets using the class.value mode). The class.attribute mode makes it easy to add a class attribute to any custom output element you generate using one line:

  <xsl:apply-templates select="." mode="class.attribute"/>
  Content of the div

This mode will first use the class.value mode to get the class value, and then generate an xsl:attribute element with that value. Since it appears right after the opening tag for div, the class attribute is added to the div output. If you decide to customize the class value, then also add a template in the class.value mode as described above.