Merge pull request #305 from jonnsn/internal-links

Internal links

docs/elements.rst

@@ -53,6 +53,8 @@ column shows the containers while the rows lists the elements.
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 22    | Form fields     | v         | v        | v        | v       | v          | v          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
+| 23    | Bookmarks       | v         | -        | -        | v       | v          | -          |
++-------+-----------------+-----------+----------+----------+---------+------------+------------+
 
 Legend:
 
@@ -129,12 +131,13 @@ You can add Hyperlinks to the document by using the function addLink:
 
 .. code-block:: php
 
-    $section->addLink($linkSrc, [$linkName], [$fontStyle], [$paragraphStyle]);
+    $section->addLink($linkSrc, [$linkName], [$fontStyle], [$paragraphStyle], [$isInternal]);
 
 -  ``$linkSrc`` The URL of the link.
 -  ``$linkName`` Placeholder of the URL that appears in the document.
 -  ``$fontStyle`` See "Font style" section.
 -  ``$paragraphStyle`` See "Paragraph style" section.
+-  ``$isInternal`` Set to true, if the link points to a bookmark inside the document
 
 Preserve texts
 ~~~~~~~~~~~~~~
@@ -429,3 +432,14 @@ Form fields
 -----------
 
 To be completed.
+
+Bookmarks
+~~~~~
+
+You can add Bookmarks to the document by using the function addBookmark:
+
+.. code-block:: php
+
+    $section->addBookmark($name);
+
+-  ``$name`` The name of the bookmark which can be referenced in the addLink-Function as target. Should obviously be unique throughout the document.

samples/Sample_35_InternalLink.php

@@ -0,0 +1,22 @@
+<?php
+include_once 'Sample_Header.php';
+
+// New Word document
+echo date('H:i:s'), " Create new PhpWord object", EOL;
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+
+$section = $phpWord->addSection();
+$section->addTitle( 'This is page 1', 1 );
+$linkIsInternal = true;
+$section->addLink('MyBookmark', 'Take me to page 3', null ,null,$linkIsInternal);
+$section->addPageBreak();
+$section->addTitle( 'This is page 2', 1 );
+$section->addPageBreak();
+$section->addTitle( 'This is page 3', 1 );
+$section->addBookmark('MyBookmark');
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

src/PhpWord/Collection/Bookmarks.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @link        https://github.com/PHPOffice/PHPWord
+ * @copyright   2010-2014 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt LGPL
+ */
+
+namespace PhpOffice\PhpWord\Collection;
+
+/**
+ * Bookmarks collection
+ *
+ * @since 0.12.0
+ */
+class Bookmarks extends AbstractCollection
+{
+}

src/PhpWord/Element/AbstractContainer.php

@@ -22,6 +22,7 @@ namespace PhpOffice\PhpWord\Element;
  *
  * @method Text addText(string $text, mixed $fStyle = null, mixed $pStyle = null)
  * @method TextRun addTextRun(mixed $pStyle = null)
+ * @method Bookmark addBookmark(string $name)
  * @method Link addLink(string $target, string $text = null, mixed $fStyle = null, mixed $pStyle = null)
  * @method PreserveText addPreserveText(string $text, mixed $fStyle = null, mixed $pStyle = null)
  * @method void addTextBreak(int $count = 1, mixed $fStyle = null, mixed $pStyle = null)
