Skip to content

Commit ec25dd3

Browse files
author
Roman Syroeshko
committed
https://github.com/PHPOffice/PHPWord/issues/216
1 parent 8d9e85b commit ec25dd3

13 files changed

+623
-599
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ This release added form fields (textinput, checkbox, and dropdown), drawing shap
3939
- `Element\Section::getSettings()` and `Element\Section::setSettings()` replaced by `Element\Section::getStyle()` and `Element\Section::setStyle()`
4040
- `Shared\Drawing` and `Shared\Font` merged into `Shared\Converter`
4141
- `DocumentProperties` replaced by `Metadata\DocInfo`
42+
- `Template` replaced by `TemplateProcessor`
43+
- `PhpWord->loadTemplate($filename)`
4244

4345
### Miscellaneous
4446

@@ -49,6 +51,7 @@ This release added form fields (textinput, checkbox, and dropdown), drawing shap
4951
- Element: Refactor elements to move set relation Id from container to element - @ivanlanin
5052
- Introduced CreateTemporaryFileException, CopyFileException - @RomanSyroeshko
5153
- Settings: added method to set user defined temporary directory - @RomanSyroeshko GH-310
54+
- Renamed `Template` into `TemplateProcessor` - @RomanSyroeshko GH-216
5255

5356
## 0.11.1 - 2 June 2014
5457

