PDF Bookmarks are navigational links that are displayed in a pane in PDF reader applications (screenshot below). They usually reflect the structure of the PDF document and allow the user to navigate to different parts of the document.
StyleVision gives you the flexibility to set up the structure of a document's PDF Bookmarks exactly as you want. By default, all the Tables of Contents (TOCs) defined in the document will be displayed as PDF Bookmarks. Depending on your FOP processor, items that are common to the various TOCs in your document may or may not be merged. If you wish to set up PDF Bookmarks that are different from the TOC structure, you can use the PDF Bookmarks feature to customize PDF Bookmarks. If you create PDF Bookmarks, then these override input from the TOC settings and are the settings adopted for the document's PDF Bookmarks.
TOCs and PDF Bookmarks
What bookmarks are created in the PDF output depends on the TOCs in the document and whether a PDF Bookmark Tree has been created. The following options are available:
•One TOC in the design: Bookmarks in the PDF will be automatically generated using the TOC structure.
•Multiple TOCs in the design: Bookmarks in the PDF will be automatically generated for each TOC, with each TOC being appended to the previous TOC. Note that some FOP processors, such as FOP 0.93, merge items that are common to TOCs.
•A PDF Bookmark Tree is created in the design: If a PDF Bookmark Tree is created in the design, this tree is used for the bookmarks in the PDF; any TOC/s in the design are overridden. If a PDF Bookmark Tree is created in the design but is empty, then no bookmarks will be generated in the PDF—even if TOCs are present; the PDF Bookmark pane will be empty
Creating the PDF Bookmark Tree
This section describes how bookmarks can be created in the PDF output using the PDF Bookmark Tree. (If no PDF Bookmark Tree is present in the document, then bookmarks are generated automatically from the TOCs in the design. For information about creating TOCs, see the section Table of Contents, Referencing, Bookmarks.)
A PDF Bookmark Tree (template) is a template that is defined on a document's Initial Document Section. If the design has multiple document outputs, then PDF Bookmark Trees can be specified for each of the multiple documents, on their respective Initial Document Sections.
Add the PDF Bookmark Tree template by clicking the Add Header / Footer link in the title bar of the Initial Document Section, and then selecting the Add PDF Bookmark Tree command (see screenshot above). The PDF Bookmark Tree template will be added (see screenshot below).
You can now drag nodes from the Schema Tree sidebar into the PDF Bookmark Tree to create a customized PDF Bookmarks structure.
For every node that you drop into the PDF Bookmark Tree, you will be prompted as to whether you wish to create a PDF Bookmark or a template. If you select PDF Bookmark, you will be prompted to enter a target for the bookmark. These targets must be bookmarks (anchors) that already exist in the design. How to create such bookmarks (anchors) is described in the section, Inserting Bookmarks. After you have entered the target bookmark, a PDF Bookmark component is added to the tree (see screenshot below).
Each PDF Bookmark component contains a hyperlink component (see screenshot above) that has two key attributes:
•Content which defines the text of the PDF Bookmark. You can delete the default content placeholder and insert any text or suitable component instead.
•A URL property, which specifies the target of the bookmark. If the target bookmark is within the same document, then the URL must be a fragment identifier (and must therefore start with #). For more information, see Defining Hyperlinks
PDF Bookmark targets
The URL property of a PDF Bookmark's hyperlink component is the target bookmark you assigned when the PDF Bookmark was created. This target can be edited by right-clicking the hyperlink component and selecting Edit URL from the context menu that pops up.
We recommend that the targets are unique (that is, no PDF Bookmark should point to the same design bookmark). Otherwise the output might be dependent on the FOP version. (For example, FOP 0.95 ignores nested PDF Bookmarks if they have the same destination. Also FOP 0.95 ignores PDF Bookmarks which point to undefined document locations. FOP 1.0, however, does display such bookmarks in the generated Bookmark Tree.) PDF Bookmarks which point to external locations (e.g. http or file urls) are not supported by Apache FOP 0.95 and 1.0.
PDF Bookmark Tree structure
Ideally PDF Bookmarks in the PDF are structured to display the hierarchy of the document. This structure can be specified in the PDF Bookmark Tree by nesting PDF Bookmarks. For example, in the screenshot below, the n1:Office element (highlighted in blue) has been dropped into the PDF Bookmark Tree after the hyperlink component of the Organization Chart bookmark but inside the bookmark itself. The Office PDF Bookmark is therefore nested inside the Organization Chart PDF Bookmark.
Note the following points about the example shown in the screenshot above:
•The XML document contains one n1:orgChart element and two n1:Office elements.
•The n1:orgChart element has a static bookmark. A fragment identifier in the PDF Bookmark's hyperlink component targets this static bookmark.
•The name of the Organization Chart PDF Bookmark is a static text string.
•The bookmarks for the two n1:Office elements are dynamically created using XPath expressions that select the names of the two offices from a child node, n1:Name. The URL of the Office PDF Bookmark component is a dynamically generated fragment identifier, also obtained with the help of the child node, n1:Name.
•The name of each Office PDF Bookmark is generated with an Auto-Calculation that uses the respective child node, n1:Name, of each n1:Office element.
The PDF Bookmarks generated by this PDF Bookmark Tree are as in the screenshot below.
|Note:||If either the target bookmarks or the PDF Bookmark URLs are incorrect, errors or incorrect PDF Bookmarks are possible, depending upon the FO processor being used (see PDF Bookmark Targets above).|
Deleting the PDF Bookmark Tree
Delete the PDF Bookmark Tree either by selecting the tree and clicking the Delete key, or by right-clicking the tree and selecting the command Edit | Delete.