SetaPDF-Merger API - Bookmark handling

The SetaPDF-Merger API offers the facility to create a bookmark outline for the concatenated documents and/or to import the existing bookmark outline(s) of the original documents.

On this page we'll describe the different ways the bookmark feature can be used.

Generally you can turn the bookmark feature on or off with the SetaPDF_Merger::setAddBookmarks()-method.

Create new bookmarks for added files

The SetaPDF_Merger::addFile()-method accepts the $bookmark parameter which is responsable for the bookmark handling at all. It has a default behavior if it is not set but bookmark creation is set to true. Let's see:

The resulting bookmark outline will be:

As you can see the API has created a bookmark entry for every addFile-call. The bookmark title it has resolved from the title of the used PDF document. If you omit the title at any place the API first tries to resolve a title from the metadata of the pdf document. If the document have no title it'll use the filename instead.

Omit a bookmark entry and define own titles

In some cases a document or page range should not create a bookmark entry. This can be done by simply passing false to the $bookmark-parameter. In the following script we'll give some entries new titles in the bookmark outline and will omit bookmark entries for others:

The resulting bookmarks outline will be:

Styling and hierarchic structure

Until now we just used the $bookmarks parameter in the "easy" mode. The parameter also accepts an array which allows you to style the bookmark entries and arrange them in a hierarchic structure. Let's see:

The opened outline will looks like this:

title
The new bookmark title. If omited the bahavior is the same as described above.

color
The color-key accepts an array of 3 values representing the RGB components. Values are between 0 and 255.

format
The format key defines if the entry should be displayed in italic and/or bold style. It accepts 2 defined constants:

SETAPDF_M_BOOKMARK_FORMAT_ITALIC = italic
SETAPDF_M_BOOKMARK_FORMAT_BOLD = bold

They can be combined using a bitwise AND (|) operation.

parent
The parent key accepts a unique id returned by SetaPDF_Merger::addFile(). By passing such id to this key will tell the API that the new entry will be arranged below the entry that created the id.

Copying existing bookmarks

The SetaPDF-Merger API allows you to import existing bookmark outlines of the concatenated pdf documents.

You can control this behavior with the copyBookmarks-key in the $bookmark parameter array:

The result:

The existing outlines are imported and were appended as childs of the new bookmark entries. This behavior was defined by passing the constant SETAPDF_M_COPY_BOOKMARKS_AS_CHILD to the copyBookmarks-key.

To omit the creation of such parent nodes you can use the constant SETAPDF_M_COPY_BOOKMARKS_TO_SAME_LEVEL, which will only import the existing outline. All other keys, like "title", "color" and "format" were not considered:

The result will looks like this:

In this case the outlines were imported to the root node. For sure you also can use this kind of import into your own build hierarchic structure.