improve template processor documentation

docs/conf.py

@@ -48,7 +48,7 @@ copyright = u'2014-2017, PHPWord Contributors'
 # built documents.
 #
 # The short X.Y version.
-version = '0.14.0'
+version = '0.16.0'
 # The full version, including alpha/beta/rc tags.
 release = version
 

docs/containers.rst

@@ -107,8 +107,8 @@ You can pass an optional parameter to specify where the header/footer should be
 To change the evenAndOddHeaders use the ``getSettings`` method to return the Settings object, and then call the ``setEvenAndOddHeaders`` method:
 
 .. code-block:: php
-    $phpWord->getSettings()->setEvenAndOddHeaders(true);
 
+    $phpWord->getSettings()->setEvenAndOddHeaders(true);
 
 Footers
 -------

docs/templates-processing.rst

@@ -4,22 +4,43 @@ Templates processing
 ====================
 
 You can create an OOXML document template with included search-patterns (macros) which can be replaced by any value you wish. Only single-line values can be replaced.
+Macros are defined like this: ``${search-pattern}``.
+To load a template file, create a new instance of the TemplateProcessor.
 
-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}``.
+.. code-block:: php
 
+    $templateProcessor = new TemplateProcessor('Template.docx');
+
+setValue
+""""""""
+Given a template containing
+
+.. code-block:: clean
+
+    Hello ${name}!
+
+The following will replace ``${name}`` with ``World``. The resulting document will now contain ``Hello World!``
+
+.. code-block:: php
+
+    $templateProcessor->setValue('name', 'World');
+
+setImageValue
+"""""""""""""
 The search-pattern model for images can be like:
     - ``${search-image-pattern}``
     - ``${search-image-pattern:[width]:[height]:[ratio]}``
     - ``${search-image-pattern:[width]x[height]}``
     - ``${search-image-pattern:size=[width]x[height]}``
     - ``${search-image-pattern:width=[width]:height=[height]:ratio=false}``
+
 Where:
-- [width] and [height] can be just numbers or numbers with measure, which supported by Word (cm|mm|in|pt|pc|px|%|em|ex)
+    - [width] and [height] can be just numbers or numbers with measure, which supported by Word (cm, mm, in, pt, pc, px, %, em, ex)
     - [ratio] uses only for ``false``, ``-`` or ``f`` to turn off respect aspect ration of image. By default template image size uses as 'container' size.
 
 Example:
 
-.. code-block:: doc
+.. code-block:: clean
 
     ${CompanyLogo}
     ${UserLogo:50:50} ${Name} - ${City} - ${Street}
@@ -33,11 +54,97 @@ Example:
     $templateProcessor->setImageValue('CompanyLogo', 'path/to/company/logo.png');
     $templateProcessor->setImageValue('UserLogo', array('path' => 'path/to/logo.png', 'width' => 100, 'height' => 100, 'ratio' => false));
 
-It is not possible to directly add new OOXML elements to the template file being processed, but it is possible to transform headers, main document part, and footers of the template using XSLT (see ``TemplateProcessor::applyXslStyleSheet``).
+cloneBlock
+""""""""""
+Given a template containing
+See ``Sample_23_TemplateBlock.php`` for an example.
 
-See ``Sample_07_TemplateCloneRow.php`` for example on how to create
-multirow from a single row in a template by using ``TemplateProcessor::cloneRow``.
+.. code-block:: clean
 
-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``.
+    ${block_name}
+    Customer: ${customer_name}
+    Address: ${customer_address}
+    ${/block_name}
+
+The following will duplicate everything between ``${block_name}`` and ``${/block_name}`` 3 times.
+
+.. code-block:: php
+
+    $templateProcessor->cloneBlock('block_name', 3, true, true);
+
+The last parameter will rename any macro defined inside the block and add #1, #2, #3 ... to the macro name.
+The result will be
+
+.. code-block:: clean
+
+    Customer: ${customer_name#1}
+    Address: ${customer_address#1}
+    Customer: ${customer_name#2}
+    Address: ${customer_address#2}
+    Customer: ${customer_name#3}
+    Address: ${customer_address#3}
+
+replaceBlock
+""""""""""""
+Given a template containing
+
+.. code-block:: clean
+
+    ${block_name}
+    This block content will be replaced
+    ${/block_name}
+
+The following will replace everything between``${block_name}`` and ``${/block_name}`` with the value passed.
+
+.. code-block:: php
+
+    $templateProcessor->replaceBlock('block_name', 'This is the replacement text.');
+
+deleteBlock
+"""""""""""
+Same as previous, but it deletes the block
+
+.. code-block:: php
+
+    $templateProcessor->deleteBlock('block_name');
+
+cloneRow
+""""""""
+Clones a table row in a template document.
+See ``Sample_07_TemplateCloneRow.php`` for an example.
+
+.. code-block:: clean
+
+    ------------------------------
+    | ${userId} | ${userName}    |
+    |           |----------------|
+    |           | ${userAddress} |
+    ------------------------------
+
+.. code-block:: php
+
+    $templateProcessor->cloneRow('userId', 2);
+
+Will result in
+
+.. code-block:: clean
+
+    ----------------------------------
+    | ${userId#1} | ${userName#1}    |
+    |             |------------------|
+    |             | ${userAddress#1} |
+    ---------------------------------|
+    | ${userId#2} | ${userName#2}    |
+    |             |------------------|
+    |             | ${userAddress#2} |
+    ----------------------------------
+
+applyXslStyleSheet
+""""""""""""""""""
+Applies the XSL stylesheet passed to header part, footer part and main part
+
+.. code-block:: php
+
+    $xslDomDocument = new \DOMDocument();
+    $xslDomDocument->load('/path/to/my/stylesheet.xsl');
+    $templateProcessor->applyXslStyleSheet($xslDomDocument);