Zend_Pdf: outlines (bookmarks) documentation.

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@17237 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Pdf-InteractiveFeatures.xml

@@ -792,7 +792,7 @@ $pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page3'));
 
             <para>
                 Only <classname>Zend_Pdf_Action_GoTo</classname> actions can be created by
-                user now. It can be done using
+                user now. It can be done using 
                 <methodname>Zend_Pdf_Action_GoTo::create($destination)</methodname> method,
                 where <varname>$destination</varname> is a
                 <classname>Zend_Pdf_Destination</classname> object or string which can be used
@@ -854,15 +854,230 @@ $iterator = new RecursiveIteratorIterator(
 foreach ($iterator as $chainedAction) {
     $actionsCount++;
 }
-printf("Actions in a tree: %d\n", $actionsCount++);
+printf("Actions in a tree: %d\n", $actionsCount++); // Prints 'Actions in a tree: 4'
 ]]></programlisting>
         </sect3>
+
+        <sect3 id="zend.pdf.pages.interactive-features.actions.open-action">
+            <title>Document Open Action</title>
+            
+            <para>
+                Special open action may be specify a destination to be displayed or an action 
+                to be performed when the document is opened.
+            </para>
+            
+            <para>
+                <methodname>Zend_Pdf_Target Zend_Pdf::getOpenAction()</methodname> method 
+                returns current document open action (or null if open action is not set).
+            </para>
+
+            <para>
+                <methodname>setOpenAction(Zend_Pdf_Target $openAction = null)</methodname> 
+                method sets document open action or clean it if <varname>$openAction</varname>
+                is null.
+            </para>
+        </sect3>
     </sect2>
 
     <sect2 id="zend.pdf.pages.interactive-features.outlines">
         <title>Document Outline (bookmarks)</title>
         <para>
+            A PDF document may optionally display a document outline on the screen, allowing
+            the user to navigate interactively from one part of the document to another.
+            The outline consists of a tree-structured hierarchy of outline items (sometimes
+            called bookmarks), which serve as a visual table of contents to display the document’s
+            structure to the user. The user can interactively open and close individual
+            items by clicking them with the mouse. When an item is open, its immediate children
+            in the hierarchy become visible on the screen; each child may in turn be
+            open or closed, selectively revealing or hiding further parts of the hierarchy.
+            When an item is closed, all of its descendants in the hierarchy are hidden. Clicking
+            the text of any visible item activates the item, causing the viewer application to
+            jump to a destination or trigger an action associated with the item.
+        </para>
+        
+        <para>
+            <classname>Zend_Pdf</classname> class provides public property 
+            <varname>$outlines</varname> which is an array of 
+            <classname>Zend_Pdf_Outline</classname> objects.
+            <programlisting language="php"><![CDATA[
+$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);
+]]></programlisting>
+        </para>
+        
+        <para>
+            Outline attributes may be retrieved or set using the following methods:
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <methodname>string getTitle()</methodname> - get outline item title.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setTitle(string $title)</methodname> - set outline item title.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>boolean isOpen()</methodname> - true if outline is open 
+                        by default.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setIsOpen(boolean $isOpen)</methodname> - set isOpen state.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>boolean isItalic()</methodname> - true if outline item 
+                        is displayed in italic.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setIsItalic(boolean $isItalic)</methodname> - set 
+                        isItalic state.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>boolean isBold()</methodname> - true if outline item 
+                        is displayed in bold.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setIsBold(boolean $isBold)</methodname> - set 
+                        isBold state.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>Zend_Pdf_Color_Rgb getColor()</methodname> - get outline 
+                        text color (null means black).
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setColor(Zend_Pdf_Color_Rgb $color)</methodname> - set 
+                        outline text color (null means black).
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>Zend_Pdf_Target getTarget()</methodname> - get outline 
+                        target (action or explicit or named destination object).
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setTarget(Zend_Pdf_Target|string $target)</methodname> - set 
+                        outline target (action or destination). String may be used to identify
+                        named destination. Null means 'no target'.
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>array getOptions()</methodname> - get outline attributes 
+                        as an array. 
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>setOptions(array $options)</methodname> - set outline options. 
+                        The following options are recognized: 'title', 'open', 'color', 'italic',
+                        'bold', and 'target'.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            New outline may be created in two ways:        
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <methodname>Zend_Pdf_Outline::create(string $title[, Zend_Pdf_Target|string $target])</methodname>
+                    </para>
+                </listitem>
+
+                <listitem>
+                    <para>
+                        <methodname>Zend_Pdf_Outline::create(array $options)</methodname>
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Each outline object may have child outline items listed in 
+            <varname>Zend_Pdf_Outline::$childOutlines</varname> public property.
+            It's an array of <classname>Zend_Pdf_Outline</classname> objects, 
+            so outlines are organized in a tree. 
+        </para>
+
+        <para>
+            <classname>Zend_Pdf_Outline</classname> class implements RecursiveArray interface,
+            so child outlines may be recursively iterated using RecursiveIteratorIterator:
+            <programlisting language="php"><![CDATA[
+$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) {
+            if ($pdf->resolveDestination($OutlineItemTarget->setDestination()) === null) {
+                // Mark Outline item with unresolvable destination using RED color
+                $childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
+            }
+        }
+    }
+}
+
+$pdf->save($path, true);
+]]></programlisting>
         </para>
