Destinations

Introduction

A destination in a PDF document defines a particular view of a page, the location of the document window on that page, and a zoom factor.

Destinations may be associated with outline items, annotations, or actions. They may be specified either explicitly or indirectly by a name. 

The Destination Class

A destination is represented by the SetaPDF_Core_Document_Destination class. This class offers some methods to evaluate a destination and let you resolve its target page in an easy way: 

getPage()

Get the target page object.

getPageNo()

Get the target page number.

The class also comes with several static methods that let you create or find a destination by a name: 

createByPage()

Creates a destination by a page object.

createByPageNo()

Creates a destination by page number.

createDestinationArray()

Creates an explicit Destination array.

findByName()

Find a destination by a name.

Examples

As a destination is related to a page the easiest way to create one is to use one of the provided helper methods: createByPage() or createByPageNo(). Internally both of these methods will create the needed destination array by calling the createDestinationArray() method. All arguments passed to one of the helper methods will also be forward to this method (e.g. the fit-mode). The default fit-mode is set to "fit".

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

$writer = new SetaPDF_Core_Writer_Http('destinations-by-page.pdf', true);
$document = new SetaPDF_Core_Document($writer);

// let's create some pages and destinations to them
$pages = $document->getCatalog()->getPages();
for ($i = 0; $i < 10; $i++) {
    $pages->create(SetaPDF_Core_PageFormats::A4);
}

// get the outlines helper
$outlines = $document->getCatalog()->getOutlines();

// create a root nodes
$toc1 = SetaPDF_Core_Document_OutlinesItem::create($document, 'Destinations by page no');
$outlines->appendChild($toc1);
$toc2 = SetaPDF_Core_Document_OutlinesItem::create($document, 'Destinations by page objects');
$outlines->appendChild($toc2);

// iterate over all pages
for ($pageNo = 1, $pageCount = $pages->count(); $pageNo <= $pageCount; $pageNo++) {

    $item = SetaPDF_Core_Document_OutlinesItem::create($document, 'Page No #' . $pageNo);
    // destination by page number
    $destination = SetaPDF_Core_Document_Destination::createByPageNo($document, $pageNo);
    $item->setDestination($destination);
    $toc1->appendChild($item);
    
    $item = SetaPDF_Core_Document_OutlinesItem::create($document, 'Page No #' . $pageNo);
    // destination by page object
    $page = $pages->getPage($pageNo);
    $destination = SetaPDF_Core_Document_Destination::createByPage($page);
    $item->setDestination($destination);
    $toc2->appendChild($item);
}

// show the outline
$document->getCatalog()->setPageMode(SetaPDF_Core_Document_PageMode::USE_OUTLINES);

$document->save()->finish();

It is also possible to define the position and zoom factor of the destination by a specific fit-mode: 

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

$writer = new SetaPDF_Core_Writer_Http('fit-modes.pdf', true);
$document = new SetaPDF_Core_Document($writer);

// let's create some pages and destinations to them
$pages = $document->getCatalog()->getPages();
for ($i = 0; $i < 10; $i++) {
    $pages->create(SetaPDF_Core_PageFormats::A4);
}

// get the outlines helper
$outlines = $document->getCatalog()->getOutlines();

// a destination with position and zoom factor
$item = SetaPDF_Core_Document_OutlinesItem::create($document, 'Page #8 (left = 100, top = 200, zoom = 300 %)');
$item->setDestination(SetaPDF_Core_Document_Destination::createByPageNo(
    $document, 8, 'XYZ', 100, 200, 3
));
$outlines->appendChild($item);

// a destination with only a page
$item = SetaPDF_Core_Document_OutlinesItem::create($document, 'Page #2 (left = null, top = null, zoom = null)');
$item->setDestination(SetaPDF_Core_Document_Destination::createByPageNo(
    $document, 2, 'XYZ', null, null, null
));
$outlines->appendChild($item);

// a destination with horizontal fit mode
$item = SetaPDF_Core_Document_OutlinesItem::create($document, 'Page #1 (top = 100)');
$item->setDestination(SetaPDF_Core_Document_Destination::createByPageNo(
    $document, 1, 'FitH', 100
));
$outlines->appendChild($item);

// a destination with vertically fit mode
$item = SetaPDF_Core_Document_OutlinesItem::create($document, 'Page #3 (left = 100)');
$item->setDestination(SetaPDF_Core_Document_Destination::createByPageNo(
    $document, 3, 'FitV', 100
));
$outlines->appendChild($item);


// show the outline
$document->getCatalog()->setPageMode(SetaPDF_Core_Document_PageMode::USE_OUTLINES);

$document->save()->finish();

Explicit vs. Named Destinations

Destinations are represented in PDF by a simple array structure which can be used as a value in structures that allow a destination value. In addition it is also allowed to use named destinations which are represented by a simple string value. The destination array related to this named destination is saved in a documents name tree. This tree will be used to look-up for these named destinations. Internally the findByName() method makes use of a documents name tree to resolve the destination appropriate. 

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

$writer = new SetaPDF_Core_Writer_Http('destinations-by-page.pdf', true);
$document = new SetaPDF_Core_Document($writer);

// let's create some pages and destinations to them
$pages = $document->getCatalog()->getPages();
for ($i = 0; $i < 10; $i++) {
    $pages->create(SetaPDF_Core_PageFormats::A4);
}

// get the name tree
$destinations = $document->getCatalog()->getNames()->getTree(SetaPDF_Core_Document_Catalog_Names::DESTS, true);

// create some named destinations
$destination = SetaPDF_Core_Document_Destination::createByPageNo($document, 1);
$destinations->add('First Page', $destination->getPdfValue());

$destination = SetaPDF_Core_Document_Destination::createByPageNo($document, 10);
$destinations->add('Last Page', $destination->getPdfValue());

// get the outlines helper
$outlines = $document->getCatalog()->getOutlines();

// create some nodes with destinations
$first = SetaPDF_Core_Document_OutlinesItem::create($document, 'First Page Item');
$first->setDestination('First Page');
$outlines->appendChild($first);

$last = SetaPDF_Core_Document_OutlinesItem::create($document, 'Last Page Item');
$last->setDestination('Last Page');
$outlines->appendChild($last);

// show the outline
$document->getCatalog()->setPageMode(SetaPDF_Core_Document_PageMode::USE_OUTLINES);

$document->save()->finish();