XML technologies / XSL-FO / XSL-FO introduction / Cross references and hyperlinks

12. Cross references and hyperlinks

In XSL-FO it is possible to generate cross references and hyperlinks. These can refer to a destination within the document or to an external source.

The application of such cross references and hyperlinks varies, depending on the medium used for the output: PDF uses the hyperlink function in an interactive reader in order to, for example, navigate from the link source to the link destination by clicking. When printing, the cross reference function is used in order to, for example, display the name/title of the reference destination at the place of the reference source. The basis of both functions is the <fo:basic-link> element.

At first, the reference destination has to be indicated. This is done by adding the id attribute to the block which contains the reference destination (a chapter, a graphic, a table, a headline etc.) and giving the block an unique identifier. With the id attribute all types of blocks and even inline elements can be assigned.

At the place of the reference source, the <fo:basic-lnk> element is set.

The <fo:basic-link> element may contain plenty of attributes. For the demonstration of this concept only three attributes are important:

In the case of a document-internal reference destination, the internal-destination attribute is set. Its value refers to the reference destination by using a XPath expression.
In the case of a document-external reference destination, the external-destination attribute is set. Its value refers to a place outside of the document. This may be a web address or another document.
In addition, the behaviour of the link/reference has to be specified: this is done with the show-destination attribute (indication of the reference destination). The default value is replace, which means the reference destination is displayed in the given view (when printing always the printed page). The alternative value new opens the reference destination in a new view, so it is not important for the print output.

However, it should be noted that the hyperlink functionality of the PDF output depends on whether the PDF generator is automatically formatting because of the XSL-FO coding or it requires additional processing into the formatting result.

The following example consists of three components since in the processing the resolution of the reference/link is done by the XSLT process and not just in the formatting process. The components are: the XML document to be formatted, the XSL stylesheet and the resulting XSL-FO document.

Extract from the XML document to be formatted:

<title id="links">Cross references/hyperlinks</title>    (1)
 ...
 text ... <ref idref="links"/> ... text ...              (2)

(1) This is a reference destination in the XML document. The title has the value "links" for the id attribute.

(2) This is the reference source. The idref attribute refers by its "links" value to the title with the same value in the id attribute.

Extract from the XSL stylesheet:

<xsl:template match="title">                                        (1)
   <fo:block id="{generate-id()}" ... >                             (2)
      <xsl:apply-templates/>
   </fo:block>
</xsl:template>
 ...
<xsl:template match="ref">                                          (3)
   <xsl:for-each select="//title[contains(@id,current()/@idref)]">  (4)
      <fo:inline text-decoration="underline">                       (5)
         <fo:basic-link internal-destination="{generate-id()}" show-destination="replace"> (6)
            <xsl:value-of select="."/>                              (7)
         </fo:basic-link>
      </fo:inline>
   </xsl:for-each>
</xsl:template>

(1) This is the template for the <title> element .

(2) The block which shall include the content of the title gets an id attribute whose value shall be generated by the XSLT processor and is specified with the generate-id() function.

(3) This is the template for the <ref> element.

(4) For each occurrence of the same id-idref attribute values for the <title> reference destination and the <ref> reference source the <xsl:for-each> element determines what is specified in the following lines. The attribute value of select is a XPath expression which describes the reference destination: a <title> element in each environment which has for the id attribute the same value ("links") as the idref attribute of the <ref> element given in this example.

(5) The text-decoration attribute is only set in order to identify the link source in the PDF as such.

(6) The attribute value of internal-destination shall also be generated with the generate-id() function in the XSLT process (see the parallel for <title>). The show-destination attribute with its replace value is only defined for the sake of clarity.

(7) With this XSLT expression the content of the <title> element is inserted into the <fo:basic-link> element. If you do not want to insert the content of the <title> element but the number of the page on which the title appears, the expression in this line would be <fo:page-number-citation ref=id"{generate-id()}"/>.

Extract from the resulting XSL-FO document:

...
  <fo:block id="IDAHGBZB" ...>Cross references/hyperlinks</fo:block>            (1)
  ...
  ...<fo:inline text-decoration="underline">
  <fo:basic-link internal-destination="IDAHGBZB" show-destination="replace">    (2)
   Cross references/hyperlinks                                                  (3)
 </fo:basic-link>
 </fo:inline>...

(1) For id the block with the content of the title now has the value "IDAHGBZB" generated by the XSLT process.

(2) The inline element <fo:basic-link> has for the internal-destination attribute the same value "IDAHGBZB". This enables the PDF generator to generate the hyperlink between the pages which connects the reference source and the reference destination with each other.

(3) Here, the content of the title is inserted which is referred to. If in the stylesheet <xsl:value-of> is used instead of the expression <fo:page-number-citation>, the corresponding page number with the respective title would be entered at this position.

<< back

Copyright © dpunkt.verlag GmbH 2004
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSL-FO in der Praxis" ("XSL-FO in practice") is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.

dpunkt.verlag GmbH, Ringstraße 19B, 69115 Heidelberg, fon 06221-14830, fax 06221-148399, hallo@dpunkt.de