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:

Create a new document:

Then, you can add a WordFragment element:

As seen in the constructors:

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:

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

Use the same method to add a new link:

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

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

Finally, generate the document:

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:

Working with templates

The method replaceVariableByWordFragment

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:

create a new WordFragment variable:

create the elements to replace the placeholder with:

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

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

Including WordML code

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

For example, for adding a paragraph:

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

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