Practical javadocx

WordFragments and WordML

Introduction

One of the most exceptional and versatile features of javadocx is the possibility of working with WordML fragments. The WordFragment class makes the insertion of new contents in documents and the replacement of variables in templates flexible. It combines the functionalities included in the library with the versatility of the almost direct work of WordML, that is, the XML format used to create DOCX documents. The correct use of WordFragment is essential to add headers, footers, and nested contents in the documents.

Instantiating the WordFragment class

To use WordFragment, you have to instantiate the WordFragment class, with the CreateDocx class as the main document.

After importing CreateDocx and WordFragment classes:

import com.javadocx.CreateDocx;
import com.javadocx.WordFragment;

Create a new document:

CreateDocx docx = new CreateDocx();

Then, you can add a WordFragment element:

WordFragment text = new WordFragment(docx);

As seen in the constructors:

public WordFragment(CreateDocx docx) throws Exception

public WordFragment(CreateDocx docx, String target) throws Exception

To use the WordFragment class, apply a mandatory parameter, which is the instance of the document, and a second optional parameter with the target of the document. This second parameter can be the body of the document (‘document’), the default header (‘defaultHeader’) or just the first one (‘firstHeader’), the footer (‘defaultFooter’) and other elements like footnotes, endnotes or comments.

Adding elements

The methods for adding the contents are the same available in CreateDocx, including its parameters and available options.

For example, to add a picture, first instantiate the class WordFragment:

WordFragment image = new WordFragment(docx);

Then, define the picture the same way as if you were working with the CreateDocx class:

OptionsImage imageOptions = new OptionsImage();
imageOptions.setScaling(50)
            .setFloatImage("right")
            .setTextWrap(1);
image.addImage("image.png", imageOptions);

Use the same method to add a new link:

OptionsLink linkOptions = new OptionsLink();
linkOptions.setUrl("http://www.google.es")
            .setColor("0000FF")
            .setUnderline("single");

WordFragment link = new WordFragment(docx);
link.addLink("link to Google", linkOptions);

Add these WordFragment methods to the new document, for example through an array:

ArrayList<WordFragment> contents = new ArrayList<WordFragment>();
contents.add(image);
contents.add(link);

Add it to the document, as if you were working directly with CreateDocx.

docx.addText(contents);

Finally, generate the document:

docx.createDocx("tutorial_4");

As well as adding pictures and links, you can include graphic charts, endnotes, page breaks, bookmarks… In other words, most part of the available contents in the CreateDocx class.

A WordFragment may have one or more contents, e.g., a text, an image and a link:

WordFragment contents = new WordFragment(docx);
contents = new WordFragment(docx);

contents.addText("Text content");

contents.addImage("image.png");

OptionsLink linkOptions = new OptionsLink();
linkOptions.setUrl("http://www.google.es")
            .setColor("0000FF")
            .setUnderline("single");
contents.addLink("link to Google", linkOptions);

Working with templates

The method replaceVariableByWordFragment

public void replaceVariableByWordFragment(HashMap<String, WordFragment> variables)

public void replaceVariableByWordFragment(HashMap<String, WordFragment> variables, OptionsReplaceVariableByWordFragment options)

allows to use WordFragments with templates.

To work with templates you have to use an additional variable, again of the WordFragment class, which saves the elements to replace. For example, to replace the picture and the link created before. After loading the template:

CreateDocxFromTemplate docx = new CreateDocxFromTemplate("template.docx");

create a new WordFragment variable:

WordFragment content = new WordFragment(docx, "document");

create the elements to replace the placeholder with:

OptionsImage imageOptions = new OptionsImage();
imageOptions.setScaling(50)
            .setFloatImage("right")
            .setTextWrap(1);
WordFragment image = new WordFragment(docx);
image.addImage("image.png", imageOptions);

OptionsLink linkOptions = new OptionsLink();
linkOptions.setUrl("http://www.google.es")
           .setColor("0000FF")
           .setUnderline("single");
WordFragment link = new WordFragment(docx);
link.addLink("link to Google", linkOptions);

ArrayList<WordFragment> contents = new ArrayList<WordFragment>();
contents.add(image);
contents.add(link);

Instead of using the object in which the document has been instantiated, add the content by calling the WordFragment object:

content.addText(contents);

Finally, for example: replace the variable VAR in the document:

OptionsReplaceVariableByWordFragment replaceVariableByWordFragmentOptions = new OptionsReplaceVariableByWordFragment();
replaceVariableByWordFragmentOptions.setType("block");

HashMap<String, WordFragment> variables = new HashMap<String, WordFragment>();
variables.put("VAR", content);

docx.replaceVariableByWordFragment(variables, replaceVariableByWordFragmentOptions);

Including WordML code

To work at a lower level than with WordFragment, add directly the WordML code:

public void addWordML(String wordML)

For example, for adding a paragraph:

docx.addWordML("<w:p><w:r><w:t>A very simple paragraph with only text.</w:t></w:r></w:p>");

Or, if you need to replace a variable in a template for a WordML code:

HashMap<String, String> variables = new HashMap<String, String>();
variables.put("WORDML", wordML);

docx.replaceVariableByWordML(variables);

Tricks and tips

Inline and block content: When replacing WordFragment elements in templates, you may need to add the inline contents with the replaced variable, or replace the container paragraph completely. To choose one or another, it is just enough to use the ‘type’ option of the second parameter of the method replaceVariableByWordFragment. This parameter can have two values: inline or block.

Next - Adding content to a document