Index

  1. Installation
  2. Getting Started
  3. Memory Usage
  4. Readers and Writers
  5. The Document Class
  6. Metadata
  7. Pages
  8. Canvas
  9. Page Layout and Mode
  10. Viewer Preferences
  11. Document Outline
  12. Page Labels
  13. Actions
  14. Destinations
    1. Introduction
    2. The Destination Class
    3. Examples
      1. Explicit vs. Named Destinations
  15. Annotations
  16. Embedded File Streams
  17. Colors and Color Spaces
  18. Page Formats and Boundaries
  19. Standard and Public Key Encryption
  20. Fonts and Encodings
  21. Corrupted Documents
  22. Reader Enabled Documents
  23. Refactor Old SetaPDF Code
  24. API Reference

Destinations

Table of Contents

  1. Introduction
    1. The Destination Class
      1. Examples
        1. Explicit vs. Named 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();
        © 2024 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)