Tracking

About tracking documents

Tracking is a feature available in Premium licenses.

This functionality allows to:

Enable and disable tracking in a document created from scratch or in an already existing DOCX.
Track added, replaced and deleted contents with the compatible methods.
Include the people participating in the document generation without regarding their origin: local, online provider.
Accept or reject the contents tracked in a document.
Protect a document by allowing changes only in tracked contents.
Obtain all information regarding tracking: contents marked to be added, replaced and deleted and participants.

Tracking changes

To activate change tracking, just call the enableTracking method. All new contents or changes will be added with the corresponding MS Word tracking tags. Use the method disableTracking to mark the end of change tracking.

The following example creates a new document with a paragraph, enables tracking for the user "phpdocx", adds two more paragraphs and finally disables tracking before saving the document:

<?php

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$docx->addText('Not tracked paragraph');

$docx->addPerson(array('author' => 'phpdocx'));

$docx->enableTracking(array('author' => 'phpdocx'));

$docx->addText('First tracked paragraph');

$docx->addText('Second tracked paragraph');

$docx->disableTracking();

$docx->addText('Other paragraph');

$docx->createDocx('document');

More complex contents as images, sections, headers or footers are also compatible:

<?php

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$docx->addText('Not tracked paragraph');

$docx->addPerson(array('author' => 'phpdocx'));

$docx->enableTracking(array('author' => 'phpdocx'));

$imageOptions = array(
    'src' => 'image.png',
    'dpi' => 300,
);

$image = new WordFragment($docx, 'defaultHeader');
$image->addImage($imageOptions);

$docx->addHeader(array('default' => $image));

$textFooter = new WordFragment($docx, 'firstFooter');
$textFooter->addText('page footer.');

$docx->addFooter(array('default' => $textFooter));

$docx->addSection('nextPage', 'A3');

$docx->addText($text);

$paramsText = array(
    'b' => true
);

$docx->addText('New section', $paramsText);

$docx->disableTracking();

$docx->addText('Other paragraph');

$docx->createDocx('document');

It is mandatory to specify the name of the tracking user in enableTracking.

These are the compatible methods with the tracking feature:

When working with or modifying templates, the following methods are tracked too: insertWordFragment, removeWordContent, replaceWordContent, replaceVariableByWordFragment, replaceVariableByHTML.

E.g.: it is possible to open an existing DOCX and track changes such as the deletion of a table or the replacement of a placeholder:

<?php

require_once 'pathToPHPDocX/classes/CreateDocx.php';

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

$docx->addPerson(array('author' => 'phpdocx'));

$docx->enableTracking(array('author' => 'phpdocx'));

$referenceNode = array(
    'type' => 'table',
);

$docx->removeWordContent($referenceNode);

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

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

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

$footnote = new WordFragment($docx, 'document');
$footnote->addFootnote(
    array(
        'textDocument' => 'here it is',
        'textFootnote' => 'This is the footnote text.',
    )
);

$text = array();

$text[] = $image;
$text[] = array(
    'text' => 'I am going to write a link: ',
    'b' => 'on',
);
$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 bottom of the page. ',
    'color' => 'B70000',
);

$wf->addText($text);

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

$docx->disableTracking();

$docx->createDocx('document');

Accept and reject tracked contents and styles

Contents and styles tracked in a document can be accepted, and thus included as definitive in the document, or rejected, that means, deleted.

The acceptTracking method approves one or more tracked contents, the rejectTracking discards them. Selection of contents can be done with a simple DOCXPath query.

The next example accepts the changes for the paragraph that contains "www.phpdocx.con" and rejects the last table of the document:

<?php

require_once 'pathToPHPDocX/classes/CreateDocx.php';

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

$referenceNode = array(
    'type' => 'paragraph',
    'contains' => 'www.phpdocx.com',
);

$docx->acceptTracking($referenceNode);

$referenceNode = array(
    'type' => 'table',
    'occurrence' => -1,
);

$docx->rejectTracking($referenceNode);

$docx->createDocx('document');

These two methods support: inserted contents, inserted rPr and pPr styles, removed styles, removed rows, changed column sizes, removed contents.

Getting tracking information

The method getDocxPathQueryInfo allows to obtain dinamically and on real time the list and information of all contents and styles tracked in a document, either created from scratch or an existing one.

Supported types in tracking queries are: tracking-insert, tracking-delete, tracking-run-style, tracking-paragraph-style, tracking-table-style, tracking-table-grid and tracking-table-row.

Among the extensive information that the Indexer class gets it figures the list of the people participating in the document.

Adding people

MS Word 2013 and higher allows to add one or more people as contributors of a document. The addPerson method adds new people to a document:

<?php

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$docx->addPerson(array('author' => 'user1'));

$docx->addPerson(array('author' => 'user_2'));

$docx->createDocx('document');

This method allows to indicate the provider, e.g., specifying if a user is local or is online in the MS Word cloud.

Other methods

Besides the methods explained so far, phpdocx includes some others:

docxSettings: with the trackRevisions option enables and displays tracking options in MS Word.
protectDOCX: protects documents by blocking changes in contents that are not being tracked.

For more information

All tracking methods include several options in order to serve for almost any task. You can check all available methods and options on the API documentation.