Practical javadocx

Pictures and images

Introduction

Adding images to new documents is as easy as inserting texts, either in the body of the document, header, footer or background.

If you use a template, you can both replace an existing image and replace a text placeholder for an image.

Valid format files for working with images are JPG, PNG and GIF.

Adding images

The method for adding new images is addImage:

OptionsImage imageOptions = new OptionsImage();
imageOptions.setTextWrap(1)
            .setSpacingRight(15)
            .setFloatImage("left");

docx.addImage("image.png", imageOptions);

Backgrounds

If instead of inserting an image in the document you want to place it as a background, use addBackgroundImage:

public void addBackgroundImage(String src) throws Exception

You have to indicate the path of the image in it. For example:

docx.addBackgroundImage("image.jpg");

Replacing pictures/images in a template

javadocx includes two methods to replace images in templates.

replacePlaceholderImage method

public void replacePlaceholderImage(String variable, String src) throws Exception

public void replacePlaceholderImage(String variable, String src, OptionsReplacePlaceholderImage options) throws Exception

replacePlaceholderImage replaces an image present in a document for the new one. The available parameters are:

"variable": Name of the placeholder.
"src": Path to the new image.
The third parameter is optional. It's an OptionsReplacePlaceholderImage object which can have the followings options:
- "firstMatch": It just replaces the first placeholder with the name of the placeholder.
- "target": Area of the variable such as document, header, footer, footnote, endnote or comment.
- "dpi": Dots per inch.
- "width": the new width
- "height": the new height

To make this replacement you have to define an image or images attribute to replace.

In order to do this, just right click on it, open the image properties and search for the field alternate text (this name may vary in each version of MS Word). Type in this field the name of the placeholder, for example: $IMAGE$.

For example, to replace an image in the header:

OptionsReplacePlaceholderImage replacePlaceholderImageOptions = new OptionsReplacePlaceholderImage();
replacePlaceholderImageOptions.setHeight(3)
                              .setWidth(3)
                              .setTarget("header");

docx.replacePlaceholderImage("IMAGE", "image.jpg", replacePlaceholderImageOptions);

replaceVariableByWordFragment method

The second method for adding images in a template replaces a placeholder with a WordFragment. replaceVariableByWordFragment is the method to use:

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

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

For example, to replace the placeholder IMAGE with a picture, after creating the new image instantiating the class WordFragment type this code:

OptionsImage imageOptions = new OptionsImage();
imageOptions.setScaling(50)
            .setFloatImage("right")
            .setTextWrap(1);

WordFragment image = new WordFragment(docx);
image.addImage("image.png", imageOptions);

And replace it by calling replaceVariableByWordFragment:

HashMap<String, WordFragment> variables = new HashMap<String, WordFragment>();
variables.put("IMAGE", image);
        
docx.replaceVariableByWordFragment(variables, replaceVariableByWordFragmentOptions);

Tips and tricks

To add a background color instead of a background image, use setBackgroundColor:

public void setBackgroundColor(String color)

The value of color is hexadecimal, for example:

docx.setBackgroundColor("FFFFCC");

With the preset settings of MS Word the background images won't appear in the printed document. Add it as a watermark using watermarkDocx:

public void watermarkDocx(String source, String target, String type) throws Exception

public void watermarkDocx(String source, String target, String type, OptionsWatermarkDocx options) throws Exception

This method is available for the Advanced and Premium licenses.

Next - Graphic charts