Un destino define una vista particular de un documento, formada por los siguientes elementos:
La página del documento que se mostrará.
La ubicación de la ventana del documento en esa página.
El factor de ampliación (zoom) que se usará al mostrar la página.
Los destinos pueden asociarse con elementos de esquema (Esquema del documento (marcadores)), anotaciones (Anotaciones), o acciones (Acciones). En cada caso, el destino especifica la vista del documento que se presentará cuando se abra el elemento de esquema o la anotación, o cuando se ejecute la acción. Además, se puede especificar la acción opcional de apertura del documento.
El componente Zend_Pdf admite los siguientes tipos.
Muestra la página especificada, con las coordenadas (left, top) posicionadas en la esquina superior izquierda de la ventana y el contenido de la página ampliado por el factor zoom.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_Zoom::create($page, $left = null, $top = null,
$zoom = null).
Donde:
$pagees una página de destino (un objetoZend_Pdf_Pageo un número de página).$leftes el borde izquierdo de la página mostrada (float).$topes el borde superior de la página mostrada (float).$zoomes un factor de ampliación (float).
NULL, especificado para el parámetro $left,
$top o $zoom, significa
"valor actual de la aplicación de visualización".
La clase Zend_Pdf_Destination_Zoom también proporciona
los siguientes métodos:
Float
getLeftEdge();setLeftEdge(float $left);Float
getTopEdge();setTopEdge(float $top);Float
getZoomFactor();setZoomFactor(float $zoom);
Muestra la página especificada, con las coordenadas (left, top) posicionadas en la esquina superior izquierda de la ventana y el contenido de la página ampliado por el factor zoom. Muestra la página especificada, con su contenido ampliado lo justo para que encaje toda la página dentro de la ventana, tanto horizontal como verticalmente. Si los factores de ampliación horizontal y vertical requeridos son diferentes, se usa el menor de los dos, centrando la página dentro de la ventana en la otra dimensión.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_Fit::create($page).
Donde $page es una página de destino
(un objeto Zend_Pdf_Page o un número de página).
Muestra la página especificada, con la coordenada vertical top posicionada en el borde superior de la ventana y el contenido de la página ampliado lo justo para que encaje todo el ancho de la página dentro de la ventana.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_FitHorizontally::create($page,
$top).
Donde:
$pagees una página de destino (un objetoZend_Pdf_Pageo un número de página).$topes el borde superior de la página mostrada (float).
La clase Zend_Pdf_Destination_FitHorizontally también
proporciona los siguientes métodos:
Float
getTopEdge();setTopEdge(float $top);
Muestra la página especificada, con la coordenada horizontal left posicionada en el borde izquierdo de la ventana y el contenido de la página ampliado lo justo para que encaje toda la altura de la página dentro de la ventana.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_FitVertically::create($page,
$left).
Donde:
$pagees una página de destino (un objetoZend_Pdf_Pageo un número de página).$leftes el borde izquierdo de la página mostrada (float).
La clase Zend_Pdf_Destination_FitVertically también
proporciona los siguientes métodos:
Float
getLeftEdge();setLeftEdge(float $left);
Muestra la página especificada, con su contenido ampliado lo justo para que el rectángulo especificado por las coordenadas left, bottom, right y top encaje por completo dentro de la ventana, tanto horizontal como verticalmente. Si los factores de ampliación horizontal y vertical requeridos son diferentes, se usa el menor de los dos, centrando el rectángulo dentro de la ventana en la otra dimensión.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_FitRectangle::create($page, $left, $bottom,
$right, $top).
Donde:
$pagees una página de destino (un objetoZend_Pdf_Pageo un número de página).$leftes el borde izquierdo de la página mostrada (float).$bottomes el borde inferior de la página mostrada (float).$rightes el borde derecho de la página mostrada (float).$topes el borde superior de la página mostrada (float).
La clase Zend_Pdf_Destination_FitRectangle también
proporciona los siguientes métodos:
Float
getLeftEdge();setLeftEdge(float $left);Float
getBottomEdge();setBottomEdge(float $bottom);Float
getRightEdge();setRightEdge(float $right);Float
getTopEdge();setTopEdge(float $top);
Muestra la página especificada, con su contenido ampliado lo justo para que su caja delimitadora encaje por completo dentro de la ventana, tanto horizontal como verticalmente. Si los factores de ampliación horizontal y vertical requeridos son diferentes, se usa el menor de los dos, centrando la caja delimitadora dentro de la ventana en la otra dimensión.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_FitBoundingBox::create($page, $left, $bottom,
$right, $top).
Donde $page es una página de destino
(un objeto Zend_Pdf_Page o un número de página).
Muestra la página especificada, con la coordenada vertical top posicionada en el borde superior de la ventana y el contenido de la página ampliado lo justo para que encaje todo el ancho de su caja delimitadora dentro de la ventana.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_FitBoundingBoxHorizontally::create($page,
$top).
Donde
$pagees una página de destino (un objetoZend_Pdf_Pageo un número de página).$topes el borde superior de la página mostrada (float).
La clase Zend_Pdf_Destination_FitBoundingBoxHorizontally
también proporciona los siguientes métodos:
Float
getTopEdge();setTopEdge(float $top);
Muestra la página especificada, con la coordenada horizontal left posicionada en el borde izquierdo de la ventana y el contenido de la página ampliado lo justo para que encaje toda la altura de su caja delimitadora dentro de la ventana.
El objeto destino puede crearse usando el método
Zend_Pdf_Destination_FitBoundingBoxVertically::create($page,
$left).
Donde
$pagees una página de destino (un objetoZend_Pdf_Pageo un número de página).$leftes el borde izquierdo de la página mostrada (float).
La clase Zend_Pdf_Destination_FitBoundingBoxVertically
también proporciona los siguientes métodos:
Float
getLeftEdge();setLeftEdge(float $left);
Todos los destinos indicados anteriormente son "Destinos explícitos".
Además de esto, un documento PDF puede contener un diccionario
de dichos destinos que puede usarse para hacer referencia desde fuera del
PDF (p. ej.
'http://www.mycompany.com/document.pdf#chapter3').
Los objetos Zend_Pdf_Destination_Named permiten referirse
a destinos del diccionario de destinos con nombre del documento.
El objeto de destino con nombre puede crearse usando el método
Zend_Pdf_Destination_Named::create(string $name).
La clase Zend_Pdf_Destination_Named proporciona un único
método adicional:
StringgetName();
La clase Zend_Pdf proporciona un conjunto de métodos
para el procesamiento de destinos.
Cada objeto destino (incluidos los destinos con nombre) puede resolverse usando el
método resolveDestination($destination). Devuelve
el objeto Zend_Pdf_Page correspondiente, si se encuentra
el destino objetivo, o NULL en caso contrario.
El método Zend_Pdf::resolveDestination() también admite
un parámetro booleano opcional $refreshPageCollectionHashes,
que por defecto es TRUE. Obliga
al objeto Zend_Pdf a actualizar los hashes internos de la
colección de páginas, ya que la lista de páginas del documento puede haberse
actualizado mediante la propiedad
Zend_Pdf::$pages
(Trabajando con páginas).
Puede desactivarse por motivos de rendimiento,
si se sabe que la lista de páginas del documento no ha cambiado desde la
última solicitud al método.
La lista completa de destinos con nombre puede obtenerse usando el
método Zend_Pdf::getNamedDestinations(). Devuelve
un array de objetos Zend_Pdf_Target, que en realidad son
un destino explícito o una acción GoTo
(Acciones).
El método Zend_Pdf::getNamedDestination(string $name) devuelve
el destino con nombre especificado (un destino explícito o una acción GoTo).
El diccionario de destinos con nombre del documento PDF puede
actualizarse con el método
Zend_Pdf::setNamedDestination(string $name, $destination),
donde $destination es un destino explícito
(cualquier destino salvo Zend_Pdf_Destination_Named) o
una acción GoTo.
Si se especifica NULL en lugar de
$destination, entonces se elimina el destino con nombre especificado.
![[Note]](images/note.png) |
Nota |
|---|---|
Los destinos con nombre no resolubles se eliminan automáticamente de un documento al guardarlo. |
Ejemplo 55.21. Ejemplo de uso de destinos
$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'));
En lugar de simplemente saltar a un destino en el documento, una anotación o un elemento de esquema puede especificar una acción para que la aplicación de visualización la ejecute, como lanzar una aplicación, reproducir un sonido o cambiar el estado de apariencia de una anotación.
Los siguientes tipos de acción se reconocen al cargar un documento PDF:
Zend_Pdf_Action_GoTo- ir a un destino en el documento actual.Zend_Pdf_Action_GoToR- ir a un destino en otro documento.Zend_Pdf_Action_GoToE- ir a un destino en un archivo incrustado.Zend_Pdf_Action_Launch- lanzar una aplicación o abrir o imprimir un documento.Zend_Pdf_Action_Thread- comenzar a leer un hilo de artículo.Zend_Pdf_Action_URI- resolver una URI.Zend_Pdf_Action_Sound- reproducir un sonido.Zend_Pdf_Action_Movie- reproducir una película.Zend_Pdf_Action_Hide- oculta o muestra una o más anotaciones en pantalla.-
Zend_Pdf_Action_Named- ejecuta una acción predefinida por la aplicación de visualización:NextPage - Ir a la página siguiente del documento.
PrevPage - Ir a la página anterior del documento.
FirstPage - Ir a la primera página del documento.
LastPage - Ir a la última página del documento.
Zend_Pdf_Action_SubmitForm- enviar datos a una dirección de recurso uniforme.Zend_Pdf_Action_ResetForm- restablecer campos a sus valores por defecto.Zend_Pdf_Action_ImportData- importar valores de campos desde un archivo.Zend_Pdf_Action_JavaScript- ejecutar un script JavaScript.Zend_Pdf_Action_SetOCGState- establecer el estado de uno o más grupos de contenido opcional.Zend_Pdf_Action_Rendition- controlar la reproducción de contenido multimedia (iniciar, detener, pausar o reanudar una reproducción en curso).Zend_Pdf_Action_Trans- actualizar la visualización de un documento, usando un diccionario de transición.Zend_Pdf_Action_GoTo3DView- establecer la vista actual de una anotación 3D.
Actualmente el usuario solo puede crear las acciones
Zend_Pdf_Action_GoTo y
Zend_Pdf_Action_URI.
El objeto de acción GoTo puede crearse usando el método
Zend_Pdf_Action_GoTo::create($destination),
donde $destination es un objeto
Zend_Pdf_Destination o una cadena que puede usarse
para identificar un destino con nombre.
Debe usarse el método
Zend_Pdf_Action_URI::create($uri[, $isMap]) para
crear una acción URI (consulte la documentación de la API para más
detalles). El parámetro opcional $isMap es
FALSE por defecto.
También admite los siguientes métodos:
Los objetos de acción pueden encadenarse usando la propiedad pública
Zend_Pdf_Action::$next.
Es un array de objetos Zend_Pdf_Action, que a su vez
pueden tener sus propias subacciones.
La clase Zend_Pdf_Action implementa la interfaz RecursiveIterator,
por lo que las acciones hijas pueden iterarse recursivamente:
$pdf = new Zend_Pdf();
$page1 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
$page2 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
// Page created, but not included into pages list
$page3 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
$pdf->pages[] = $page1;
$pdf->pages[] = $page2;
$action1 = Zend_Pdf_Action_GoTo::create(
Zend_Pdf_Destination_Fit::create($page2));
$action2 = Zend_Pdf_Action_GoTo::create(
Zend_Pdf_Destination_Fit::create($page3));
$action3 = Zend_Pdf_Action_GoTo::create(
Zend_Pdf_Destination_Named::create('Chapter1'));
$action4 = Zend_Pdf_Action_GoTo::create(
Zend_Pdf_Destination_Named::create('Chapter5'));
$action2->next[] = $action3;
$action2->next[] = $action4;
$action1->next[] = $action2;
$actionsCount = 1; // Note! Iteration doesn't include top level action and
// walks through children only
$iterator = new RecursiveIteratorIterator(
$action1,
RecursiveIteratorIterator::SELF_FIRST);
foreach ($iterator as $chainedAction) {
$actionsCount++;
}
// Prints 'Actions in a tree: 4'
printf("Actions in a tree: %d\n", $actionsCount++);
Una acción de apertura especial puede especificar un destino que se mostrará o una acción que se ejecutará cuando se abra el documento.
El método Zend_Pdf_Target Zend_Pdf::getOpenAction()
devuelve la acción de apertura actual del documento (o NULL si
no se ha establecido ninguna acción de apertura).
El método setOpenAction(Zend_Pdf_Target $openAction = null)
establece la acción de apertura del documento, o la elimina si
$openAction es NULL.
Un documento PDF puede mostrar opcionalmente un esquema del documento en pantalla, permitiendo al usuario navegar de forma interactiva de una parte del documento a otra. El esquema consiste en una jerarquía en forma de árbol de elementos de esquema (a veces llamados marcadores), que sirven como una tabla de contenidos visual para mostrar al usuario la estructura del documento. El usuario puede abrir y cerrar elementos individuales de forma interactiva haciendo clic en ellos con el ratón. Cuando un elemento está abierto, sus hijos inmediatos en la jerarquía se vuelven visibles en pantalla; cada hijo puede a su vez estar abierto o cerrado, revelando u ocultando selectivamente otras partes de la jerarquía. Cuando un elemento está cerrado, todos sus descendientes en la jerarquía quedan ocultos. Al hacer clic en el texto de cualquier elemento visible, se activa el elemento, provocando que la aplicación de visualización salte a un destino o active una acción asociada con el elemento.
La clase Zend_Pdf proporciona la propiedad pública
$outlines, que es un array de objetos
Zend_Pdf_Outline.
$pdf = Zend_Pdf::load($path);
// Remove outline item
unset($pdf->outlines[0]->childOutlines[1]);
// Set Outline to be displayed in bold
$pdf->outlines[0]->childOutlines[3]->setIsBold(true);
// Add outline entry
$pdf->outlines[0]->childOutlines[5]->childOutlines[] =
Zend_Pdf_Outline::create('Chapter 2', 'chapter_2');
$pdf->save($path, true);
Los atributos del esquema pueden obtenerse o establecerse usando los siguientes métodos:
string getTitle()- obtiene el título del elemento de esquema.setTitle(string $title)- establece el título del elemento de esquema.boolean isOpen()-TRUEsi el esquema está abierto por defecto.setIsOpen(boolean $isOpen)- establece el estado isOpen.boolean isItalic()-TRUEsi el elemento de esquema se muestra en cursiva.setIsItalic(boolean $isItalic)- establece el estado isItalic.boolean isBold()-TRUEsi el elemento de esquema se muestra en negrita.setIsBold(boolean $isBold)- establece el estado isBold.Zend_Pdf_Color_Rgb getColor()- obtiene el color del texto del esquema (NULLsignifica negro).setColor(Zend_Pdf_Color_Rgb $color)- establece el color del texto del esquema (NULLsignifica negro).Zend_Pdf_Target getTarget()- obtiene el objetivo del esquema (objeto de acción, destino explícito o con nombre).setTarget(Zend_Pdf_Target|string $target)- establece el objetivo del esquema (acción o destino). Puede usarse una cadena para identificar un destino con nombre.NULLsignifica 'sin objetivo'.array getOptions()- obtiene los atributos del esquema como un array.setOptions(array $options)- establece las opciones del esquema. Se reconocen las siguientes opciones: 'title', 'open', 'color', 'italic', 'bold' y 'target'.
Un nuevo esquema puede crearse de dos formas:
Zend_Pdf_Outline::create(string $title[, Zend_Pdf_Target|string $target])Zend_Pdf_Outline::create(array $options)
Cada objeto de esquema puede tener elementos de esquema hijos listados en la
propiedad pública Zend_Pdf_Outline::$childOutlines.
Es un array de objetos Zend_Pdf_Outline,
por lo que los esquemas se organizan en un árbol.
La clase Zend_Pdf_Outline implementa la interfaz RecursiveArray,
por lo que los esquemas hijos pueden iterarse recursivamente usando RecursiveIteratorIterator:
$pdf = Zend_Pdf::load($path);
foreach ($pdf->outlines as $documentRootOutlineEntry) {
$iterator = new RecursiveIteratorIterator(
$documentRootOutlineEntry,
RecursiveIteratorIterator::SELF_FIRST
);
foreach ($iterator as $childOutlineItem) {
$OutlineItemTarget = $childOutlineItem->getTarget();
if ($OutlineItemTarget instanceof Zend_Pdf_Destination) {
if ($pdf->resolveDestination($OutlineItemTarget) === null) {
// Mark Outline item with unresolvable destination
// using RED color
$childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
}
} else if ($OutlineItemTarget instanceof Zend_Pdf_Action_GoTo) {
$OutlineItemTarget->setDestination();
if ($pdf->resolveDestination($OutlineItemTarget) === null) {
// Mark Outline item with unresolvable destination
// using RED color
$childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
}
}
}
}
$pdf->save($path, true);
|
Nota |
|---|---|
Todos los elementos de esquema con destinos no resueltos (o destinos de acciones
GoTo) se actualizan al guardar el documento, estableciendo sus objetivos a
|
Una anotación asocia un objeto, como una nota, un sonido o una película, con una ubicación en una página de un documento PDF, o proporciona una forma de interactuar con el usuario mediante el ratón y el teclado.
Todas las anotaciones están representadas por la clase abstracta
Zend_Pdf_Annotation.
Una anotación puede adjuntarse a una página usando el método
Zend_Pdf_Page::attachAnnotation(Zend_Pdf_Annotation
$annotation).
Actualmente el usuario puede crear tres tipos de anotaciones:
Zend_Pdf_Annotation_Link::create($x1, $y1, $x2, $y2, $target)donde$targetes un objeto de acción, un destino, o una cadena (que puede usarse en lugar de un objeto de destino con nombre).Zend_Pdf_Annotation_Text::create($x1, $y1, $x2, $y2, $text)Zend_Pdf_Annotation_FileAttachment::create($x1, $y1, $x2, $y2, $fileSpecification)
Una anotación de enlace representa un hipervínculo a un destino en otra parte del documento, o una acción a ejecutar.
Una anotación de texto representa una "nota adhesiva" adjunta a un punto del documento PDF.
Una anotación de archivo adjunto contiene una referencia a un archivo.
Los siguientes métodos son compartidos por todos los tipos de anotación:
setLeft(float $left)float getLeft()setRight(float $right)float getRight()setTop(float $top)float getTop()setBottom(float $bottom)float getBottom()setText(string $text)string getText()
La propiedad de texto de la anotación es el texto que se mostrará para la anotación o, si este tipo de anotación no muestra texto, una descripción alternativa del contenido de la anotación en forma legible por humanos.
Los objetos de anotación de enlace también proporcionan dos métodos adicionales:
setDestination(Zend_Pdf_Target|string $target)Zend_Pdf_Target getDestination()