PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Destinations

A destination defines a particular view of a document, consisting of the following items:

  • The page of the document to be displayed.

  • The location of the document window on that page.

  • The magnification (zoom) factor to use when displaying the page.

Destinations may be associated with outline items (Document Outline (bookmarks)), annotations (Annotations), or actions (Actions). In each case, the destination specifies the view of the document to be presented when the outline item or annotation is opened or the action is performed. In addition, the optional document open action can be specified.

Supported Destination Types

The following types are supported by Zend_Pdf component.

Zend_Pdf_Destination_Zoom

Display the specified page, with the coordinates (left, top) positioned at the upper-left corner of the window and the contents of the page magnified by the factor zoom.

Destination object may be created using Zend_Pdf_Destination_Zoom::create($page, $left = null, $top = null, $zoom = null) method.

Where:

  • $page is a destination page (a Zend_Pdf_Page object or a page number).

  • $left is a left edge of the displayed page (float).

  • $top is a top edge of the displayed page (float).

  • $zoom is a zoom factor (float).

NULL, specified for $left, $top or $zoom parameter means "current viewer application value".

Zend_Pdf_Destination_Zoom class also provides the following methods:

  • FloatgetLeftEdge();

  • setLeftEdge(float $left);

  • FloatgetTopEdge();

  • setTopEdge(float $top);

  • FloatgetZoomFactor();

  • setZoomFactor(float $zoom);

Zend_Pdf_Destination_Fit

Display the specified page, with the coordinates (left, top) positioned at the upper-left corner of the window and the contents of the page magnified by the factor zoom. Display the specified page, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

Destination object may be created using Zend_Pdf_Destination_Fit::create($page) method.

Where $page is a destination page (a Zend_Pdf_Page object or a page number).

Zend_Pdf_Destination_FitHorizontally

Display the specified page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.

Destination object may be created using Zend_Pdf_Destination_FitHorizontally::create($page, $top) method.

Where:

  • $page is a destination page (a Zend_Pdf_Page object or a page number).

  • $top is a top edge of the displayed page (float).

Zend_Pdf_Destination_FitHorizontally class also provides the following methods:

  • FloatgetTopEdge();

  • setTopEdge(float $top);

Zend_Pdf_Destination_FitVertically

Display the specified page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.

Destination object may be created using Zend_Pdf_Destination_FitVertically::create($page, $left) method.

Where:

  • $page is a destination page (a Zend_Pdf_Page object or a page number).

  • $left is a left edge of the displayed page (float).

Zend_Pdf_Destination_FitVertically class also provides the following methods:

  • FloatgetLeftEdge();

  • setLeftEdge(float $left);

Zend_Pdf_Destination_FitRectangle

Display the specified page, with its contents magnified just enough to fit the rectangle specified by the coordinates left, bottom, right, and top entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

Destination object may be created using Zend_Pdf_Destination_FitRectangle::create($page, $left, $bottom, $right, $top) method.

Where:

  • $page is a destination page (a Zend_Pdf_Page object or a page number).

  • $left is a left edge of the displayed page (float).

  • $bottom is a bottom edge of the displayed page (float).

  • $right is a right edge of the displayed page (float).

  • $top is a top edge of the displayed page (float).

Zend_Pdf_Destination_FitRectangle class also provides the following methods:

  • FloatgetLeftEdge();

  • setLeftEdge(float $left);

  • FloatgetBottomEdge();

  • setBottomEdge(float $bottom);

  • FloatgetRightEdge();

  • setRightEdge(float $right);

  • FloatgetTopEdge();

  • setTopEdge(float $top);

Zend_Pdf_Destination_FitBoundingBox

Display the specified page, with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.

Destination object may be created using Zend_Pdf_Destination_FitBoundingBox::create($page, $left, $bottom, $right, $top) method.

Where $page is a destination page (a Zend_Pdf_Page object or a page number).

Zend_Pdf_Destination_FitBoundingBoxHorizontally

Display the specified page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.

Destination object may be created using Zend_Pdf_Destination_FitBoundingBoxHorizontally::create($page, $top) method.

Where

  • $page is a destination page (a Zend_Pdf_Page object or a page number).

  • $top is a top edge of the displayed page (float).

Zend_Pdf_Destination_FitBoundingBoxHorizontally class also provides the following methods:

  • FloatgetTopEdge();

  • setTopEdge(float $top);

Zend_Pdf_Destination_FitBoundingBoxVertically

Display the specified page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.

Destination object may be created using Zend_Pdf_Destination_FitBoundingBoxVertically::create($page, $left) method.

Where

  • $page is a destination page (a Zend_Pdf_Page object or a page number).

  • $left is a left edge of the displayed page (float).

Zend_Pdf_Destination_FitBoundingBoxVertically class also provides the following methods:

  • FloatgetLeftEdge();

  • setLeftEdge(float $left);

Zend_Pdf_Destination_Named

All destinations listed above are "Explicit Destinations".

In addition to this, PDF document may contain a dictionary of such destinations which may be used to reference from outside the PDF (e.g. 'http://www.mycompany.com/document.pdf#chapter3').

Zend_Pdf_Destination_Named objects allow to refer destinations from the document named destinations dictionary.

Named destination object may be created using Zend_Pdf_Destination_Named::create(string $name) method.

Zend_Pdf_Destination_Named class provides the only one additional method:

StringgetName();

Document level destination processing

Zend_Pdf class provides a set of destinations processing methods.

Each destination object (including named destinations) can be resolved using the resolveDestination($destination) method. It returns corresponding Zend_Pdf_Page object, if destination target is found, or NULL otherwise.

Zend_Pdf::resolveDestination() method also takes an optional boolean parameter $refreshPageCollectionHashes, which is TRUE by default. It forces Zend_Pdf object to refresh internal page collection hashes since document pages list may be updated by user using Zend_Pdf::$pages property (Working with Pages). It may be turned off for performance reasons, if it's known that document pages list wasn't changed since last method request.

Complete list of named destinations can be retrieved using Zend_Pdf::getNamedDestinations() method. It returns an array of Zend_Pdf_Target objects, which are actually either an explicit destination or a GoTo action (Actions).

Zend_Pdf::getNamedDestination(string $name) method returns specified named destination (an explicit destination or a GoTo action).

PDF document named destinations dictionary may be updated with Zend_Pdf::setNamedDestination(string $name, $destination) method, where $destination is either an explicit destination (any destination except Zend_Pdf_Destination_Named) or a GoTo action.

If NULL is specified in place of $destination, then specified named destination is removed.

Note

Unresolvable named destinations are automatically removed from a document while document saving.

Example 677. Destinations usage example

<?php
$pdf 
= new Zend_Pdf();
$page1 $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
$page2 $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
$page3 $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
// Page created, but not included into pages list

$pdf->pages[] = $page1;
$pdf->pages[] = $page2;

$destination1 Zend_Pdf_Destination_Fit::create($page2);
$destination2 Zend_Pdf_Destination_Fit::create($page3);

// Returns $page2 object
$page $pdf->resolveDestination($destination1);

// Returns null, page 3 is not included into document yet
$page $pdf->resolveDestination($destination2);

$pdf->setNamedDestination('Page2'$destination1);
$pdf->setNamedDestination('Page3'$destination2);

// Returns $destination2
$destination $pdf->getNamedDestination('Page3');

// Returns $destination1
$pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page2'));

// Returns null, page 3 is not included into document yet
$pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page3'));

Zend Framework