MailMerger (docx4j-core 8.3.9 API)

java.lang.Object
- org.docx4j.model.fields.merge.MailMerger

Direct Known Subclasses:

MailMergerWithNext
```
public class MailMerger
extends java.lang.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

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

Constructor Summary

Constructors
Constructor and Description

MailMerger()

Constructors
Constructor and Description
`MailMerger()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`protected static void`	`canonicaliseStarts(ComplexFieldLocator fl, java.util.List<FieldRef> fieldRefs)`
`protected static java.lang.String`	`extractInstr(java.util.List<java.lang.Object> instructions)`
`static WordprocessingMLPackage`	`getConsolidatedResultCrude(WordprocessingMLPackage input, java.util.List<java.util.Map<DataFieldName,java.lang.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, java.util.List<java.util.Map<DataFieldName,java.lang.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 java.lang.String`	`getDatafieldNameFromInstr(java.lang.String instr)` Get the datafield name from, for example MERGEFIELD Kundenstrasse \* MERGEFORMAT or MERGEFIELD Kundenstrasse
`protected static java.lang.String`	`getTextInsideContent(ContentAccessor paragraph)` Parse through all content inside the paragraph to concatenate all values inside a text
`static void`	`performMerge(WordprocessingMLPackage input, java.util.Map<DataFieldName,java.lang.String> data, boolean processHeadersAndFooters)` Perform merge on a single instance.
`protected static void`	`recursiveRemove(ContentAccessor content, java.lang.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, java.lang.String ffName, java.lang.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,
                                                                 java.util.List<java.util.Map<DataFieldName,java.lang.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,
                                                                 java.util.List<java.util.Map<DataFieldName,java.lang.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,
                                java.util.Map<DataFieldName,java.lang.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,
                                         java.util.List<FieldRef> fieldRefs)
                                  throws Docx4JException
```
    Parameters:
    
    fl -
    
    fieldRefs -
    
    Throws:
    
    Docx4JException
  - getDatafieldNameFromInstr
```
protected static java.lang.String getDatafieldNameFromInstr(java.lang.String instr)
```
    Get the datafield name from, for example MERGEFIELD Kundenstrasse \* MERGEFORMAT or MERGEFIELD Kundenstrasse
  - extractInstr
```
protected static java.lang.String extractInstr(java.util.List<java.lang.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 java.lang.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,
                                      java.lang.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,
                                             java.lang.String ffName,
                                             java.lang.String ffTextInputFormat)
```

Class MailMerger

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

fieldFate

Constructor Detail

MailMerger

Method Detail

getConsolidatedResultCrude

getConsolidatedResultCrude

performMerge

canonicaliseStarts

getDatafieldNameFromInstr

extractInstr

removeSimpleField

getTextInsideContent

recursiveRemove

setMERGEFIELDInOutput

setFormFieldProperties