The MailMerge 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 defines how form fields are treated during the merge process.

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

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);
}

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

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);
}

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

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.