‎composer.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "phpoffice/phpword",
33
"description": "PHPWord - A pure PHP library for reading and writing word processing documents (DOCX, ODT, RTF, HTML, PDF)",
44
"keywords": [
5-
"PHP", "PhpOffice", "office", "PhpWord", "word", "template", "reader", "writer",
5+
"PHP", "PhpOffice", "office", "PhpWord", "word", "template", "template processor", "reader", "writer",
66
"docx", "OOXML", "OpenXML", "Office Open XML", "ISO IEC 29500", "WordprocessingML",
77
"RTF", "Rich Text Format", "doc", "odt", "OpenDocument", "PDF", "HTML"
88
],
@@ -50,7 +50,7 @@
5050
"ext-zip": "Used to write DOCX and ODT",
5151
"ext-gd2": "Used to add images",
5252
"ext-xmlwriter": "Used to write DOCX and ODT",
53-
"ext-xsl": "Used to apply XSL style sheet to template part",
53+
"ext-xsl": "Used to apply XSL style sheet to main document part of OOXML template",
5454
"dompdf/dompdf": "Used to write PDF"
5555
},
5656
"autoload": {

‎docs/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Format (RTF).
2323
containers
2424
elements
2525
styles
26-
templates
26+
templates-processing
2727
writersreaders
2828
recipes
2929
faq

‎docs/src/documentation.md

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Don't forget to change `code::` directive to `code-block::` in the resulting rst
4444
- [Font](#font)
4545
- [Paragraph](#paragraph)
4646
- [Table](#table)
47-
- [Templates](#templates)
47+
- [Templates processing](#templates-processing)
4848
- [Writers & readers](#writers-readers)
4949
- [OOXML](#ooxml)
5050
- [OpenDocument](#opendocument)
@@ -873,21 +873,25 @@ Available image styles:
873873
- `font` Font name
874874
- `hint` See font style
875875

876-
# Templates
876+
# Templates processing
877877

878-
You can create a docx template with included search-patterns that can be replaced by any value you wish. Only single-line values can be replaced. To load a template file, use the `loadTemplate` method. After loading the docx template, you can use the `setValue` method to change the value of a search pattern. The search-pattern model is: `${search-pattern}`. It is not possible to add new PHPWord elements to a loaded template file.
878+
You can create a .docx document template with included search-patterns which can be replaced by any value you wish. Only single-line values can be replaced.
879+
880+
To deal with a template file, use `new TemplateProcessor` statement. After TemplateProcessor instance creation the document template is copied into the temporary directory. Then you can use `TemplateProcessor::setValue` method to change the value of a search pattern. The search-pattern model is: `${search-pattern}`.
879881

880882
Example:
881883

882884
```php
883-
$template = $phpWord->loadTemplate('Template.docx');
884-
$template->setValue('Name', 'Somebody someone');
885-
$template->setValue('Street', 'Coming-Undone-Street 32');
885+
$templateProcessor = new TemplateProcessor('Template.docx');
886+
$templateProcessor->setValue('Name', 'Somebody someone');
887+
$templateProcessor->setValue('Street', 'Coming-Undone-Street 32');
886888
```
887889

888-
See `Sample_07_TemplateCloneRow.php` for example on how to create multirow from a single row in a template by using `cloneRow`.
890+
It is not possible to directly add new OOXML elements to the template file being processed, but it is possible to transform main document part of the template using XSLT (see `TemplateProcessor::applyXslStyleSheet`).
891+
892+
See `Sample_07_TemplateCloneRow.php` for example on how to create multirow from a single row in a template by using `TemplateProcessor::cloneRow`.
889893

890-
See `Sample_23_TemplateBlock.php` for example on how to clone a block of text using `cloneBlock` and delete a block of text using `deleteBlock`.
894+
See `Sample_23_TemplateBlock.php` for example on how to clone a block of text using `TemplateProcessor::cloneBlock` and delete a block of text using `TemplateProcessor::deleteBlock`.
891895

892896
# Writers & readers
893897

‎docs/templates-processing.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. _templates-processing:
2+
3+
Templates processing
4+
====================
5+
6+
You can create a .docx document template with included search-patterns which can be replaced by any value you wish. Only single-line values can be replaced.
7+
8+
To deal with a template file, use ``new TemplateProcessor`` statement. After TemplateProcessor instance creation the document template is copied into the temporary directory. Then you can use ``TemplateProcessor::setValue`` method to change the value of a search pattern. The search-pattern model is: ``${search-pattern}``.
9+
10+
Example:
11+
12+
.. code-block:: php
13+
14+
$templateProcessor = new TemplateProcessor('Template.docx');
15+
$templateProcessor->setValue('Name', 'Somebody someone');
16+
$templateProcessor->setValue('Street', 'Coming-Undone-Street 32');
17+
18+
It is not possible to directly add new OOXML elements to the template file being processed, but it is possible to transform main document part of the template using XSLT (see ``TemplateProcessor::applyXslStyleSheet``).
19+
20+
See ``Sample_07_TemplateCloneRow.php`` for example on how to create
21+
multirow from a single row in a template by using ``TemplateProcessor::cloneRow``.
22+
23+
See ``Sample_23_TemplateBlock.php`` for example on how to clone a block
24+
of text using ``TemplateProcessor::cloneBlock`` and delete a block of text using
25+
``TemplateProcessor::deleteBlock``.

‎docs/templates.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎samples/Sample_07_TemplateCloneRow.php

Lines changed: 44 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,60 @@
11
<?php
22
include_once 'Sample_Header.php';
33

4-
// New Word document
5-
echo date('H:i:s') , " Create new PhpWord object" , EOL;
6-
$phpWord = new \PhpOffice\PhpWord\PhpWord();
7-
8-
$document = $phpWord->loadTemplate('resources/Sample_07_TemplateCloneRow.docx');
4+
// Template processor instance creation
5+
echo date('H:i:s') , ' Creating new TemplateProcessor instance...' , EOL;
6+
$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor('resources/Sample_07_TemplateCloneRow.docx');
97

108
// Variables on different parts of document
11-
$document->setValue('weekday', date('l')); // On section/content
12-
$document->setValue('time', date('H:i')); // On footer
13-
$document->setValue('serverName', realpath(__DIR__)); // On header
9+
$templateProcessor->setValue('weekday', date('l')); // On section/content
10+
$templateProcessor->setValue('time', date('H:i')); // On footer
11+
$templateProcessor->setValue('serverName', realpath(__DIR__)); // On header
1412

1513
// Simple table
16-
$document->cloneRow('rowValue', 10);
17-
18-
$document->setValue('rowValue#1', 'Sun');
19-
$document->setValue('rowValue#2', 'Mercury');
20-
$document->setValue('rowValue#3', 'Venus');
21-
$document->setValue('rowValue#4', 'Earth');
22-
$document->setValue('rowValue#5', 'Mars');
23-
$document->setValue('rowValue#6', 'Jupiter');
24-
$document->setValue('rowValue#7', 'Saturn');
25-
$document->setValue('rowValue#8', 'Uranus');
26-
$document->setValue('rowValue#9', 'Neptun');
27-
$document->setValue('rowValue#10', 'Pluto');
28-
29-
$document->setValue('rowNumber#1', '1');
30-
$document->setValue('rowNumber#2', '2');
31-
$document->setValue('rowNumber#3', '3');
32-
$document->setValue('rowNumber#4', '4');
33-
$document->setValue('rowNumber#5', '5');
34-
$document->setValue('rowNumber#6', '6');
35-
$document->setValue('rowNumber#7', '7');
36-
$document->setValue('rowNumber#8', '8');
37-
$document->setValue('rowNumber#9', '9');
38-
$document->setValue('rowNumber#10', '10');
14+
$templateProcessor->cloneRow('rowValue', 10);
15+
16+
$templateProcessor->setValue('rowValue#1', 'Sun');
17+
$templateProcessor->setValue('rowValue#2', 'Mercury');
18+
$templateProcessor->setValue('rowValue#3', 'Venus');
19+
$templateProcessor->setValue('rowValue#4', 'Earth');
20+
$templateProcessor->setValue('rowValue#5', 'Mars');
21+
$templateProcessor->setValue('rowValue#6', 'Jupiter');
22+
$templateProcessor->setValue('rowValue#7', 'Saturn');
23+
$templateProcessor->setValue('rowValue#8', 'Uranus');
24+
$templateProcessor->setValue('rowValue#9', 'Neptun');
25+
$templateProcessor->setValue('rowValue#10', 'Pluto');
26+
27+
$templateProcessor->setValue('rowNumber#1', '1');
28+
$templateProcessor->setValue('rowNumber#2', '2');
29+
$templateProcessor->setValue('rowNumber#3', '3');
30+
$templateProcessor->setValue('rowNumber#4', '4');
31+
$templateProcessor->setValue('rowNumber#5', '5');
32+
$templateProcessor->setValue('rowNumber#6', '6');
33+
$templateProcessor->setValue('rowNumber#7', '7');
34+
$templateProcessor->setValue('rowNumber#8', '8');
35+
$templateProcessor->setValue('rowNumber#9', '9');
36+
$templateProcessor->setValue('rowNumber#10', '10');
3937

4038
// Table with a spanned cell
41-
$document->cloneRow('userId', 3);
39+
$templateProcessor->cloneRow('userId', 3);
4240

43-
$document->setValue('userId#1', '1');
44-
$document->setValue('userFirstName#1', 'James');
45-
$document->setValue('userName#1', 'Taylor');
46-
$document->setValue('userPhone#1', '+1 428 889 773');
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');
4745

48-
$document->setValue('userId#2', '2');
49-
$document->setValue('userFirstName#2', 'Robert');
50-
$document->setValue('userName#2', 'Bell');
51-
$document->setValue('userPhone#2', '+1 428 889 774');
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');
5250

53-
$document->setValue('userId#3', '3');
54-
$document->setValue('userFirstName#3', 'Michael');
55-
$document->setValue('userName#3', 'Ray');
56-
$document->setValue('userPhone#3', '+1 428 889 775');
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');
5755

58-
$name = 'Sample_07_TemplateCloneRow.docx';
59-
echo date('H:i:s'), " Write to Word2007 format", EOL;
60-
$document->saveAs($name);
61-
rename($name, "results/{$name}");
56+
echo date('H:i:s'), ' Saving the result document...', EOL;
57+
$templateProcessor->saveAs('results/Sample_07_TemplateCloneRow.docx');
6258

6359
echo getEndingNotes(array('Word2007' => 'docx'));
6460
if (!CLI) {

‎samples/Sample_23_TemplateBlock.php

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,18 @@
11
<?php
22
include_once 'Sample_Header.php';
33

4-
// New Word document
5-
echo date('H:i:s') , " Create new PhpWord object" , EOL;
6-
$phpWord = new \PhpOffice\PhpWord\PhpWord();
7-
8-
$document = $phpWord->loadTemplate('resources/Sample_23_TemplateBlock.docx');
4+
// Template processor instance creation
5+
echo date('H:i:s') , ' Creating new TemplateProcessor instance...' , EOL;
6+
$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor('resources/Sample_23_TemplateBlock.docx');
97

108
// Will clone everything between ${tag} and ${/tag}, the number of times. By default, 1.
11-
$document->cloneBlock('CLONEME', 3);
9+
$templateProcessor->cloneBlock('CLONEME', 3);
1210

1311
// Everything between ${tag} and ${/tag}, will be deleted/erased.
14-
$document->deleteBlock('DELETEME');
12+
$templateProcessor->deleteBlock('DELETEME');
1513

16-
$name = 'Sample_23_TemplateBlock.docx';
17-
echo date('H:i:s'), " Write to Word2007 format", EOL;
18-
$document->saveAs($name);
19-
rename($name, "results/{$name}");
14+
echo date('H:i:s'), ' Saving the result document...', EOL;
15+
$templateProcessor->saveAs('results/Sample_23_TemplateBlock.docx');
2016

2117
echo getEndingNotes(array('Word2007' => 'docx'));
2218
if (!CLI) {

‎src/PhpWord/PhpWord.php

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -264,14 +264,16 @@ public function setDefaultParagraphStyle($styles)
264264
/**
265265
* Load template by filename
266266
*
267+
* @deprecated 0.12.0 Use `new TemplateProcessor($documentTemplate)` instead.
268+
*
267269
* @param string $filename Fully qualified filename.
268-
* @return Template
270+
* @return TemplateProcessor
269271
* @throws \PhpOffice\PhpWord\Exception\Exception
270272
*/
271273
public function loadTemplate($filename)
272274
{
273275
if (file_exists($filename)) {
274-
return new Template($filename);
276+
return new TemplateProcessor($filename);
275277
} else {
276278
throw new Exception("Template file {$filename} not found.");
277279
}

0 commit comments

Comments
 (0)