org.docx4j.model.fields.merge

Class MailMerger

java.lang.Object

org.docx4j.model.fields.merge.MailMerger

Direct Known Subclasses:

MailMergerWithNext

public class MailMerger
extends Object

Perform a mail merge. Instance values are merged into a docx containing MERGEFIELD to produce output docx made up of a copy of the input docx for each collection of input values. The output can be a single docx, or multiple docx. If you choose single docx, there are two ways to do this: One is using MergeDocx, which will ensure each constituent "document" doesn't affect the neighbouring ones (eg numbering will restart). The other is the "poor man's" approach, which puts them together, and just hopes for the best. Images and hyperlinks should be ok. But numbering will continue, as will footnotes/endnotes. From 3.0, there is some support for formatting switches (date/time, numeric, and general), and basic support for MERGEFORMAT. LIMITATIONS: - no support for text before (\b) and text after (\f) switches - no support for \m and \v switches - no support for multiple MERGEFIELD in a single instruction (eg MERGEFIELD CoutesyTitle \f " " MERGEFIELD FirstName \f " " MERGEFIELD LastName )

Author:

jharrop

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	MailMerger.FormTextFieldNames If we're converting MERGEFIELD to FORMTEXT, it is desirable to make the w:fldChar/w:ffData/w:name unique within the docx (though Word 2010 can still open the docx if they aren't), and to remove spaces
static class	MailMerger.OutputField

Field Summary

Fields

Modifier and Type	Field and Description
protected static MailMerger.OutputField	fieldFate

Constructor Summary

Constructors

Constructor and Description
MailMerger()

Method Summary

Modifier and Type	Method and Description
protected static void	canonicaliseStarts(ComplexFieldLocator fl, List<FieldRef> fieldRefs)
protected static String	extractInstr(List<Object> instructions)
static WordprocessingMLPackage	getConsolidatedResultCrude(WordprocessingMLPackage input, List<Map<DataFieldName,String>> data) A "poor man's" approach, which generates the mail merge results as a single docx, and just hopes for the best.
static WordprocessingMLPackage	getConsolidatedResultCrude(WordprocessingMLPackage input, List<Map<DataFieldName,String>> data, boolean processHeadersAndFooters) A "poor man's" approach, which generates the mail merge results as a single docx, and just hopes for the best.
protected static String	getDatafieldNameFromInstr(String instr) Get the datafield name from, for example MERGEFIELD Kundenstrasse \* MERGEFORMAT or MERGEFIELD Kundenstrasse
protected static String	getTextInsideContent(ContentAccessor paragraph) Parse through all content inside the paragraph to concatenate all values inside a text
static void	performMerge(WordprocessingMLPackage input, Map<DataFieldName,String> data, boolean processHeadersAndFooters) Perform merge on a single instance.
protected static void	recursiveRemove(ContentAccessor content, Object needToBeRemoved) To remove an object from the docx template
protected static void	removeSimpleField(FieldRef fr) Remove the field but preserve the paragraph and content around it
protected static void	setFormFieldProperties(FieldRef fr, String ffName, String ffTextInputFormat)
static void	setMERGEFIELDInOutput(MailMerger.OutputField fieldFate) What to do with the MERGEFIELD in the output docx.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

fieldFate

protected static MailMerger.OutputField fieldFate

Constructor Detail

MailMerger

public MailMerger()

Method Detail

getConsolidatedResultCrude

public static WordprocessingMLPackage getConsolidatedResultCrude(WordprocessingMLPackage input,
                                                                 List<Map<DataFieldName,String>> data)
                                                          throws Docx4JException

A "poor man's" approach, which generates the mail merge results as a single docx, and just hopes for the best. Images and hyperlinks should be ok. But numbering will continue, as will footnotes/endnotes.

Parameters:

input -

data -

Returns:

Throws:

Docx4JException

getConsolidatedResultCrude

public static WordprocessingMLPackage getConsolidatedResultCrude(WordprocessingMLPackage input,
                                                                 List<Map<DataFieldName,String>> data,
                                                                 boolean processHeadersAndFooters)
                                                          throws Docx4JException

A "poor man's" approach, which generates the mail merge results as a single docx, and just hopes for the best. Images and hyperlinks should be ok. But numbering will continue, as will footnotes/endnotes. [Advert:] If this isn't working for you, the commercial Enterprise Edition of docx4j (MergeDocx component) will solve your problems.

Parameters:

input -

data -

processHeadersAndFooters - process headers and footers in FIRST section only. If you have multiple sections in your input docx, performMerge is a better approach

Returns:

Throws:

Docx4JException

performMerge

public static void performMerge(WordprocessingMLPackage input,
                                Map<DataFieldName,String> data,
                                boolean processHeadersAndFooters)
                         throws Docx4JException

Perform merge on a single instance. This is the best approach, if your input has headers/footers in multiple sections. If you are using MergeDocx, you can use that to join the instances into a single docx. WARNING: The input docx will be modified, so input a copy if that is a problem. This is left to the user, since that can potentially be more efficient, than doing it here.

Parameters:

input -

data -

processHeadersAndFooters -

Throws:

Docx4JException

canonicaliseStarts

protected static void canonicaliseStarts(ComplexFieldLocator fl,
                                         List<FieldRef> fieldRefs)
                                  throws Docx4JException

Parameters:

fl -

fieldRefs -

Throws:

Docx4JException

getDatafieldNameFromInstr

protected static String getDatafieldNameFromInstr(String instr)

Get the datafield name from, for example MERGEFIELD Kundenstrasse \* MERGEFORMAT or MERGEFIELD Kundenstrasse

extractInstr

protected static String extractInstr(List<Object> instructions)

removeSimpleField

protected static void removeSimpleField(FieldRef fr)

Remove the field but preserve the paragraph and content around it

Parameters:

fr -

getTextInsideContent

protected static String getTextInsideContent(ContentAccessor paragraph)

Parse through all content inside the paragraph to concatenate all values inside a text

Parameters:

paragraph - The paragraph which contains (or not) data

Returns:

All text inside the paragraph

recursiveRemove

protected static void recursiveRemove(ContentAccessor content,
                                      Object needToBeRemoved)

To remove an object from the docx template

Parameters:

content - Body (or other part) of the template

needToBeRemoved - The object that will be removed from the content

setMERGEFIELDInOutput

public static void setMERGEFIELDInOutput(MailMerger.OutputField fieldFate)

What to do with the MERGEFIELD in the output docx. Default is REMOVED. KEEP_MERGEFIELD will allow you to perform another merge on the output document. The AS_FORMTEXT options convert the MERGEFIELD to a FORMTEXT field. This is convenient if you want users to be able to edit the field, where editing is restricted to forms.

Parameters:

fieldFate -

setFormFieldProperties

protected static void setFormFieldProperties(FieldRef fr,
                                             String ffName,
                                             String ffTextInputFormat)