Zend_Pdf: URI action support. ZF-8390.

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

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

@@ -791,15 +791,26 @@ $pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page3'));
             </itemizedlist>
 
             <para>
-                Only <classname>Zend_Pdf_Action_GoTo</classname> actions can be created by
-                user now. It can be done using
+                Only <classname>Zend_Pdf_Action_GoTo</classname> and 
+                <classname>Zend_Pdf_Action_URI</classname> actions can be created by
+                user now.
+            </para>
+
+            <para>
+                GoTo action object can be created 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
+                <classname>Zend_Pdf_Destination</classname> object or a string which can be used
                 to identify named destination.
             </para>
 
             <para>
+                <methodname>Zend_Pdf_Action_URI::create($uri[, $isMap])</methodname> method has
+                to be used to create a URI action (see API documentation for the details).
+                Optional <varname>$isMap</varname> parameter is set to false by default. 
+            </para>
+
+            <para>
                 It also supports the following methods:
             </para>
         </sect3>

library/Zend/Pdf/Action/GoTo.php

@@ -53,7 +53,6 @@ class Zend_Pdf_Action_GoTo extends Zend_Pdf_Action
      *
      * @param Zend_Pdf_Element_Dictionary $dictionary
      * @param SplObjectStorage            $processedActions  list of already processed action dictionaries, used to avoid cyclic references
