Merge remote-tracking branch

'geraldb-nicat/PHPWord/templateProcessingViaArray' into develop

Conflicts:
	docs/templates-processing.rst

docs/templates-processing.rst

@@ -17,13 +17,23 @@ Given a template containing
 
 .. code-block:: clean
 
-    Hello ${name}!
+    Hello ${firstname} ${lastname}!
 
-The following will replace ``${name}`` with ``World``. The resulting document will now contain ``Hello World!``
+The following will replace ``${firstname}`` with ``John``, and ``${lastname}`` with ``Doe`` .
+The resulting document will now contain ``Hello John Doe!``
 
 .. code-block:: php
 
-    $templateProcessor->setValue('name', 'World');
+    $templateProcessor->setValue('firstname', 'John');
+    $templateProcessor->setValue('lastname', 'Doe');
+
+setValues
+"""""""""
+You can also set multiple values by passing all of them in an array.
+
+.. code-block:: php
+
+    $templateProcessor->setValues(array('firstname' => 'John', 'lastname' => 'Doe'));
 
 setImageValue
 """""""""""""
@@ -138,11 +148,11 @@ See ``Sample_07_TemplateCloneRow.php`` for an example.
 
 .. code-block:: clean
 
-    ------------------------------
+    +-----------+----------------+
     | ${userId} | ${userName}    |
-    |           |----------------|
+    |           |----------------+
     |           | ${userAddress} |
-    ------------------------------
+    +-----------+----------------+
 
 .. code-block:: php
 
@@ -152,15 +162,49 @@ Will result in
 
 .. code-block:: clean
 
-    ----------------------------------
+    +-------------+------------------+
     | ${userId#1} | ${userName#1}    |
-    |             |------------------|
+    |             |------------------+
     |             | ${userAddress#1} |
-    ---------------------------------|
+    +-------------+------------------+
     | ${userId#2} | ${userName#2}    |
-    |             |------------------|
+    |             |------------------+
     |             | ${userAddress#2} |
-    ----------------------------------
+    +-------------+------------------+
+
+cloneRowAndSetValues
+""""""""""""""""""""
+Finds a row in a table row identified by `$search` param and clones it as many times as there are entries in `$values`.
+
+.. code-block:: clean
+
+    +-----------+----------------+
+    | ${userId} | ${userName}    |
+    |           |----------------+
+    |           | ${userAddress} |
+    +-----------+----------------+
+
+.. code-block:: php
+
+    $values = [
+        ['userId' => 1, 'userName' => 'Batman', 'userAddress' => 'Gotham City'],
+        ['userId' => 2, 'userName' => 'Superman', 'userAddress' => 'Metropolis'],
+    ];
+    $templateProcessor->cloneRowAndSetValues('userId', );
+
+Will result in
+
+.. code-block:: clean
+
+    +---+-------------+
+    | 1 | Batman      |
+    |   |-------------+
+    |   | Gotham City |
+    +---+-------------+
+    | 2 | Superman    |
+    |   |-------------+
+    |   | Metropolis  |
+    +---+-------------+
 
 applyXslStyleSheet
 """"""""""""""""""

samples/Sample_07_TemplateCloneRow.php

@@ -36,22 +36,46 @@ $templateProcessor->setValue('rowNumber#9', '9');
 $templateProcessor->setValue('rowNumber#10', '10');
 
 // Table with a spanned cell
-$templateProcessor->cloneRow('userId', 3);
+$values = array(
+    array(
+        'userId'        => 1,
+        'userFirstName' => 'James',
+        'userName'      => 'Taylor',
+        'userPhone'     => '+1 428 889 773',
+    ),
+    array(
+        'userId'        => 2,
+        'userFirstName' => 'Robert',
+        'userName'      => 'Bell',
+        'userPhone'     => '+1 428 889 774',
+    ),
+    array(
+        'userId'        => 3,
+        'userFirstName' => 'Michael',
+        'userName'      => 'Ray',
+        'userPhone'     => '+1 428 889 775',
+    ),
+);
 
-$templateProcessor->setValue('userId#1', '1');
+$templateProcessor->cloneRowAndSetValues('userId', $values);
-$templateProcessor->setValue('userFirstName#1', 'James');
-$templateProcessor->setValue('userName#1', 'Taylor');
-$templateProcessor->setValue('userPhone#1', '+1 428 889 773');
 
-$templateProcessor->setValue('userId#2', '2');
+//this is equivalent to cloning and settings values with cloneRowAndSetValues
-$templateProcessor->setValue('userFirstName#2', 'Robert');
+// $templateProcessor->cloneRow('userId', 3);
-$templateProcessor->setValue('userName#2', 'Bell');
-$templateProcessor->setValue('userPhone#2', '+1 428 889 774');
 
-$templateProcessor->setValue('userId#3', '3');
+// $templateProcessor->setValue('userId#1', '1');
-$templateProcessor->setValue('userFirstName#3', 'Michael');
+// $templateProcessor->setValue('userFirstName#1', 'James');
-$templateProcessor->setValue('userName#3', 'Ray');
+// $templateProcessor->setValue('userName#1', 'Taylor');
-$templateProcessor->setValue('userPhone#3', '+1 428 889 775');
+// $templateProcessor->setValue('userPhone#1', '+1 428 889 773');
+
+// $templateProcessor->setValue('userId#2', '2');
+// $templateProcessor->setValue('userFirstName#2', 'Robert');
+// $templateProcessor->setValue('userName#2', 'Bell');
+// $templateProcessor->setValue('userPhone#2', '+1 428 889 774');
+
+// $templateProcessor->setValue('userId#3', '3');
+// $templateProcessor->setValue('userFirstName#3', 'Michael');
+// $templateProcessor->setValue('userName#3', 'Ray');
+// $templateProcessor->setValue('userPhone#3', '+1 428 889 775');
 
 echo date('H:i:s'), ' Saving the result document...', EOL;
 $templateProcessor->saveAs('results/Sample_07_TemplateCloneRow.docx');

src/PhpWord/TemplateProcessor.php

@@ -284,6 +284,18 @@ class TemplateProcessor
         $this->tempDocumentFooters = $this->setValueForPart($search, $replace, $this->tempDocumentFooters, $limit);
     }
 
+    /**
+     * Set values from a one-dimensional array of "variable => value"-pairs.
+     *
+     * @param array $values
+     */
+    public function setValues(array $values)
+    {
+        foreach ($values as $macro => $replace) {
+            $this->setValue($macro, $replace);
+        }
+    }
+
     private function getImageArgs($varNameWithArgs)
     {
         $varElements = explode(':', $varNameWithArgs);
@@ -641,6 +653,24 @@ class TemplateProcessor
         $this->tempDocumentMainPart = $result;
     }
 
+    /**
+     * Clones a table row and populates it's values from a two-dimensional array in a template document.
+     *
+     * @param string $search
+     * @param array $values
+     */
+    public function cloneRowAndSetValues($search, $values)
+    {
+        $this->cloneRow($search, count($values));
+
+        foreach ($values as $rowKey => $rowData) {
+            $rowNumber = $rowKey + 1;
+            foreach ($rowData as $macro => $replace) {
+                $this->setValue($macro . '#' . $rowNumber, $replace);
+            }
+        }
+    }
+
     /**
      * Clone a block.
      *

tests/PhpWord/TemplateProcessorTest.php

@@ -196,6 +196,67 @@ final class TemplateProcessorTest extends \PHPUnit\Framework\TestCase
         $this->assertTrue($docFound);
     }
 
+    /**
+     * @covers ::setValue
+     * @covers ::cloneRow
+     * @covers ::saveAs
+     * @test
+     */
+    public function testCloneRowAndSetValues()
+    {
+        $mainPart = '<w:tbl>
+            <w:tr>
+                <w:tc>
+                    <w:tcPr>
+                        <w:vMerge w:val="restart"/>
+                    </w:tcPr>
+                    <w:p>
+                        <w:r>
+                            <w:t>${userId}</w:t>
+                        </w:r>
+                    </w:p>
+                </w:tc>
+                <w:tc>
+                    <w:p>
+                        <w:r>
+                            <w:t>${userName}</w:t>
+                        </w:r>
+                    </w:p>
+                </w:tc>
+            </w:tr>
+            <w:tr>
+                <w:tc>
+                    <w:tcPr>
+                        <w:vMerge/>
+                    </w:tcPr>
+                    <w:p/>
+                </w:tc>
+                <w:tc>
+                    <w:p>
+                        <w:r>
+                            <w:t>${userLocation}</w:t>
+                        </w:r>
+                    </w:p>
+                </w:tc>
+            </w:tr>
+        </w:tbl>';
+        $templateProcessor = new TestableTemplateProcesor($mainPart);
+
+        $this->assertEquals(
+            array('userId', 'userName', 'userLocation'),
+            $templateProcessor->getVariables()
+        );
+
+        $values = array(
+            array('userId' => 1, 'userName' => 'Batman', 'userLocation' => 'Gotham City'),
+            array('userId' => 2, 'userName' => 'Superman', 'userLocation' => 'Metropolis'),
+        );
+        $templateProcessor->setValue('tableHeader', 'My clonable table');
+        $templateProcessor->cloneRowAndSetValues('userId', $values);
+        $this->assertContains('<w:t>Superman</w:t>', $templateProcessor->getMainPart());
+        $this->assertContains('<w:t>Metropolis</w:t>', $templateProcessor->getMainPart());
+    }
+
     /**
      * @expectedException \Exception
      * @test
@@ -246,6 +307,25 @@ final class TemplateProcessorTest extends \PHPUnit\Framework\TestCase
         );
     }
 
+    /**
+     * @covers ::setValues
+     * @test
+     */
+    public function testSetValues()
+    {
+        $mainPart = '<?xml version="1.0" encoding="UTF-8"?>
+        <w:p>
+            <w:r>
+                <w:t xml:space="preserve">Hello ${firstname} ${lastname}</w:t>
+            </w:r>
+        </w:p>';
+
+        $templateProcessor = new TestableTemplateProcesor($mainPart);
+        $templateProcessor->setValues(array('firstname' => 'John', 'lastname' => 'Doe'));
+
+        $this->assertContains('Hello John Doe', $templateProcessor->getMainPart());
+    }
+
     /**
      * @covers ::setImageValue
      * @test