Text Control's MailMerge TX Text Control .NET Server for ASP.NET
DocumentServer Namespace
MailMerge Class
The MailMerge class is a .NET component that can be used to effortlessly merge template documents with database content in .NET projects, such as ASP.NET web applications, web services or Windows services.
API maps merge fields in MS Word compatible templates with data columns (fields) in supported data sources. During the merge process, the field name in the template is compared to the column names of merged data in the applicable hierarchy level.

The following illustration shows how merge field names are mapped to hierarchical data.

Data Structure

company_name comes from the root table directly while the address is coming from a child table. These fields can be accessed using the "dot notation". For example, to access the street, the merge field name is address.street.

Learn More

MailMerge: Data Structures Explained with a Sample Template and JSON Data

Read Article

Removing Empty Fields

But what is happening to a field in case an appropriate column name cannot be found in the given data source?

By default, empty fields are removed. This behavior can be controlled by setting the RemoveEmptyFields TX Text Control .NET Server for ASP.NET
DocumentServer Namespace
MailMerge Class
RemoveEmptyFields Property
Specifies whether empty fields should be removed from the template or not.
property.

The following sample template contains 3 fields while the third field MERGEFIELD doesn't have an associated data field in the used sample JSON data source.

Data Structure

In the resulting document, the third field is removed:

Data Structure

In the following code, a new instance of the MailMerge class is created and the RemoveEmptyFields is set to false, so that empty fields are not removed from the document.

string jsonData = System.IO.File.ReadAllText("data.json");
using (MailMerge mm = new MailMerge() { TextComponent = textControl1 }) {
mm.RemoveEmptyFields = false;
mm.MergeJsonData(jsonData);
}
view raw test.cs hosted with ❤ by GitHub

Data Structure

Handling Empty Fields

For each merged field, the FieldMerged TX Text Control .NET Server for ASP.NET
DocumentServer Namespace
MailMerge Class
FieldMerged Event
Occurs when a field has been merged.
event can be used to map the field to another data column or to set custom text. The following code attaches the event to the MailMerge instance. The RemoveEmptyFields property must be set to false to handle those empty fields.

string jsonData = System.IO.File.ReadAllText("data.json");
using (MailMerge mm = new MailMerge() { TextComponent = textControl1 }) {
mm.FieldMerged += Mm_FieldMerged;
mm.RemoveEmptyFields = false;
mm.MergeJsonData(jsonData);
}
view raw test.cs hosted with ❤ by GitHub

In the event handler, the text of the unmapped field is changed.

private void Mm_FieldMerged(object sender, MailMerge.FieldMergedEventArgs e) {
if (e.Merged == false) {
if (e.MailMergeFieldAdapter.TypeName == "MERGEFIELD") {
MergeField mf = new MergeField(e.MailMergeFieldAdapter.ApplicationField);
mf.Text = "[Field not merged!]";
}
}
}
view raw test.cs hosted with ❤ by GitHub

The unhandled field contains the custom text after the merge process.

Data Structure

In case there is a mismatch, this event can be also used to add custom mapping lists or dictionaries that represent the mapping between names in the given data source and merge fields in the template.

Removing Empty Paragraphs

In case a paragraph contains only unhandled merge fields and becomes empty during the merge process, the resulting empty line might not be wanted in the resulting document. These empty lines can be removed automatically by setting the RemoveEmptyLines TX Text Control .NET Server for ASP.NET
DocumentServer Namespace
MailMerge Class
RemoveEmptyLines Property
Specifies whether text lines which are empty after merging should be removed from the template or not.
property.

string jsonData = System.IO.File.ReadAllText("data.json");
using (MailMerge mm = new MailMerge() { TextComponent = textControl1 }) {
mm.FieldMerged += Mm_FieldMerged;
mm.RemoveEmptyFields = true;
mm.RemoveEmptyLines = true;
mm.MergeJsonData(jsonData);
}
view raw test.cs hosted with ❤ by GitHub