-     * @throws Zend_Pdf_Exception
      */
     public function __construct(Zend_Pdf_Element $dictionary, SplObjectStorage $processedActions)
     {
@@ -92,6 +91,7 @@ class Zend_Pdf_Action_GoTo extends Zend_Pdf_Action
     /**
      * Set goto action destination
      *
+     * @param Zend_Pdf_Destination|string $destination
      * @return Zend_Pdf_Action_GoTo
      */
     public function setDestination(Zend_Pdf_Destination $destination)

library/Zend/Pdf/Action/URI.php

@@ -20,6 +20,13 @@
  * @version    $Id$
  */
 
+/** Internally used classes */
+require_once 'Zend/Pdf/Element/Dictionary.php';
+require_once 'Zend/Pdf/Element/Name.php';
+require_once 'Zend/Pdf/Element/String.php';
+require_once 'Zend/Pdf/Element/Boolean.php';
+
+
 /** Zend_Pdf_Action */
 require_once 'Zend/Pdf/Action.php';
 
@@ -27,6 +34,8 @@ require_once 'Zend/Pdf/Action.php';
 /**
  * PDF 'Resolve a uniform resource identifier' action
  *
+ * A URI action causes a URI to be resolved.
+ *
  * @package    Zend_Pdf
  * @subpackage Actions
  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
@@ -34,4 +43,125 @@ require_once 'Zend/Pdf/Action.php';
  */
 class Zend_Pdf_Action_URI extends Zend_Pdf_Action
 {
+    /**
+     * Object constructor
+     *
+     * @param Zend_Pdf_Element_Dictionary $dictionary
+     * @param SplObjectStorage            $processedActions  list of already processed action dictionaries, used to avoid cyclic references
+     * @throws Zend_Pdf_Exception
+     */
+    public function __construct(Zend_Pdf_Element $dictionary, SplObjectStorage $processedActions)
+    {
+        parent::__construct($dictionary, $processedActions);
+
+        if ($dictionary->URI === null) {
+            require_once 'Zend/Pdf/Exception.php';
+            throw new Zend_Pdf_Exception('URI action dictionary entry is required');
+        }
+    }
+
+    /**
+     * Validate URI
+     *
+     * @param string $uri
+     * @return true
+     * @throws Zend_Pdf_Exception
+     */
+    protected static function _validateUri($uri)
+    {
+        $scheme = parse_url((string)$uri, PHP_URL_SCHEME);
+        if ($scheme === false || $scheme === null) {
+            require_once 'Zend/Pdf/Exception.php';
+            throw new Zend_Pdf_Exception('Invalid URI');
+        }
+    }
+
+    /**
+     * Create new Zend_Pdf_Action_URI object using specified uri
+     *
+     * @param string  $uri    The URI to resolve, encoded in 7-bit ASCII
+     * @param boolean $isMap  A flag specifying whether to track the mouse position when the URI is resolved
+     * @return Zend_Pdf_Action_URI
+     */
+    public static function create($uri, $isMap = false)
+    {
+        self::_validateUri($uri);
+
+        $dictionary = new Zend_Pdf_Element_Dictionary();
+        $dictionary->Type = new Zend_Pdf_Element_Name('Action');
+        $dictionary->S    = new Zend_Pdf_Element_Name('URI');
+        $dictionary->Next = null;
+        $dictionary->URI  = new Zend_Pdf_Element_String($uri);
+        if ($isMap) {
+            $dictionary->IsMap = new Zend_Pdf_Element_Boolean(true);
+        }
+
+        return new Zend_Pdf_Action_URI($dictionary, new SplObjectStorage());
+    }
+
+    /**
+     * Set URI to resolve
+     *
+     * @param string $uri   The uri to resolve, encoded in 7-bit ASCII.
+     * @return Zend_Pdf_Action_URI
+     */
+    public function setUri($uri)
+    {
+        $this->_validateUri($uri);
+
+        $this->_actionDictionary->touch();
+        $this->_actionDictionary->URI = new Zend_Pdf_Element_String($uri);
+
+        return $this;
+    }
+
+    /**
+     * Get URI to resolve
+     *
+     * @return string
+     */
+    public function getUri()
+    {
+        return $this->_actionDictionary->URI->value;
+    }
+
+    /**
+     * Set IsMap property
+     *
+     * If the IsMap flag is true and the user has triggered the URI action by clicking
+     * an annotation, the coordinates of the mouse position at the time the action is
+     * performed should be transformed from device space to user space and then offset
+     * relative to the upper-left corner of the annotation rectangle.
+     *
+     * @param boolean $isMap  A flag specifying whether to track the mouse position when the URI is resolved
+     * @return Zend_Pdf_Action_URI
+     */
+    public function setIsMap($isMap)
+    {
+        $this->_actionDictionary->touch();
+
+        if ($isMap) {
+            $this->_actionDictionary->IsMap = new Zend_Pdf_Element_Boolean(true);
+        } else {
+            $this->_actionDictionary->IsMap = null;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get IsMap property
+     *
+     * If the IsMap flag is true and the user has triggered the URI action by clicking
+     * an annotation, the coordinates of the mouse position at the time the action is
+     * performed should be transformed from device space to user space and then offset
+     * relative to the upper-left corner of the annotation rectangle.
+     *
+     * @return boolean
+     */
+    public function getIsMap()
+    {
+        return $this->_actionDictionary->IsMap !== null  &&
+               $this->_actionDictionary->IsMap->value;
+    }
 }

tests/Zend/Pdf/ActionTest.php

@@ -23,7 +23,13 @@
 /** Zend_Pdf_Action */
 require_once 'Zend/Pdf/Action.php';
 
-/** Zend_Pdf_Action */
+/** Zend_Pdf_Action_GoTo */
+require_once 'Zend/Pdf/Action/GoTo.php';
+
+/** Zend_Pdf_Action_URI */
+require_once 'Zend/Pdf/Action/URI.php';
+
+/** Zend_Pdf_ElementFactory */
 require_once 'Zend/Pdf/ElementFactory.php';
 
 /** Zend_Pdf */
@@ -372,6 +378,65 @@ class Zend_Pdf_ActionTest extends PHPUnit_Framework_TestCase
         $this->assertTrue($pdf->resolveDestination($action2->getDestination()) === null);
     }
 
+    public function testActionURILoad1()
+    {
+        $dictionary = new Zend_Pdf_Element_Dictionary();
+        $dictionary->Type = new Zend_Pdf_Element_Name('Action');
+        $dictionary->S    = new Zend_Pdf_Element_Name('URI');
+        $dictionary->URI  = new Zend_Pdf_Element_String('http://somehost/');
+
+        $action = Zend_Pdf_Action::load($dictionary);
+
+        $this->assertTrue($action instanceof Zend_Pdf_Action_URI);
+    }
+
+    public function testActionURILoad2()
+    {
+        $dictionary = new Zend_Pdf_Element_Dictionary();
+        $dictionary->Type = new Zend_Pdf_Element_Name('Action');
+        $dictionary->S    = new Zend_Pdf_Element_Name('URI');
+
+
+        try {
+            $action = Zend_Pdf_Action::load($dictionary);
+            $this->fail("exception expected");
+        } catch (Zend_Pdf_Exception $e) {
+            $this->assertContains('URI action dictionary entry is required', $e->getMessage());
+        }
+    }
+
+    public function testActionURICreate()
+    {
+        $action = Zend_Pdf_Action_URI::create('http://somehost/');
+
+        $this->assertTrue($action instanceof Zend_Pdf_Action_URI);
+
+        $this->assertEquals($action->getResource()->toString(),
+                            '<</Type /Action /S /URI /URI (http://somehost/) >>');
+    }
+
+    public function testActionURIGettersSetters()
+    {
+        $action = Zend_Pdf_Action_URI::create('http://somehost/');
+
+        $this->assertEquals($action->getUri(), 'http://somehost/');
+
+        $action->setUri('http://another_host/');
+        $this->assertEquals($action->getUri(), 'http://another_host/');
+
+        $this->assertEquals($action->getIsMap(), false);
+
+        $action->setIsMap(true);
+        $this->assertEquals($action->getIsMap(), true);
+        $this->assertEquals($action->getResource()->toString(),
+                            '<</Type /Action /S /URI /URI (http://another_host/) /IsMap true >>');
+
+        $action->setIsMap(false);
+        $this->assertEquals($action->getIsMap(), false);
+        $this->assertEquals($action->getResource()->toString(),
+                            '<</Type /Action /S /URI /URI (http://another_host/) >>');
+    }
+
     /**
      * @group ZF-8462
      */