DOCXPath

Introduction

DOCXPath is a feature of Javadocx available 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 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 content with another. The possibilities 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.

package examples.DOCXPath.insertWordFragment;

import com.javadocx.CreateDocxFromTemplate;
import com.javadocx.WordFragment;
import com.javadocx.elements.OptionsDOCXPath;
import com.javadocx.elements.OptionsImage;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or a template
        CreateDocxFromTemplate docx = new CreateDocxFromTemplate("template.docx");
        
        // create a new WordFragment
        WordFragment contentFragment = new WordFragment(docx);
        
        contentFragment.addText("New text");
        
        OptionsImage imageOptions = new OptionsImage();
        imageOptions.setScaling(50);
        
        contentFragment.addImage("src/examples/files/img/image.png", imageOptions);
        
        // set the reference node to insert the WordFragment
        OptionsDOCXPath referenceNode = new OptionsDOCXPath();
        referenceNode.setType("paragraph")
                     .setOccurrence("2")
                     .setContains("HYPERLINK")
                     .setLocation("before");
        
        // insert the new WordFragment
        docx.insertWordFragment(contentFragment, referenceNode);
        
        // create the new document
        docx.createDocx("output");
    }
}

Remove elements

This method deletes existing elements in the document.

package examples.DOCXPath.removeWordContent;

import com.javadocx.CreateDocxFromTemplate;
import com.javadocx.elements.OptionsDOCXPath;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or a template
        CreateDocxFromTemplate docx = new CreateDocxFromTemplate("template.docx");
        
        OptionsDOCXPath referenceNode = new OptionsDOCXPath();
        referenceNode.setType("paragraph")
                     .setOccurrence("1");
        
        // remove the reference node
        docx.removeWordContent(referenceNode);
        
        // create the new document
        docx.createDocx("output");
    }
}

Replace elements

This method replaces an existing element by a WordFragment.

package examples.DOCXPath.replaceWordContent;

import com.javadocx.CreateDocx;
import com.javadocx.WordFragment;
import com.javadocx.elements.OptionsDOCXPath;
import com.javadocx.elements.OptionsParagraph;
import com.javadocx.elements.OptionsText;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or a template
        CreateDocx docx = new CreateDocx();
        
        String text = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi utaliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.";

        OptionsParagraph paragraphOptions = new OptionsParagraph();
        paragraphOptions.setBold(true)
                        .setFont("Arial");

        docx.addText(text, paragraphOptions);
        
        text = "Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.";
        
        docx.addText(text, paragraphOptions);
        
        OptionsText textOptions = new OptionsText();
        textOptions.setText("New text.")
                   .setFontSize(20)
                   .setColor("0000ff");
        WordFragment textFragment = new WordFragment(docx);
        textFragment.addText(textOptions); 
        
        OptionsDOCXPath referenceNode = new OptionsDOCXPath();
        referenceNode.setType("paragraph")
                     .setContains("Lorem");
        
        // replace the reference node
        docx.replaceWordContent(textFragment, referenceNode);
        
        docx.createDocx("output");
    }
}

Clone elements

This method clones existing elements in the document.

package examples.DOCXPath.cloneWordContent;

import com.javadocx.CreateDocxFromTemplate;
import com.javadocx.elements.OptionsDOCXPath;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or a template
        CreateDocxFromTemplate docx = new CreateDocxFromTemplate("template.docx");
        
        OptionsDOCXPath referenceToBeCloned = new OptionsDOCXPath();
        referenceToBeCloned.setType("image")
                           .setLocation("after");
        
        OptionsDOCXPath referenceNodeTo = new OptionsDOCXPath();
        referenceNodeTo.setType("paragraph")
                       .setContains("closing paragraph");
        
        // clone the reference node
        docx.cloneWordContent(referenceToBeCloned, referenceNodeTo);
        
        // create the new document
        docx.createDocx("output");
    }
}

Move elements

This method moves existing elements in the document.

package examples.DOCXPath.moveWordContent;

import com.javadocx.CreateDocxFromTemplate;
import com.javadocx.elements.OptionsDOCXPath;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or a template
        CreateDocxFromTemplate docx = new CreateDocxFromTemplate("src/examples/files/docxpath/images.docx");
        
        OptionsDOCXPath referenceNodeFrom = new OptionsDOCXPath();
        referenceNodeFrom.setType("image")
                         .setLocation("after");
        
        OptionsDOCXPath referenceNodeTo = new OptionsDOCXPath();
        referenceNodeTo.setType("paragraph")
                       .setContains("closing paragraph");
        
        // move the reference node
        docx.moveWordContent(referenceNodeFrom, referenceNodeTo);
        
        // create the new document
        docx.createDocx("output");
    }
}

Get Word contents

This method returns the text values of existing elements.

package examples.DOCXPath.getWordContents;

import java.util.ArrayList;

import com.javadocx.CreateDocxFromTemplate;
import com.javadocx.elements.OptionsDOCXPath;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or template
        CreateDocxFromTemplate docx = new CreateDocxFromTemplate("template.docx");
        
        OptionsDOCXPath referenceNode = new OptionsDOCXPath();
        referenceNode.setType("paragraph")
                     .setContains("heading");
        
        // get the text contents from the reference node
        ArrayList<String> contents = docx.getWordContents(referenceNode);
        
        // print the text values
        for (int i = 0; i < contents.size(); i++) {
            System.out.println(contents.get(i));
        }
    }
}

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, the following code gets the length of a DOCXPath query (existing paragraphs in the document).

package examples.DOCXPath.getDocxPathQueryInfo;

import org.w3c.dom.NodeList;

import com.javadocx.CreateDocx;
import com.javadocx.elements.OptionsDOCXPath;
import com.javadocx.elements.OptionsParagraph;

public class Sample {
    public static void main(String[] args) throws Exception {
        // it is possible to use DOCXPath with a new document or template
        CreateDocx docx = new CreateDocx();
        
        String text = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi utaliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.";

        OptionsParagraph paragraphOptions = new OptionsParagraph();
        paragraphOptions.setBold(true)
                        .setFont("Arial");

        docx.addText(text, paragraphOptions);
        
        text = "Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.";
        
        docx.addText(text, paragraphOptions);
        
        OptionsDOCXPath referenceNode = new OptionsDOCXPath();
        referenceNode.setType("paragraph");
        
        NodeList queryInfo = docx.getDOCXPathQueryInfo(referenceNode);
        
        System.out.println(queryInfo.getLength());
    }
}

Tips

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 (String, exact occurrence or range of contents (e.g.: 2..9, 2.., ..9) or first() or last(), if empty iterate all elements), attributes (HashMap, 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 use the forceAppend option 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.