@@ -78,7 +79,7 @@ abstract class AbstractContainer extends AbstractElement
     public function __call($function, $args)
     {
         $elements = array(
-            'Text', 'TextRun', 'Link', 'PreserveText', 'TextBreak',
+            'Text', 'TextRun', 'Bookmark', 'Link', 'PreserveText', 'TextBreak',
             'ListItem', 'ListItemRun', 'Table', 'Image', 'Object',
             'Footnote', 'Endnote', 'CheckBox', 'TextBox', 'Field',
             'Line', 'Shape', 'Title', 'TOC', 'PageBreak',
@@ -189,6 +190,7 @@ abstract class AbstractContainer extends AbstractElement
         );
         $validContainers = array(
             'Text'          => $allContainers,
+            'Bookmark'      => $allContainers,
             'Link'          => $allContainers,
             'TextBreak'     => $allContainers,
             'Image'         => $allContainers,

src/PhpWord/Element/Bookmark.php

@@ -0,0 +1,63 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @link        https://github.com/PHPOffice/PHPWord
+ * @copyright   2010-2014 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\Element;
+
+use PhpOffice\PhpWord\Shared\String;
+use PhpOffice\PhpWord\Style;
+
+/**
+ * Bookmark element
+ */
+class Bookmark extends AbstractElement
+{
+    /**
+     * Bookmark Name
+     *
+     * @var string
+     */
+    private $name;
+
+    /**
+     * Is part of collection
+     *
+     * @var bool
+     */
+    protected $collectionRelation = true;
+
+    /**
+     * Create a new Bookmark Element
+     *
+     * @param string $name
+     */
+    public function __construct($name)
+    {
+
+        $this->name = String::toUTF8($name);
+        return $this;
+    }
+
+    /**
+     * Get Bookmark name
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+}

src/PhpWord/Element/Link.php

@@ -61,6 +61,13 @@ class Link extends AbstractElement
      */
     protected $mediaRelation = true;
 
+    /**
+     * Has internal flag - anchor to internal bookmark
+     *
+     * @var bool
+     */
+    protected $internal = false;
+
     /**
      * Create a new Link Element
      *
@@ -69,13 +76,13 @@ class Link extends AbstractElement
      * @param mixed $fontStyle
      * @param mixed $paragraphStyle
      */
-    public function __construct($source, $text = null, $fontStyle = null, $paragraphStyle = null)
+    public function __construct($source, $text = null, $fontStyle = null, $paragraphStyle = null, $internal = false)
     {
         $this->source = String::toUTF8($source);
         $this->text = is_null($text) ? $this->source : String::toUTF8($text);
         $this->fontStyle = $this->setNewStyle(new Font('text'), $fontStyle);
         $this->paragraphStyle = $this->setNewStyle(new Paragraph(), $paragraphStyle);
-
+        $this->internal = $internal;
         return $this;
     }
 
@@ -154,4 +161,14 @@ class Link extends AbstractElement
     {
         return $this->getText();
     }
+
+    /**
+     * is internal
+     *
+     * @return bool
+     */
+    public function isInternal()
+    {
+        return $this->internal;
+    }
 }

src/PhpWord/PhpWord.php

@@ -27,6 +27,7 @@ use PhpOffice\PhpWord\Exception\Exception;
  * @method Collection\Footnotes getFootnotes()
  * @method Collection\Endnotes getEndnotes()
  * @method Collection\Charts getCharts()
+ * @method int addBookmark(Element\Bookmark $bookmark)
  * @method int addTitle(Element\Title $title)
  * @method int addFootnote(Element\Footnote $footnote)
  * @method int addEndnote(Element\Endnote $endnote)
@@ -82,7 +83,7 @@ class PhpWord
     public function __construct()
     {
         // Collection
-        $collections = array('Titles', 'Footnotes', 'Endnotes', 'Charts');
+        $collections = array('Bookmarks', 'Titles', 'Footnotes', 'Endnotes', 'Charts');
         foreach ($collections as $collection) {
             $class = 'PhpOffice\\PhpWord\\Collection\\' . $collection;
             $this->collections[$collection] = new $class();
@@ -113,7 +114,7 @@ class PhpWord
         $addCollection = array();
         $addStyle = array();
 
-        $collections = array('Title', 'Footnote', 'Endnote', 'Chart');
+        $collections = array('Bookmark', 'Title', 'Footnote', 'Endnote', 'Chart');
         foreach ($collections as $collection) {
             $getCollection[] = strtolower("get{$collection}s");
             $addCollection[] = strtolower("add{$collection}");
@@ -138,7 +139,7 @@ class PhpWord
             /** @var \PhpOffice\PhpWord\Collection\AbstractCollection $collectionObject */
             $collectionObject = $this->collections[$key];
 
-            return $collectionObject->addItem($args[0]);
+            return $collectionObject->addItem(array_key_exists(0, $args) ? $args[0] : null);
         }
 
         // Run add style method

src/PhpWord/Writer/Word2007/Element/Bookmark.php

@@ -0,0 +1,49 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @link        https://github.com/PHPOffice/PHPWord
+ * @copyright   2010-2014 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\Writer\Word2007\Element;
+
+/**
+ * Bookmark element writer
+ *
+ * @since 0.12.0
+ */
+class Bookmark extends AbstractElement
+{
+    /**
+     * Write bookmark element
+     */
+    public function write()
+    {
+        $xmlWriter = $this->getXmlWriter();
+        $element = $this->getElement();
+        if (!$element instanceof \PhpOffice\PhpWord\Element\Bookmark) {
+            return;
+        }
+
+        $rId = $element->getRelationId();
+
+        $xmlWriter->startElement('w:bookmarkStart');
+        $xmlWriter->writeAttribute('w:id', $rId);
+        $xmlWriter->writeAttribute('w:name', $element->getName());
+        $xmlWriter->endElement();
+        
+        $xmlWriter->startElement('w:bookmarkEnd');
+        $xmlWriter->writeAttribute('w:id', $rId);
+        $xmlWriter->endElement();
+    }
+}

src/PhpWord/Writer/Word2007/Element/Link.php

@@ -42,7 +42,11 @@ class Link extends Text
         $this->startElementP();
 
         $xmlWriter->startElement('w:hyperlink');
-        $xmlWriter->writeAttribute('r:id', 'rId' . $rId);
+        if ($element->isInternal()) {
+            $xmlWriter->writeAttribute('w:anchor', $element->getSource());
+        } else {
+            $xmlWriter->writeAttribute('r:id', 'rId' . $rId);
+        }
         $xmlWriter->writeAttribute('w:history', '1');
         $xmlWriter->startElement('w:r');
 

src/PhpWord/Writer/Word2007/Element/Title.php

@@ -50,10 +50,11 @@ class Title extends AbstractElement
         }
 
         $rId = $element->getRelationId();
+        $bookmarkRId = $element->getPhpWord()->addBookmark();
 
         // Bookmark start for TOC
         $xmlWriter->startElement('w:bookmarkStart');
-        $xmlWriter->writeAttribute('w:id', $rId);
+        $xmlWriter->writeAttribute('w:id', $bookmarkRId);
         $xmlWriter->writeAttribute('w:name', "_Toc{$rId}");
         $xmlWriter->endElement();
 
@@ -66,7 +67,7 @@ class Title extends AbstractElement
 
         // Bookmark end
         $xmlWriter->startElement('w:bookmarkEnd');
-        $xmlWriter->writeAttribute('w:id', $rId);
+        $xmlWriter->writeAttribute('w:id', $bookmarkRId);
         $xmlWriter->endElement();
 
         $xmlWriter->endElement();