The DocBook XSL stylesheets provide options for controlling HTML headers and footers. First, let's distinguish the two kinds of headers in HTML:
Generated content to be displayed at the top of chunked HTML output.
HTML elements that should appear in the HEAD
of the HTML file. See the section “HTML HEAD elements” for more information on this kind of header.
This section covers just the first kind of header. By default, chunked HTML output gets a couple of lines of navigational links at the top and bottom of each output file. That permits the user to move from file to file to see all the content. If you do not chunk your HTML output, then there is no displayed header or footer in the file.
If you want to leave the navigational headers and footers in place, and just add something of your own, such as a copyright line, then you can fill in some no-op templates that are already called by the stylesheets. These are the header and footer templates in the order in which they are called on the page, including four that can be user defined:
Table 12.1. Templates for HTML headers and footers
Template name | When it is called |
---|---|
user.header.navigation | Called before standard navigational header. |
header.navigation | The standard navigational header. |
user.header.content | Called after standard navigational header but before any other content. |
user.footer.content | Called after the chunk content but before the standard navigational footer. |
footer.navigation | The standard navigational footer. |
user.footer.navigation | Called after the standard navigational footer. |
The following is an example of adding a copyright string to the bottom of each chunked file, above the standard navigational footer. It processes the first copyright
element it finds in the document, using the titlepage.mode
which adds the copyright symbol:
<xsl:template name="user.footer.content"> <HR/> <xsl:apply-templates select="//copyright[1]" mode="titlepage.mode"/> </xsl:template>
If you would rather have the copyright appear below the navigational footer, then use the user.footer.navigational
template instead. The content of the template can include IMG
elements to reference a graphical logo, and any other HTML content that makes sense. If you add class
attributes, then you can control the formatting with your CSS stylesheet.
See the section “Footer link to legalnotice” if you want the copyright string to link to a separate legalnotice chunk.
If your DocBook XML file is kept under a content management system such as CVS, you might want to insert the CVS version information on the HTML pages generated from the file. That informs the reader of when the content of the page was last changed.
The XSLT processor cannot directly request the version identifier from the CVS system. But that information can be stored in the XML document itself, where the stylesheet can access it. The trick is to put the CVS identifier string $Id$
in a releaseinfo
element in your document. It can go in the bookinfo
element of a book, or the articleinfo
element of an article. Each time the file is checked into the CVS system, the identifier string is updated by CVS with the latest information. For example:
<releaseinfo> $Id: dbxsl.xml,v 1.128 2007/09/02 18:19:18 bobs Exp $ </releaseinfo
Once this information is in the XML file, it is easy to insert it into the HTML footer:
<xsl:template name="user.footer.content"> <P class="CVSinfo"> <xsl:value-of select="//releaseinfo[1]"/> </P> </xsl:template>
The select
attribute has an XPath expression that finds the first releaseinfo
element in the document, and the xsl:value-of
element takes its string value.
The standard navigational headers and footers in chunked output use words such as Next
, Prev
, Up
, and Home
.
You can replace those words with different words by customizing the generated text. See the section “Customizing generated text” for a description of this method of customization. The following is an example that changes the word Home
with Table of Contents
for English output:
<xsl:param name="local.l10n.xml" select="document('')" />
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
<l:l10n language="en">
<l:gentext key="nav-home" text="Table of Contents"/>
</l:l10n>
</l:i18n>
See the stylesheet file common/en.xml
to see all the l:gentext
elements with key names that begin with nav-
that specify the navigational labels.
You can also replace the navigational words with graphical icons. See the section “Navigational icons” for the parameters to turn that feature on. You can also supply your own graphics.
The standard navigational headers and footers also show the titles of the other files
by default. If you want a very clean presentation without the titles, then you can set the navig.showtitles
parameter to zero (it is 1 by default). Then
you will see only Next
and Prev
or their icon equivalents.
Bread crumbs are a common navigational aid that displays the sequence of nested elements that generated the currently displayed chunk. Each of the items in the sequence is a link to an ancestor element, which provides a higher context than the current node. So if you chunk at section level 2, then the breadcrumbs for such a section might display the titles for its book, chapter, and section level 1 as links.
The following example shows a custom template that generates the links, and how it can be called.
Template to generate breadcrumbs: <xsl:template name="breadcrumbs"> <xsl:param name="this.node" select="."/> <div class="breadcrumbs"> <xsl:for-each select="$this.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="$this.node"/> </xsl:call-template> </xsl:attribute> <xsl:apply-templates select="." mode="title.markup"/> </a> </span> <xsl:text> > </xsl:text> </xsl:for-each> <!-- And display the current node, but not as a link --> <span class="breadcrumb-node"> <xsl:apply-templates select="$this.node" mode="title.markup"/> </span> </div> </xsl:template> Call the template: <xsl:template name="user.header.content"> <xsl:call-template name="breadcrumbs"/> </xsl:template>
The breadcrumbs
template selects the ancestors using ancestor::*
, and then generates a link for each. The select
in an xsl:for-each
presents the nodes in document order, with the current context node designated as "."
within the xsl:for-each
. The href is generated using the template named href.target
, which will generate an appropriate link between any two chunks. The context
param should contain the starting point for the link, whose value was saved before the xsl:for-each
changed the context node, and the target chunk is designated by the object
param. The template then generates the title using mode="title.markup"
. A separator string is added after each, which can be customized for your style. Then the title of the current node is added, but not as a link. Each title is contained in a span
element with a class
attribute so it can be styled using CSS.
You call your new template using the placeholder template named user.header.content
, which is automatically called at the top of each chunked output file.
If you decide you need to completely replace the navigational headers and footers, then you can either create replacement templates, or you can turn them off and apply the user-defined templates instead.
If you want to retain the navigational features such as Next and Previous, then it is probably easiest to modify the existing templates. Copy the templates named header.navigation
and footer.navigation
from the html/chunk-common.xsl
file to your customization layer for modification. You'll find they are substantial templates that create small tables to format the header and footer. They are passed two parameters named prev
and next
, which are the XML nodes for those pointers.
If your goal is to completely replace the standard headers and footers, then set the suppress.navigation
parameter to 1 to turn them off. You can then
define
your own in templates named user.header.navigation
and user.footer.navigation
. If you do not define any new templates, then
you will
completely suppress headers and footers.
DocBook XSL: The Complete Guide - 4th Edition | PDF version available | Copyright © 2002-2007 Sagehill Enterprises |