replaceVariableByWordFragment

WORD CONTENTS

LAYOUT & SETTINGS

TEMPLATES

FORMAT CONVERSION

DOCXPATH

DOCXUTILITIES

DOCXPATHUTILITIES

PDFUTILITIES

DOCXCUSTOMIZER

customizeWordContent

PERFORMANCE

BULK PROCESSING

TRACKING

CRYPTOPHPDOCX

DIGITAL SIGNATURE

ARTIFICIAL INTELLIGENCE

XLSXUTILITIES

PPTXUTILITIES

BLOCKCHAIN

VARIANT

replaceVariableByWordFragment

TRIAL / ADVANCED / PREMIUM

Replaces placeholder variables by fragments of Word.

Description

public replaceVariableByWordFragment (array $variables[, array $options])

This powerful method allows the substitution of placeholder variables by Word fragments that may include:

formatted text
tables
images
charts
footnotes
...

The Word fragments should be instances of the WordFragment class.

The available WordFragment targets to be used with this method 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.

Parameters

variables

This must be an array with the names of the placeholder template variables as keys and the WordFragment instances that should replace them as values.

options

The possible keys and values of this array are:

Key	Type	Description
firstMatch	boolean	If the variable appears more than once within the Word document and firstMatch is set to true, phpdocx will only replace the first occurrence of the variable within the Word document.
stylesReplacementType	string	Empty as default. usePlaceholderStyles: keeps placeholder styles, styles from the imported WordFragment are ignored. Applies to the following styles: pPr, rPr. mixPlaceholderStyles: mixes placeholder styles, placeholder styles overwrite WordFragment styles with the same name. Applies to the following styles: pPr, rPr. Only available in Premium licenses.
stylesReplacementTypeIgnore	array	Styles to be ignored from the imported WordFragment. Use with mixPlaceholderStyles. Empty as default. Only available in Premium licenses.
stylesReplacementTypeOverwrite	bool	If true, WordFragment styles overwrite placeholder styles with the same name that are not set in the stylesReplacementTypeIgnore option. Use with mixPlaceholderStyles. Default as false. Only available in Premium licenses.
target	string	Possible values are: document (default), header, footer, footnote, endnote, comment. This option sets the scope of the replacement procedure.
type	string	Possible values are: block (default): replaces the variable and removes its containing paragraph. inline: only replaces the variable by the WordFragment inline content (it may be used to replace a variable by formatted text). inline-block: replaces the variable keeping inline and block elements. Only available in Premium licenses.

Exceptions

Not using WordFragments.

Code samples

Example #1

require_once 'classes/CreateDocx.php';

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

//create the Word fragment that is going to replace the variable
$wf = new WordFragment($docx, 'document');
//create an image fragment
$image = new WordFragment($docx, 'document');
$image->addImage(array('src' => 'image.png' , 'scaling' => 50, 'float' => 'right', 'textWrap' => 1));
//and also a link fragment
$link = new WordFragment($docx, 'document');
$link->addLink('link to Google', array('url'=> 'http://www.google.es', 'color' => '0000FF', 'u' => 'single'));
//and a footnote fragment
$footnote = new WordFragment($docx, 'document');
$footnote->addFootnote(
    array(
        'textDocument' => 'here it is',
        'textFootnote' => 'This is the footnote text.',
    )
);
//combine them to create a paragraph
$text = array();
$text[] = $image;
$text[] =
    array(
        'text' => 'I am going to write a link: ',
        'bold' => true,
    );
$text[] = $link;
$text[] =
    array(
        'text' => ' to illustrate how to include links. ',
    );
$text[] =
    array(
        'text' => ' As you may see is extremely simple to do so and can be done with any other Word element. For example to include  a footnote is also as simple as this: ',
    );
$text[] = $footnote;
$text[] =
array(
    'text' => ' , as you see there is a footnote at the bootom of the page. ',
    'color' => 'B70000',
);

//insert all the content in the Word fragment we are going to use for replacement
$wf->addText($text);

$docx->replaceVariableByWordFragment(array('WORDFRAGMENT' => $wf), array('type' => 'block'));

$docx->createDocx('output');

The resulting Word document looks like:

Example #2

require_once 'classes/CreateDocx.php';

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

// create the Word fragment that is going to replace the variable
// like the variable to replace is in a footnote we should it as target
$wf = new WordFragment($docx, 'footnote');

// create an image fragment
$image = new WordFragment($docx, 'footnote');
// Warning: you can not position absolutely images in footnotes. That is a limitation of the Word interface not the standard.
$image->addImage(array('src' => 'image.png' , 'scaling' => 10));

// and also a link fragment
$link = new WordFragment($docx, 'footnote');
$link->addLink('link to Google', array('url'=> 'http://www.google.es', 'color' => '0000FF', 'u' => 'single'));

// combine them to create a paragraph
$text = array();
$text[] = $image;
$text[] =
    array(
        'text' => 'I am going to write a link: ',
        'bold' => true,
    );
$text[] = $link;
$text[] =
    array(
        'text' => ' to illustrate how to include links in a footnote. ',
    );
$text[] =
    array(
        'text' => ' As you may see it is extremely simple to do so and can be done with any other Word element.',
    );

// insert all the content in the Word fragment we are going to use for replacement
$wf->addText($text);

// we want to preserve the reference mark so we do an inline substitution to presereve the paragraph structure.
// we also target the footnote that is where the placeholder variable is located
$docx->replaceVariableByWordFragment(array('INLINEFRAGMENT' => $wf), array('type' => 'inline', 'target' => 'footnote'));

$docx->createDocx('output');

The resulting Word document looks like:

Release notes

phpdocx 15.0:
- improved the inline-block replacement type to work with complex contents multiple times.

phpdocx 13.5:
- stylesReplacementTypeOverwrite option.

phpdocx 12.5:
- inline-block replacement type can be used with the same placeholder name more than once.
- improved inline type replacements to keep existing rPr styles in contents after placeholders.

phpdocx 12.0:
- stylesReplacementType option.
- inline-block type replacement.

phpdocx 7.0:
- improved performance working with headers and footers.

phpdocx 4.6:
- header and footer targets.