DOCXPath

DOCXPath

Introduction

DOCXPath is a new feature of phpdocx available since version 6.0, in the Advanced and Premium licenses. Its functionality is to facilitate the low level work with DOCX documents through six easy but powerful methods that allow you to insert, delete, replace, clone, move and return almost any Word content.

This feature benefits from the flexibility that a set of options adds. This set allows to filter by content type, position, text, parents, attributes or dynamic queries.

For example, it is possible to add a new image after any paragraph that contains a certain text, to place several new elements before an specific graph, to delete one or more rows from a table or a whole paragraph, or to replace one graph with another. The posibilities of DOCXPath are almost endless.

DOCXPath is compatible with new documents and templates, and its working environment is limited to the document content. In the current stable package, headers, footers, footnotes or endnotes are out of its scope.

Insert elements

This method inserts WordFragments after the element specified in the document.

Remove elements

This method deletes existing elements in the document.

Replace elements

This option replaces an existing element by a WordFragment.

Clone elements

This method clones existing elements in the document.

Move elements

This method moves existing elements in the document.

Get Word contents

This method returns the text values of existing elements.

How to obtain information from a performed query

The previous commands act over the first result of a Xpath query. If you need to obtain information about the data the Xpath query returns, you can run the getDOCXPathQueryInfo method. Thanks to this new method it is possible to get the number of the concurrent results and the string of the query. For example, this allows to go across all concurrent elements with a loop to perform a certain action.

Tips
  • When adding elements, you can use four placing types: before, after, inlineBefore and inlineAfter. The first two place the content as a block type (for example, a paragraph). The other two place contents as inline ones.
  • The following options indicate the references to the contents: type (string, element type, any as default), contains (string, text value), ocurrence (int, number of ocurrence from 1), attributes (string, contains a specific attribute key and value), parent (string, main document body as default, allows to set any parent or a specific one), customQuery (custom xpath query, overwrites any other reference).
  • When setting a referenceNode it is mandatory to employ at least one of the available options. You can combine them freely.
  • If the reference you indicate doesn't exist, the method doesn't add the WordFragment. It is possible to run the $forceAppend parameter to force the addition of the new content, even if the reference you indicate doesn´t exist.
  • If you need to set the last occurrence of an element you can use the value -1. The first element is always 1, unlike PHP arrays, in which the first element is 0.