The 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. class is usually used to merge objects or JSON data into document templates to populate merge fields. Since version 30.0, the MailMerge class can be used to merge data into form fields as well.

Merging Form Fields

The FormFieldMergeType ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer Namespace
╰ MailMerge Class
╰ FormFieldMergeType Property
Specifies in which manner form fields are treated during the merge process. defines how form fields are treated during the merge process.

Member Description
None Form fields are not merged at all.
Preselect Form field content is preselected when possible. Form fields not associated with a data table column are unaffected.
Replace Form fields are replaced with database content. Empty form fields are removed according to property 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.

Consider the following sample template that contains different form fields including checkboxes, drop-downs and form text fields:

Form Template

Pre-Populate Form Fields

The MailMerge class can now be used for 2 different scenarios. In the first scenario, the form should be pre-populated with known data to help users by minimizing their efforts to complete the form. The following code shows how to load the template into a ServerTextControl instance to merge it using the MailMerge engine:

// create the pre-populate data object
HealthcareForm data = new HealthcareForm() {
insurance_date = DateTime.Now,
insurance_name = "Global Health",
insurance_check = true,
insurance_state = "North Carolina",
notes = "Thanks for your business."
};
using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) {
tx.Create();
// load the template
tx.Load("App_Data/health_form.tx", TXTextControl.StreamType.InternalUnicodeFormat);
using (MailMerge mm = new MailMerge()) {
mm.TextComponent = tx;
// pre-populate the form fields
mm.FormFieldMergeType = FormFieldMergeType.Preselect;
mm.MergeObject(data);
}
// save document as PDF
byte[] document;
tx.Save(out document, TXTextControl.BinaryStreamType.AdobePDF);
}
view raw test.cs hosted with ❤ by GitHub

The following screenshot shows the PDF document in Acrobat Reader. The form fields are pre-populated with the merged data:

Form Template

Flatten Form Fields

In the second scenario, the document should be flattened by removing all form fields and replacing them with the actual merge data:

HealthcareForm data = new HealthcareForm() {
insurance_date = new DateTime(2020,1,1),
insurance_name = "Health Providers",
insurance_check = true,
insurance_state = "Georgia",
notes = "Thanks for your business."
};
using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) {
tx.Create();
tx.Load("App_Data/health_form.tx", TXTextControl.StreamType.InternalUnicodeFormat);
using (MailMerge mm = new MailMerge()) {
mm.TextComponent = tx;
mm.FormFieldMergeType = FormFieldMergeType.Replace;
mm.MergeObject(data);
}
// save document as PDF
byte[] document;
tx.Save(out document, TXTextControl.BinaryStreamType.AdobePDF);
}
view raw test.cs hosted with ❤ by GitHub

In the resulting document, all form fields are removed and the document is not an editable form document anymore:

Form Template

The MailMerge class can be used to merge both merge fields and form fields in the same merge process. This helps to generate forms with dynamic, non-editable data (merge fields) and pre-populated form fields that can be edited by end-users. Pre-populating fields in a form eliminates errors, increases the user acceptance and provides a better user experience.