Document Outline

Introduction

The document outline, also knows as bookmarks, provides a way for a user to interactively navigate through a document.

The outline is structured as a tree and usually shown similar to this:

- Root level item      1
- Another item
  - Sub item           4
  - Another sub item   5
+ Third root item      9

The above outline shows a few things:

Some of the changeable properties of outline items have been mentioned above, here is the full list:

Title

This is the only mandatory property and it specifies the text of the outline item.

Destination/Action

An outline item usually has an associated destination or action that gets activated when clicking on the item’s text. It is possible to omit the destination/action. However, this is only useful if the item acts as a container, i.e. when it has sub items.

Open or closed

An outline item that has sub items may initially be open or closed. If it is open, its sub items are visible. Otherwise the sub items are not visible.

Color of the item text

The default color of an outline item is black. However, it can be changed to any RGB color.

Style characteristics of the item text

The item text is normally shown with a regular style font variant. However, it is possible to use a bold, italic or bold italic font variant.

Usage

A PDF outline is represented by two dictionary types:

Main outline dictionary

This dictionary is referenced from the catalog via the /Outlines entry and is implemented by the class HexaPDF::Type::Outline. To make accessing it still easier there is the HexaPDF::Document#outline method which also automatically creates it if it does not exist.

It just contains the list of root level items and only has two methods #add_item and #each_item. These two methods work like the ones in the outline item dictionary implementation.

Outline item dictionary

This dictionary represents a single outline item and is implemented by the HexaPDF::Type::OutlineItem class. It contains convenience methods for all things, like adding a sub item, iterating over all child items or setting the title.

Items are either added to the main outline dictionary (root level items) or to an already created item:

doc.outline.add_item("Section 1") do |section1|     # add root level item
  section1.add_item("Header 1.1", destination: 0)   # add sub item
end
# or
section1 = doc.outline.add_item("Section 1")
section1.add_item("Header 1.1", destination: 0)

When creating an item it is possible to provide all outline item properties. Alternatively, the properties can be set later:

section = doc.outline.add_item("Section", destination: 0, open: false)
section.text_color("red")
section.flag(:bold)