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:

Now, let's replace the contents of this $docx object. The order of replacement is not relevant.

Texts

The easiest element for replacing a placeholder is a string. This is the method to do it:

You have to set one or more value arrays here to replace them. Use a second array with the following keys

  • ‘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 for a text with a line break:

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 this method:

Where the parameters are, in order:

  • $variable: name of the placeholder of the template
  • $listValues: array with the values to add
  • $options: with the ‘firstMatch’ options, replaces only the first occurrence if it’s true
  • ‘parseLineBreaks’: replaces the characters ‘\n’ with line breaks

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

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 method used is:

Where the parameters are, in order:

  • $vars: multidimensional array with the table placeholders and its values. For each position of the array, a new line is created in the table.
  • $options: with the ‘firstMatch’ options, replaces only the first occurrence if it's true.
  • ‘parseLineBreaks’: replaces the characters ‘\n’ with line breaks.
Deleting placeholders

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

The available options are:

  • $variableName: name of the placeholder to erase
  • $type: block delete type. It also removes the container or inline paragraph
  • $target: to define the area of the placeholder as document, header, footer...

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

And, for deleting the placeholder OTHERVAR in the document:

Besides the methods mentioned above, there are many other ways that will be reviewed later on.

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.

This even works if it's a document-type, header or footer, and allows to know if it has a concrete prefix on its name.

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.

The method sends back an array with the classified variables by document type, header and footer.

Next - Headers and Footers