Bookmarks

Bookmarks are the entries which appear on the right in a PDF file in Adobe Acrobat. They are used to navigate directly to locations within the document. They also have a hierarchical structure, where one bookmark can contain a set of child bookmarks which in turn can themselves contain other bookmarks.

The bookmark-tree element is optional. If used it should be placed under the fo:root element, after the fo:layout-master-set and fo:declarations elements and before any fo:page-sequence or fo:page-sequence-wrapper elements.

The structure of a bookmark tree is shown in Figure 19-1.

<fo:bookmark-tree>
	<fo:bookmark internal-destination="section-1">
		<fo:bookmark-title>Chapter 1</fo:bookmark-title>
		<fo:bookmark internal-destination="section-1-1">
			<fo:bookmark-title>Section 1</fo:bookmark-title>
		</fo:bookmark>
		<fo:bookmark internal-destination="section-1-2">
			<fo:bookmark-title>Section 2</fo:bookmark-title>
		</fo:bookmark>
	</fo:bookmark>
	<fo:bookmark internal-destination="section-2">
		<fo:bookmark-title>Chapter 2</fo:bookmark-title>
		<fo:bookmark internal-destination="section-2-1">
			<fo:bookmark-title>Section 1</fo:bookmark-title>
		</fo:bookmark>
	</fo:bookmark>
</fo:bookmark-tree>

Figure 19-1: A bookmark tree

We can see the following from the structure shown in Figure 19-1.

  • The bookmarks are contained in a fo:bookmark-tree element.
  • A fo:bookmark element has an internal-destination attribute identifying where in the document it links to. The value for this attribute should be used as the id attribute on the destination element.
  • A bookmark element can contain other bookmark elements.
  • The text which appears in the bookmark is contained within a fo:bookmark-title element. Ibex supports using Unicode text in bookmarks.

The bookmarks which have child bookmark elements appear in the PDF file in a closed state, so the user can click the '+' next to them to display the child elements. If you specify starting-state="show" on a bookmark or bookmark-tree element it's immediate children will be visible when the PDF file is opened.