Practical phpdocx

WordFragments and WordML

Introduction

One of the most exceptional and versatile features of phpdocx 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:

require_once 'classes/CreateDocx.php';

Create a new document:

$docx = new CreateDocx();

Then, you can add a WordFragment element:

$text = new WordFragment($docx);

As seen in the constructor:

public function __construct($docx = NULL, $target = 'document')

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 ('footnote'), endnotes ('endnote') or comments ('comment').

The $target parameter is only required when the WordFragment to be added includes a external relationship such as an image, a link or a chart.

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:

$image = new WordFragment($docx);

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

$imageOptions = array(
    'src' => 'image.png',
    'scaling' => 50,
    'float' => 'right',
    'textWrap' => 1
    );
$image->addImage($imageOptions);

Use the same method to add a new link:

$link = new WordFragment($docx);
$linkOptions = array('url'=> 'http://www.google.es',
    'color' => '0000FF',
    'underline' => 'single');
$link->addLink('link to Google', $linkOptions);

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

$text = array();
$text[] = $image;
$text[] = $link;

Add it to the document:

$docx->addText($text);

Finally, generate the document:

$docx->createDocx('tutorial_4');

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

A WordFragment may have one or more contents, e.g., a text, an image and a table:

$wordFragment = new WordFragment($docx);

$wordFragment->addText('Text content');

$imageOptions = array('src' => 'image.png');
$wordFragment->addImage($imageOptions);

$valuesTable = array(
    array(11, 12, 13, 14),
    array(21, 22, 23, 24),
    array(31, 32, 33, 34),
);

$paramsTable = array('border' => 'single', 'tableAlign' => 'center');

$wordFragment->addTable($valuesTable, $paramsTable);

Working with templates

The method replaceVariableByWordFragment

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

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 add. For example, to replace a placeholder with a picture and a link. After loading the template:

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

Create a new WordFragment variable:

$wordFragment = new WordFragment($docx, 'document');

The available WordFragment targets to be used with replaceVariableByWordFragment are the following: body of the document ('document'), headers ('header'), footers ('footer'), footnotes ('footnote'), endnotes ('endnote') and comments ('comment'). Specific header and footer targets such as defaultHeader or firstFooter aren't used with replaceVariableByWordFragment.

Create the elements to replace the placeholder with:

$image = new WordFragment($docx);
$imageOptions = array(
    'src' => 'image.png',
    'scaling' => 50,
    'float' => 'right',
    'textWrap' => 1
    );
$image->addImage($imageOptions);

$link = new WordFragment($docx);
$linkOptions = array('url'=> 'http://www.google.es',
    'color' => '0000FF',
    'underline' => 'single');
$link->addLink('link to Google', $linkOptions);

$text = array();
$text[] = $image;
$text[] = $link;

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

$wordFragment->addText($text);

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

$docx->replaceVariableByWordFragment(array('VAR' => $wordFragment), array('type' => 'block'));

Including WordML code

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

public function addWordML($wordML)

For example, for adding a paragraph:

$wordML = '
    <w:p>
        <w:r><w:t>A very simple paragraph with only text.</w:t></w:r>
    </w:p>';

$docx->addWordML($wordML);

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

$docx->replaceVariableByWordML(array('WORDML' => $wordML));

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.

Premium licenses also includes the inline-block replacement type in replaceVariableByWordFragment.

Next - Adding content to a document