+        
+        <note>
+            <para>
+                All outline items with unresolved destinations (or destinations of GoTo
+                actions) are updated while document saving by setting their targets to null.
+                So document will not be corrupted by removing pages referenced by outlines.
+            </para>
+        </note>
     </sect2>
 
     <sect2 id="zend.pdf.pages.interactive-features.annotations">

library/Zend/Pdf.php

@@ -859,9 +859,9 @@ class Zend_Pdf
 
     /**
      * Get open Action
-     * Returns Zend_Pdf_Destination or Zend_Pdf_Action (which is actually GoTo Action) object
+     * Returns Zend_Pdf_Target (Zend_Pdf_Destination or Zend_Pdf_Action object)
      *
-     * @return Zend_Pdf_Destination|Zend_Pdf_Action
+     * @return Zend_Pdf_Target
      */
     public function getOpenAction()
     {
@@ -875,23 +875,25 @@ class Zend_Pdf
     /**
      * Set open Action which is actually Zend_Pdf_Destination or Zend_Pdf_Action object
      *
-     * @param Zend_Pdf_Destination|Zend_Pdf_Action $openAction
-     * @throws Zend_Pdf_Exception
+     * @param Zend_Pdf_Target $openAction
+     * @returns Zend_Pdf
      */
-    public function setOpenAction($openAction)
+    public function setOpenAction(Zend_Pdf_Target $openAction = null)
     {
         $root = $this->_trailer->Root;
         $root->touch();
 
         if ($openAction === null) {
             $root->OpenAction = null;
-        } else if ($openAction instanceof Zend_Pdf_Target) {
-            $root->OpenAction = $openAction->getResource();
-            $openAction->dumpAction($this->_objFactory);
         } else {
-            require_once 'Zend/Pdf/Exception.php';
-            throw new Zend_Pdf_Exception('Open action must be a Zend_Pdf_Target or null.');
+            $root->OpenAction = $openAction->getResource();
+
+            if ($openAction instanceof Zend_Pdf_Action)  {
+                $openAction->dumpAction($this->_objFactory);
+            }
         }
+
+        return $this;
     }
 
     /**

library/Zend/Pdf/Outline.php

@@ -215,7 +215,7 @@ abstract class Zend_Pdf_Outline implements RecursiveIterator, Countable
      *
      * It provides two forms of input parameters:
      *
-     * 1. Zend_Pdf_Outline::create(string $title[, Zend_Pdf_Destination $destination])
+     * 1. Zend_Pdf_Outline::create(string $title[, Zend_Pdf_Target $target])
      * 2. Zend_Pdf_Outline::create(array $options)
      *
      * Second form allows to provide outline options as an array.
@@ -225,7 +225,7 @@ abstract class Zend_Pdf_Outline implements RecursiveIterator, Countable
      *   'color'  - Zend_Pdf_Color_Rgb object, true if outline entry is open (default value is null - black)
      *   'italic' - boolean, true if outline entry is displayed in italic (default value is false)
      *   'bold'   - boolean, true if outline entry is displayed in bold (default value is false)
-     *   'target' - Zend_Pdf_Destination object, outline item destination
+     *   'target' - Zend_Pdf_Target object or string, outline item destination
      *
      * @return Zend_Pdf_Outline
      * @throws Zend_Pdf_Exception
@@ -233,9 +233,9 @@ abstract class Zend_Pdf_Outline implements RecursiveIterator, Countable
     public static function create($param1, $param2 = null)
     {
         if (is_string($param1)) {
-            if ($param2 !== null  &&  !$param2 instanceof Zend_Pdf_Destination) {
+            if ($param2 !== null  &&  !($param2 instanceof Zend_Pdf_Target  ||  is_string($param2))) {
                 require_once 'Zend/Pdf/Exception.php';
-                throw new Zend_Pdf_Exception('Outline create method takes $title (string) and $destination (Zend_Pdf_Destination) or an array as an input');
+                throw new Zend_Pdf_Exception('Outline create method takes $title (string) and $target (Zend_Pdf_Target or string) or an array as an input');
             }
 
             require_once 'Zend/Pdf/Outline/Created.php';