Practical phpdocx

Adding content to a template

Introduction

To show how the library works with templates, let's modify a template and replace some variables for text, lists, tables and other contents.

Loading the template

First, create the new document instancing the class CreateDocxFromTemplate:

require_once 'classes/CreateDocx.php';

$docx = new CreateDocxFromTemplate('template.docx');

Now, let's replace the contents of this $docx object.

Texts

The easiest element for replacing a placeholder is a string. replaceVariableByText is the method to be used:

public function replaceVariableByText($variables, $options = array())

You have to set one or more value arrays here to replace them. A second parameter is available with the following options

'target': Where the variables for replacement are: document, header, footer...
'firstMatch': Replaces the first occurrence only if it's true
'parseLineBreaks': Replaces all characters ‘\n’ with line breaks

For example, replace the TEXT placeholder by a text with a line break:

$text = 'A web browser (commonly referred to as a browser) is a software application for retrieving, presenting and traversing information resources on the World Wide Web.\n
An information resource is identified by a Uniform Resource Identifier (URI/URL) and may be a web page, image, video or other piece of content.';

$docx->replaceVariableByText(array('TEXT' => $text), array('parseLineBreaks' => true));

Lists

Replacing lists is as simple as adding a list with a single element in the template which contains the placeholder. When adding the new values, lists elements remain intact.

To add values to the list, use the replaceListVariable method:

public function replaceListVariable($variable, $listValues, $options = array())

Where the available parameters are, in order:

$variable: Name of the placeholder of the template
$listValues: Array with the values to add
$options: With the 'firstMatch' option replaces only the first occurrence if it's true, 'parseLineBreaks' replaces the characters '\n' with line breaks, 'target' set the placeholder target.

For example, switch the placeholder LIST in a web browser list:

$items = array('Google Chrome', 'Mozilla Firefox', 'Internet Explorer');

$docx->replaceListVariable('LIST', $items);

Tables

Just like with the lists, you can add tables to the template by making a table with the styles that you want and define a row with the variables to replace. This row will be replaced for as many rows as needed with new values, keeping the original table styles.

The signature of the replaceTableVariable method is:

public function replaceTableVariable($vars, $options = array())

Where the parameters are, in order:

$vars: Multidimensional array with the table placeholders and its values. For each position of the array, a new row is created in the table.
$options: With the 'firstMatch' option replaces only the first occurrence if it's true, 'parseLineBreaks' replaces the characters '\n' with line breaks, 'target' set the placeholder target.

$data_table = array(
array(
        'MONTH' => 'September',
        'PERCENT_CHROME' => '59.1%',
        'PERCENT_FIREFOX' => '24.0%',
        'PERCENT_IE' => '9.9%',
    ),
array(
        'MONTH' => 'August',
        'PERCENT_CHROME' => '60.1%',
        'PERCENT_FIREFOX' => '24.7%%',
        'PERCENT_IE' => '8.3%',
    ),
array(
        'MONTH' => 'July',
        'PERCENT_CHROME' => '59.8%',
        'PERCENT_FIREFOX' => '24.9%',
        'PERCENT_IE' => '8.5%',
    ),
array(
        'MONTH' => 'Average',
        'PERCENT_CHROME' => '- %',
        'PERCENT_FIREFOX' => '- %',
        'PERCENT_IE' => '- %',
),
);
$docx->replaceTableVariable($data_table);

Deleting placeholders

Sometimes there's no need to replace every placeholder, and some of them remain in the template. To erase them, call removeTemplateVariable:

    public function removeTemplateVariable($variableName, $type = 'block', $target = 'document')

The available options are:

$variableName: Name of the placeholder to erase
$type: Delete type. It also removes or not the container paragraph
$target: To define the target of the placeholder as document, header, footer...

For example, to delete the placeholder FOOTERVAR in the footer code this method:

$docx->removeTemplateVariable('FOOTERVAR', 'block', 'footer');

And, for deleting the placeholder OTHERVAR in the document:

$docx->removeTemplateVariable('OTHERVAR', 'inline');

Tips and Tricks

How to retrieve variables with the getTemplateVariables: at any time you can know which placeholder hasn't been replaced with the getTemplateVariables method. The method sends back an array with the variables by document, header, footer, footnote, endnote or comment targets.

Working with prefixes allows to carry an extensive control of every placeholder, divided by groups of work, and even permits to classify them by substitution priority. This makes easier its further replacement and deletion.

Template methods replace placeholders in the main document body. To replace placeholders in other scopes such as header, footer, comment or footnote, the target option is available.

Other methods are available to work with templates. They are detailed on the API documentation pages.

Next - Headers and Footers