Practical phpdocx

Blocks

Introduction

Blocks let you group elements and easily clone, replace and delete them. They can be created with MS Word or any other DOCX editor, even with the available methods of the phpdocx API.

Blocks can contain texts, images, placeholders to be replaced with phpdocx, sub-blocks and almost any other content.

Defining elements of the block type

To define blocks in a DOCX, create two placeholders with the same name, at the beginning and the end of the block content, with the following syntaxis:

$BLOCK_*$

Replace * with the block name, e.g:

$BLOCK_A1$

When invoking block methods it is mandatory to specify the block name without neither prefix ($BLOCK by default) nor suffix. So, to delete the A1 block execute:

$docx->deleteBlock('A1');

Replace values

Existing placeholders in a block can be replaced with phpdocx template methods with no need of indicating block names. E.g., if a block has the $VAR1$ placeholder, it is possible to replace it with replaceVariableByText:

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

$variables = array('VAR1' => 'New text');
$docx->replaceVariableByText($variables);

Remove, replace and clean

The deleteBlock method deletes the whole content of a block. With this functionality it is possible to define optional blocks that can be deleted if they are unnecessary:

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

$docx->deleteBlock('A1');

By default, deleteBlock removes the block contents including paragraphs. Inline block contents can be removed setting the type option as inline:

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

$docx->deleteBlock('A1', 'inline');

replaceBlock replaces a block content with a new string or WordFragment content. E.g., to replace a block with a string and another block with a WordFragment:

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

// replace the block with a string
$docx->replaceBlock('A1', 'New content');

// replace the block with a WordFragment
$wordFragmentContent = new WordFragment($docx);
$wordFragmentContent->addText('New content', array('bold' => true));

$docx->replaceBlock('A2', $wordFragmentContent);

clearBlocks removes just the blocks placeholders while keeping their content. E.g., to replace contents and then clean the placeholders that wrap the blocks:

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

$variables = array('VAR1' => 'New text');
$docx->replaceVariableByText($variables);

$docx->clearBlocks();

Clone

Available for Advanced and Premium licenses, cloneBlock allows to clone a block just by stating its name:

$docx->cloneBlock('A1');

When cloning blocks, all contents are copied. If the cloned blocks include placeholders, the same method can replace them:

// each array sets a new clone of the block
$variables = array(
    array(
        'VAR_MEMBER' => 'John Doe',
        'VAR_CONTENT' => 'New content',
        'VAR_DATE' => '11/08/2021',
    ),
    array(
        'VAR_MEMBER' => 'Jane Doe',
        'VAR_CONTENT' => 'Other content',
        'VAR_DATE' => '21/08/2021',
    ),
);

// clone block setting the variables to be replaced
$docx->cloneBlock('FIRST', 1, $variables, array('removeBlockPlaceholder' => true));

The firstMatch option (available in almost all template methods) can also be used to iterate the placeholders to be replaced by new values:

$variables = array('VAR' => 'First value');
// the first occurrence is replaced with the new value
$docx->replaceVariableByText($variables, array('firstMatch' => true));

$variables = array('VAR' => 'Second value');
// the next occurrence that now is the first occurrence is replaced with the new value
$docx->replaceVariableByText($variables, array('firstMatch' => true));

On Clone blocks replacing placeholders there are samples to illustrate replacing placeholders when cloning blocks.

Tips and Tricks

The Cookbook offers several articles about blocks.

You can customize blocks prefixes and the characters to wrap them with setTemplateBlockSymbol and setTemplateSymbol methods.

DOCXPath lets you perform more complex replacements, such as substituting placeholders by name or its position in the block that contains them.

cloneBlock and clearBlocks methods require placeholders to be added in their own paragraphs.

Next - Document transformations