Practical phpdocx

WordFragments and WordML


One of the most exceptional and versatile features of phpdocx 4 is the possibility of working with WordML fragments. The WordFragment class makes the insertion of new contents in documents and the replacement of variables in templates flexible. It combines the functionalities included in the library with the versatility of the almost direct work of WordML, that is, the XML format used to create DOCX documents. The correct use of WordFragment is essential to add headers, footers, and nested contents in the documents.

Instantiating the WordFragment class

To use WordFragment, you have to instantiate the WordFragment class, with the CreateDocx class as the main document.

Thanks to the Autoloader class in the library, it is not necessary to include additional classes to use WordFragment.

After including the main class of CreateDocx:

Create a new document:

Then, you can add a WordFragment element:

As seen in the constructor:

To run the WordFragment class, apply a mandatory parameter, which is the instance of the document, and a second optional parameter with the scope of the document. This second parameter can be the body of the document (‘document’), the default header (‘defaultHeader’) or just the first one (‘firstHeader’), the footer (‘defaultFooter’) and other elements like footnotes, endnotes or comments.

It is mandatory to instance a new WordFragment object for every element you add.

Adding elements

The methods for adding the contents are the same available in CreateDocx, including its parameters and available options.

For example, to add a picture, first instance the class WordFragment:

Then, define the picture the same way as if you were working with the CreateDocx class:

Use the same method to add a new link:

Add these WordFragment methods to the new document, for example through an array:

Add it to the document, as if you were working directly with CreateDocx.

Finally, generate the document:

As well as adding pictures and links, you can include graphic charts, endnotes, page brakes, bookmarks… In other words, most part of the available contents in the CreateDocx class.

Working with templates

The method

allows to use WordFragments with templates.

To work with templates you have to use an additional variable, again of the WordFragment class, which saves the elements to replace. For example, to replace the picture and the link created before. After loading the template:

create a new WordFragment variable:

create the elements to replace the placeholder with:

Instead of using the object in which the document has been instanced, add the content by calling the WordFragment-type variable:

Finally, for example: replace the variable VAR in the document:

Including WordML code

To work at a lower level than with WordFragment, add directly the WordML code:

For example, for adding a paragraph:

Or, if you need to replace a variable in a template for a WordML code:

Tricks and tips

Inline and block content: When replacing WordFragment elements in templates, you may need to add the inline contents with the replaced variable, or replace the container paragraph completely.

To choose one or another, it is just necessary to use the ‘type’ option of the second parameter of the method replaceVariableByWordFragment. This parameter can have two values: inline or block.

Next - Adding content to a document