The MailMerge class is used to merge data into merge fields, image placeholders, merge blocks, barcodes and other reporting elements. By default, MS Word compatible MergeFields and FormFields are merged automatically in loaded templates. But consider a template where a hyperlink should be merged with a dynamic website address.

The Template

In the following screenshot, a simple template is created using TX Text Control that consists of 2 merge fields:

• company
• website

The Data Source

The following class is used to create the data source object for this sample merge process:

private class Report {
  public string Company { get; set; }
  public Hyperlink Website { get; set; }
}

private class Hyperlink {
  public string Target { get; set; }
  public string Text { get; set; }

  public override string ToString() {
    return Text;
  }
}

Pay attention to the Hyperlink class that contains the actual display Text and the Target. The overridden ToString method returns the text, so that without any custom handling, the merge field would contain the display text after the merge process.

After creating an instance of the data source, the MailMerge class is used to merge the data object into the template:

// create a data object
var dummyData = new Report() {
  Company = "Text Control, LLC",
  Website = new Hyperlink() {
    Text = "Visit us",
    Target = "https://www.textcontrol.com"
  }
};

// merge using MailMerge
using (TXTextControl.DocumentServer.MailMerge mm =
  new TXTextControl.DocumentServer.MailMerge() { TextComponent = textControl1 }) {

  // magic happens in the FieldMerged event
  mm.FieldMerged += Mm_FieldMerged;
  mm.MergeObject(dummyData);
}

Custom Event Handling

In our custom handling, we want to replace the merge field website with a clickable hyperlink. Therefore, the FieldMerged event is used to inject the custom handling.

private void Mm_FieldMerged(
  object sender, 
  TXTextControl.DocumentServer.MailMerge.FieldMergedEventArgs e) {

  // check if the current field is a merge field
  if (e.MailMergeFieldAdapter.TypeName == "MERGEFIELD") {
    MergeField field = (MergeField)e.MailMergeFieldAdapter;

    // the DataRow returns the object of the actual data source
    if (e.DataRow[field.Name].GetType() == typeof(Hyperlink)) {

      // cast the object to a Hyperlink
      Hyperlink hyperlink = (Hyperlink)e.DataRow[field.Name];

      // use a temporary ServerTextControl to generate HypertextLink
      using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) {
        tx.Create();

        // the load the field to apply the formatting
        tx.Load(e.MergedField, TXTextControl.BinaryStreamType.InternalUnicodeFormat);

        // remove the field
        tx.ApplicationFields.Clear(true);

        // remove the text, but keep formatting
        tx.SelectAll();
        tx.Selection.Text = "";

        // create and insert a new hypertext link based on the data row object
        TXTextControl.HypertextLink hypertextLink = 
          new TXTextControl.HypertextLink(hyperlink.Text, hyperlink.Target);
        tx.HypertextLinks.Add(hypertextLink);

        // save the content and return to the event arguments
        byte[] data;
        tx.Save(out data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);
        e.MergedField = data;
      }
    }
  }

}

The FieldMerged event is triggered for all merged fields. The event not only returns the MailMergeFieldAdapter that contains information about the merged field, but gives also access to the actual DataRow that is used to merge data into the current field. In the event handler, we check whether the returned DataRow object is a custom Hyperlink object:

if (e.DataRow[field.Name].GetType() == typeof(Hyperlink)) { }  //...

In case, the object is a Hyperlink, a temporary ServerTextControl is used to generate a new hyperlink with the same format (font, color, ...) that is eventually returned to the MergedField property.

In the resulting document, the website merge field is converted into a clickable hypertext link: