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: SetaPDF_Core_Document_Destination or SetaPDF_Core_Document_Destination. Internally both of these methods will create the needed destination array by calling the SetaPDF_Core_Document_Destination 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 SetaPDF_Core_Document_Destination 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();