Practical javadocx

Merging

Introduction

One of the most remarkable features of javadocx is the possibility of merging two or more documents. You can merge them to obtain a single document, in the same way as with PDF files.

Besides these merging options, you can also add DOCX, HTML, MHT and RTF files in new documents and templates.

Merging DOCX documents

In order to merge documents, use the mergeDocx method, available in Advanced and Premium licenses.

The available parameters of this method are:

documents: ArrayList of documents to be merged, by order of insertion.
target: Name of the resulting DOCX document.
mergeType: 0 or 1, to preserve or discard the sections of each document you want to add.
enforceSectionPageBreak: enforces a page section break between documents.
numbering: continue or restart, that allows to restart, for example, the page numbering in the merged document.
lineBreaks: insert the number of line breaks indicated between the contents of the merging files.
preserveStyleDefaults: if true makes sure that the defaults of the first document are not overridden.

For example, for merging the documents first.docx, second.docx and third.docx, use the following code:

MultiMerge docx = new MultiMerge();
        
ArrayList<String> documents = new ArrayList<String>();
documents.add("first.docx");
documents.add("second.docx");
documents.add("third.docx");

docx.mergeDocx(documents, "output.docx");

Merging PDF documents

Merging PDF files can be done using mergePDF:

PDFUtilities pdf = new PDFUtilities();
        
ArrayList<String> documents = new ArrayList<String>();
documents.add("first.pdf");
documents.add("second.pdf");
documents.add("third.pdf");

pdf.mergePDF(documents, "output.pdf");

Adding other documents

If you need to add documents that already exist or replace placeholders by files, javadocx provides two methods.

For adding documents to other new ones, call addExternalFile:

public void addExternalFile(OptionsExternalFile options) throws Exception

To replace a placeholder in a template for a document, use replaceVariableByExternalFile:

public void replaceVariableByExternalFile(HashMap<String, String> variables, OptionsReplaceVariableByExternalFile options) throws Exception

Thanks to these methods you can easily add DOCX, HTML, MHT, and RTF files.

The most important of the available options is matchSource. It is a boolean var that forces MS Word to respect as much as possible the original styles and structures of the inserted document.

In the same options parameter, indicate with the src key the document to insert:

Here's a simple example for adding a DOCX in a new document:

OptionsExternalFile externalFileElement = new OptionsExternalFile();
externalFileElement.setSrc("document.docx");

docx.addExternalFile(externalFileElement);

On the other hand, to replace a placeholder in a template, run this code:

OptionsReplaceVariableByExternalFile replaceVariableByExternalFileOptions = new OptionsReplaceVariableByExternalFile();
replaceVariableByExternalFileOptions.setMatchSource(true);

HashMap<String, String> variables = new HashMap<String, String>();
variables.put("EXTERNAL", "document.docx");

docx.replaceVariableByExternalFile(variables, replaceVariableByExternalFileOptions);

Tips and tricks

The altChunk tag, used by the addExternalFile and replaceVariableByExternalFile methods, is only compatible with MS Word 2007 and later versions on Windows. Other office suites like LibreOffice, OpenOffice or old versions of MS Word for macOS are not compatible with altChunk.

The MultiMerge class doesn't use altChunk tags to merge documents, so it's compatible with all DOCX readers.

mergeDocx combines documents sequentially. In order to merge in specific positions it is possible to call mergeDocxAt.

Next - More features