public class FieldMergingArgs extends FieldMergingArgsBase
To learn more, visit the Mail Merge and Reporting documentation article.
Remarks:
The MergeField event occurs during mail merge when a simple mail merge field is encountered in the document. You can respond to this event to return text for the mail merge engine to insert into the document.
Examples:
Shows how to execute a mail merge with a custom callback that handles merge data in the form of HTML documents.
public void insertHtml() throws Exception {
Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");
// Add a handler for the MergeField event
doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());
final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";
// Execute mail merge
doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});
// Save resulting document with a new name
doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
}
private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
// This is called when merge field is actually merged with data in the document.
public void fieldMerging(final FieldMergingArgs args) throws Exception {
// All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
FieldMergeField field = args.getField();
// Insert the text for this merge field as HTML data, using DocumentBuilder
DocumentBuilder builder = new DocumentBuilder(args.getDocument());
builder.moveToMergeField(args.getDocumentFieldName());
builder.write(field.getTextBefore());
builder.insertHtml((String) args.getFieldValue());
// The HTML text itself should not be inserted
// We have already inserted it as an HTML
args.setText("");
}
}
public void imageFieldMerging(ImageFieldMergingArgs args) {
// Do nothing
}
}
IFieldMergingCallback| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
getText()
Gets the text that will be inserted into the document for the current merge field.
|
void |
setText(java.lang.String value)
Sets the text that will be inserted into the document for the current merge field.
|
getDocument, getDocumentFieldName, getField, getFieldName, getFieldValue, getRecordIndex, getTableName, setFieldValuepublic java.lang.String getText()
Remarks:
When your event handler is called, this property is set to null.
If you leave Text as null, the mail merge engine will insert FieldMergingArgsBase.getFieldValue() / FieldMergingArgsBase.setFieldValue(java.lang.Object) in place of the merge field.
If you set Text to any string (including empty), the string will be inserted into the document in place of the merge field.
Examples:
Shows how to execute a mail merge with a custom callback that handles merge data in the form of HTML documents.
public void insertHtml() throws Exception {
Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");
// Add a handler for the MergeField event
doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());
final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";
// Execute mail merge
doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});
// Save resulting document with a new name
doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
}
private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
// This is called when merge field is actually merged with data in the document.
public void fieldMerging(final FieldMergingArgs args) throws Exception {
// All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
FieldMergeField field = args.getField();
// Insert the text for this merge field as HTML data, using DocumentBuilder
DocumentBuilder builder = new DocumentBuilder(args.getDocument());
builder.moveToMergeField(args.getDocumentFieldName());
builder.write(field.getTextBefore());
builder.insertHtml((String) args.getFieldValue());
// The HTML text itself should not be inserted
// We have already inserted it as an HTML
args.setText("");
}
}
public void imageFieldMerging(ImageFieldMergingArgs args) {
// Do nothing
}
}
public void setText(java.lang.String value)
Remarks:
When your event handler is called, this property is set to null.
If you leave Text as null, the mail merge engine will insert FieldMergingArgsBase.getFieldValue() / FieldMergingArgsBase.setFieldValue(java.lang.Object) in place of the merge field.
If you set Text to any string (including empty), the string will be inserted into the document in place of the merge field.
Examples:
Shows how to execute a mail merge with a custom callback that handles merge data in the form of HTML documents.
public void insertHtml() throws Exception {
Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");
// Add a handler for the MergeField event
doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());
final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";
// Execute mail merge
doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});
// Save resulting document with a new name
doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
}
private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
// This is called when merge field is actually merged with data in the document.
public void fieldMerging(final FieldMergingArgs args) throws Exception {
// All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
FieldMergeField field = args.getField();
// Insert the text for this merge field as HTML data, using DocumentBuilder
DocumentBuilder builder = new DocumentBuilder(args.getDocument());
builder.moveToMergeField(args.getDocumentFieldName());
builder.write(field.getTextBefore());
builder.insertHtml((String) args.getFieldValue());
// The HTML text itself should not be inserted
// We have already inserted it as an HTML
args.setText("");
}
}
public void imageFieldMerging(ImageFieldMergingArgs args) {
// Do nothing
}
}
value - The text that will be inserted into the document for the current merge field.