Skip to content

Commit 1956908

Browse files
troosantroosan
committed
Merge remote-tracking branch
'geraldb-nicat/PHPWord/templateProcessingViaArray' into develop Conflicts: docs/templates-processing.rst
2 parents 3a7b8ab + bcfb3e8 commit 1956908

File tree

4 files changed

+205
-27
lines changed

4 files changed

+205
-27
lines changed

‎docs/templates-processing.rst

Lines changed: 55 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,23 @@ Given a template containing
1717

1818
.. code-block:: clean
1919
20-
Hello ${name}!
20+
Hello ${firstname} ${lastname}!
2121
22-
The following will replace ``${name}`` with ``World``. The resulting document will now contain ``Hello World!``
22+
The following will replace ``${firstname}`` with ``John``, and ``${lastname}`` with ``Doe`` .
23+
The resulting document will now contain ``Hello John Doe!``
2324

2425
.. code-block:: php
2526
26-
$templateProcessor->setValue('name', 'World');
27+
$templateProcessor->setValue('firstname', 'John');
28+
$templateProcessor->setValue('lastname', 'Doe');
29+
30+
setValues
31+
"""""""""
32+
You can also set multiple values by passing all of them in an array.
33+
34+
.. code-block:: php
35+
36+
$templateProcessor->setValues(array('firstname' => 'John', 'lastname' => 'Doe'));
2737
2838
setImageValue
2939
"""""""""""""
@@ -138,11 +148,11 @@ See ``Sample_07_TemplateCloneRow.php`` for an example.
138148

139149
.. code-block:: clean
140150
141-
------------------------------
151+
+-----------+----------------+
142152
| ${userId} | ${userName} |
143-
| |----------------|
153+
| |----------------+
144154
| | ${userAddress} |
145-
------------------------------
155+
+-----------+----------------+
146156
147157
.. code-block:: php
148158
@@ -152,15 +162,49 @@ Will result in
152162

153163
.. code-block:: clean
154164
155-
----------------------------------
165+
+-------------+------------------+
156166
| ${userId#1} | ${userName#1} |
157-
| |------------------|
167+
| |------------------+
158168
| | ${userAddress#1} |
159-
---------------------------------|
169+
+-------------+------------------+
160170
| ${userId#2} | ${userName#2} |
161-
| |------------------|
171+
| |------------------+
162172
| | ${userAddress#2} |
163-
----------------------------------
173+
+-------------+------------------+
174+
175+
cloneRowAndSetValues
176+
""""""""""""""""""""
177+
Finds a row in a table row identified by `$search` param and clones it as many times as there are entries in `$values`.
178+
179+
.. code-block:: clean
180+
181+
+-----------+----------------+
182+
| ${userId} | ${userName} |
183+
| |----------------+
184+
| | ${userAddress} |
185+
+-----------+----------------+
186+
187+
.. code-block:: php
188+
189+
$values = [
190+
['userId' => 1, 'userName' => 'Batman', 'userAddress' => 'Gotham City'],
191+
['userId' => 2, 'userName' => 'Superman', 'userAddress' => 'Metropolis'],
192+
];
193+
$templateProcessor->cloneRowAndSetValues('userId', );
194+
195+
Will result in
196+
197+
.. code-block:: clean
198+
199+
+---+-------------+
200+
| 1 | Batman |
201+
| |-------------+
202+
| | Gotham City |
203+
+---+-------------+
204+
| 2 | Superman |
205+
| |-------------+
206+
| | Metropolis |
207+
+---+-------------+
164208
165209
applyXslStyleSheet
166210
""""""""""""""""""

‎samples/Sample_07_TemplateCloneRow.php

Lines changed: 40 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,22 +36,46 @@
3636
$templateProcessor->setValue('rowNumber#10', '10');
3737

3838
// Table with a spanned cell
39-
$templateProcessor->cloneRow('userId', 3);
40-
41-
$templateProcessor->setValue('userId#1', '1');
42-
$templateProcessor->setValue('userFirstName#1', 'James');
43-
$templateProcessor->setValue('userName#1', 'Taylor');
44-
$templateProcessor->setValue('userPhone#1', '+1 428 889 773');
45-
46-
$templateProcessor->setValue('userId#2', '2');
47-
$templateProcessor->setValue('userFirstName#2', 'Robert');
48-
$templateProcessor->setValue('userName#2', 'Bell');
49-
$templateProcessor->setValue('userPhone#2', '+1 428 889 774');
50-
51-
$templateProcessor->setValue('userId#3', '3');
52-
$templateProcessor->setValue('userFirstName#3', 'Michael');
53-
$templateProcessor->setValue('userName#3', 'Ray');
54-
$templateProcessor->setValue('userPhone#3', '+1 428 889 775');
39+
$values = array(
40+
array(
41+
'userId' => 1,
42+
'userFirstName' => 'James',
43+
'userName' => 'Taylor',
44+
'userPhone' => '+1 428 889 773',
45+
),
46+
array(
47+
'userId' => 2,
48+
'userFirstName' => 'Robert',
49+
'userName' => 'Bell',
50+
'userPhone' => '+1 428 889 774',
51+
),
52+
array(
53+
'userId' => 3,
54+
'userFirstName' => 'Michael',
55+
'userName' => 'Ray',
56+
'userPhone' => '+1 428 889 775',
57+
),
58+
);
59+
60+
$templateProcessor->cloneRowAndSetValues('userId', $values);
61+
62+
//this is equivalent to cloning and settings values with cloneRowAndSetValues
63+
// $templateProcessor->cloneRow('userId', 3);
64+
65+
// $templateProcessor->setValue('userId#1', '1');
66+
// $templateProcessor->setValue('userFirstName#1', 'James');
67+
// $templateProcessor->setValue('userName#1', 'Taylor');
68+
// $templateProcessor->setValue('userPhone#1', '+1 428 889 773');
69+
70+
// $templateProcessor->setValue('userId#2', '2');
71+
// $templateProcessor->setValue('userFirstName#2', 'Robert');
72+
// $templateProcessor->setValue('userName#2', 'Bell');
73+
// $templateProcessor->setValue('userPhone#2', '+1 428 889 774');
74+
75+
// $templateProcessor->setValue('userId#3', '3');
76+
// $templateProcessor->setValue('userFirstName#3', 'Michael');
77+
// $templateProcessor->setValue('userName#3', 'Ray');
78+
// $templateProcessor->setValue('userPhone#3', '+1 428 889 775');
5579

5680
echo date('H:i:s'), ' Saving the result document...', EOL;
5781
$templateProcessor->saveAs('results/Sample_07_TemplateCloneRow.docx');

‎src/PhpWord/TemplateProcessor.php

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -284,6 +284,18 @@ public function setValue($search, $replace, $limit = self::MAXIMUM_REPLACEMENTS_
284284
$this->tempDocumentFooters = $this->setValueForPart($search, $replace, $this->tempDocumentFooters, $limit);
285285
}
286286

287+
/**
288+
* Set values from a one-dimensional array of "variable => value"-pairs.
289+
*
290+
* @param array $values
291+
*/
292+
public function setValues(array $values)
293+
{
294+
foreach ($values as $macro => $replace) {
295+
$this->setValue($macro, $replace);
296+
}
297+
}
298+
287299
private function getImageArgs($varNameWithArgs)
288300
{
289301
$varElements = explode(':', $varNameWithArgs);
@@ -641,6 +653,24 @@ public function cloneRow($search, $numberOfClones)
641653
$this->tempDocumentMainPart = $result;
642654
}
643655

656+
/**
657+
* Clones a table row and populates it's values from a two-dimensional array in a template document.
658+
*
659+
* @param string $search
660+
* @param array $values
661+
*/
662+
public function cloneRowAndSetValues($search, $values)
663+
{
664+
$this->cloneRow($search, count($values));
665+
666+
foreach ($values as $rowKey => $rowData) {
667+
$rowNumber = $rowKey + 1;
668+
foreach ($rowData as $macro => $replace) {
669+
$this->setValue($macro . '#' . $rowNumber, $replace);
670+
}
671+
}
672+
}
673+
644674
/**
645675
* Clone a block.
646676
*

‎tests/PhpWord/TemplateProcessorTest.php

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,67 @@ public function testCloneRow()
196196
$this->assertTrue($docFound);
197197
}
198198

199+
/**
200+
* @covers ::setValue
201+
* @covers ::cloneRow
202+
* @covers ::saveAs
203+
* @test
204+
*/
205+
public function testCloneRowAndSetValues()
206+
{
207+
$mainPart = '<w:tbl>
208+
<w:tr>
209+
<w:tc>
210+
<w:tcPr>
211+
<w:vMerge w:val="restart"/>
212+
</w:tcPr>
213+
<w:p>
214+
<w:r>
215+
<w:t>${userId}</w:t>
216+
</w:r>
217+
</w:p>
218+
</w:tc>
219+
<w:tc>
220+
<w:p>
221+
<w:r>
222+
<w:t>${userName}</w:t>
223+
</w:r>
224+
</w:p>
225+
</w:tc>
226+
</w:tr>
227+
<w:tr>
228+
<w:tc>
229+
<w:tcPr>
230+
<w:vMerge/>
231+
</w:tcPr>
232+
<w:p/>
233+
</w:tc>
234+
<w:tc>
235+
<w:p>
236+
<w:r>
237+
<w:t>${userLocation}</w:t>
238+
</w:r>
239+
</w:p>
240+
</w:tc>
241+
</w:tr>
242+
</w:tbl>';
243+
$templateProcessor = new TestableTemplateProcesor($mainPart);
244+
245+
$this->assertEquals(
246+
array('userId', 'userName', 'userLocation'),
247+
$templateProcessor->getVariables()
248+
);
249+
250+
$values = array(
251+
array('userId' => 1, 'userName' => 'Batman', 'userLocation' => 'Gotham City'),
252+
array('userId' => 2, 'userName' => 'Superman', 'userLocation' => 'Metropolis'),
253+
);
254+
$templateProcessor->setValue('tableHeader', 'My clonable table');
255+
$templateProcessor->cloneRowAndSetValues('userId', $values);
256+
$this->assertContains('<w:t>Superman</w:t>', $templateProcessor->getMainPart());
257+
$this->assertContains('<w:t>Metropolis</w:t>', $templateProcessor->getMainPart());
258+
}
259+
199260
/**
200261
* @expectedException \Exception
201262
* @test
@@ -246,6 +307,25 @@ public function testSetValue()
246307
);
247308
}
248309

310+
/**
311+
* @covers ::setValues
312+
* @test
313+
*/
314+
public function testSetValues()
315+
{
316+
$mainPart = '<?xml version="1.0" encoding="UTF-8"?>
317+
<w:p>
318+
<w:r>
319+
<w:t xml:space="preserve">Hello ${firstname} ${lastname}</w:t>
320+
</w:r>
321+
</w:p>';
322+
323+
$templateProcessor = new TestableTemplateProcesor($mainPart);
324+
$templateProcessor->setValues(array('firstname' => 'John', 'lastname' => 'Doe'));
325+
326+
$this->assertContains('Hello John Doe', $templateProcessor->getMainPart());
327+
}
328+
249329
/**
250330
* @covers ::setImageValue
251331
* @test

0 commit comments

Comments
 (0)