Practical javadocx

Adding content to a template

Introduction

To show how the library works with templates, let's modify a template and replace some variables for text, lists, tables and other contents.

Loading the template

First, create a new document using a DOCX as template with the class CreateDocxFromTemplate:

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

Now, let's replace the contents of this docx object. The order of replacement is not relevant.

Texts

The easiest element for replacing a placeholder is a string. replaceVariableByText is the method to be used:

public void replaceVariableByText(HashMap<String, String> variables)

public void replaceVariableByText(HashMap<String, String> variables, OptionsReplaceVariableByText options)

You have to set one or more values in the HashMap to replace them. A second parameter is available with the following options:

"target": Where the variables for replacement are: document, header, footer...
"firstMatch": Replaces the first occurrence only if it's true
"parseLineBreaks": Replaces all characters "\n" with line breaks

For example, replace the TEXT placeholder by a text with a line break:

text = "A web browser (commonly referred to as a browser) is a software application for retrieving, presenting and traversing information resources on the World Wide Web.\n
An information resource is identified by a Uniform Resource Identifier (URI/URL) and may be a web page, image, video or other piece of content.";

HashMap<String, String> variables = new HashMap<String, String>();
variables.put("TEXT", text);

docx.replaceVariableByText(variables);

Lists

Replacing lists is as simple as adding a list with a single element in the template which contains the placeholder. When adding the new values, lists elements remain intact.

To add values to the list, use the replaceListVariable method:

public void replaceListVariable(String variable, ArrayList listValues)

public void replaceListVariable(String variable, ArrayList listValues, OptionsReplaceListVariable options)

Where the available parameters are, in order:

"variable": Name of the placeholder of the template
"listValues": ArrayList with the values to add
"options": "firstMatch" option replaces only the first occurrence if it's true, "parseLineBreaks" replaces the characters "\n" with line breaks, "target" set the placeholder target.

For example, switch the placeholder LIST in a web browser list:

ArrayList<String> items = new ArrayList<String>();
items.add("Google Chrome");
items.add("Mozilla Firefox");
items.add("Internet Explorer");

docx.replaceListVariable("LIST", items);

Tables

Just like with the lists, you can add tables to the template by making a table with the styles that you want and define a row with the variables to replace. This row will be replaced for as many rows as needed with new values, keeping the original table styles.

The signatures of the replaceTableVariable method are:

public void replaceTableVariable(ArrayList<HashMap<String, ?>> variables)

public void replaceTableVariable(ArrayList<HashMap<String, ?>> variables, OptionsReplaceTableVariable options)

Where the parameters are, in order:

"variables": ArrayList with the table placeholders and its values. For each position of the ArrayList, a new row is created in the table.
"options": With the "firstMatch" option replaces only the first occurrence if it's true, "parseLineBreaks" replaces the characters "\n" with line breaks, "target" set the placeholder target.

ArrayList<HashMap<String, ?>> items = new ArrayList<HashMap<String, ?>>();
        
HashMap<String, String> itemRowA = new HashMap<String, String>();
itemRowA.put("MONTH", "September");
itemRowA.put("PERCENT_CHROME", "59.1%");
itemRowA.put("PERCENT_FIREFOX", "24.0%");
itemRowA.put("PERCENT_IE", "9.9%");

HashMap<String, String> itemRowB = new HashMap<String, String>();
itemRowA.put("MONTH", "August");
itemRowA.put("PERCENT_CHROME", "60.1%");
itemRowA.put("PERCENT_FIREFOX", "24.7%");
itemRowA.put("PERCENT_IE", "8.3%");

HashMap<String, String> itemRowC = new HashMap<String, String>();
itemRowA.put("MONTH", "July");
itemRowA.put("PERCENT_CHROME", "59.8%");
itemRowA.put("PERCENT_FIREFOX", "24.9%");
itemRowA.put("PERCENT_IE", "8.5%");

HashMap<String, String> itemRowD = new HashMap<String, String>();
itemRowA.put("MONTH", "Average");
itemRowA.put("PERCENT_CHROME", "- %");
itemRowA.put("PERCENT_FIREFOX", "- %");
itemRowA.put("PERCENT_IE", "- %");

items.add(itemRowA);
items.add(itemRowB);
items.add(itemRowC);
items.add(itemRowD);

docx.replaceTableVariable(items);

Deleting placeholders

Sometimes there's no need to replace every placeholder, and some of them remain in the template. To erase them, call removeTemplateVariable:

public void removeTemplateVariable(String variable, String type, String target)

The available options are:

"variable": Name of the placeholder to remove
"type": Delete type. It also removes or not the container paragraph
"target": To define the target of the placeholder as document, header, footer...

For example, to delete the placeholder FOOTERVAR in the footer code this method:

docx.removeTemplateVariable("FOOTERVAR", "block", "footer");

And, for deleting the placeholder OTHERVAR in the document:

docx.removeTemplateVariable("OTHERVAR", "inline");

Tips and Tricks

How to retrieve variables with the getTemplateVariables: at any time you can know which placeholder hasn't been replaced with the getTemplateVariables method. The method sends back a HashMap with the variables by document, header, footer, footnote, endnote or comment targets.

Working with prefixes allows to carry an extensive control of every placeholder, divided by groups of work, and even permits to classify them by substitution priority. This makes easier its further replacement and deletion.

Template methods replace placeholders in the main document body. To replace placeholders in other scopes such as header, footer, comment or footnote, the target option is available.

Other methods are available to work with templates. They are detailed on the API documentation pages.

Next - Headers and Footers