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 easy but powerful methods that allow you to insert, delete, replace, clone, move, import 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 a specific graph, to delete one or more rows from a table or a whole paragraph, or to replace one graph with another. The possibilities of DOCXPath are almost endless.
DOCXPath is compatible with new documents and templates, and its working environment is limited to document, header and footer contents. In the current stable package, footnotes or endnotes are out of its scope.
insertWordFragment: this method inserts WordFragments after the element specified in the document.
removeWordContent: this method deletes existing elements in the document.
replaceWordContent: this method replaces an existing element by a WordFragment.
cloneWordContent: this method clones existing elements in the document.
moveWordContent: this method moves existing elements in the document.
importContents: this method imports contents from a DOCX. Available only in Premium licenses.
getWordContents: this method returns the text values of existing elements.
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.
- When inserting 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), occurrence ((int) exact occurrence or (string) range of contents (e.g.: 2..9, 2.., ..9) or first() or last(), if empty iterate all elements), 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).
- If the option occurrence is not set all references of the query will be changed.
- 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.