Using TX Text Control, merging data into MS Word compatible templates can be effortlessly done in 3 simple steps.

  • Loading a template
  • Merging with data
  • Exporting the document

Loading a Template

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 merges the data from various data sources into documents. It can be connected to any Text Control ( TXTextControl.ServerTextControl ╰ TX Text Control .NET Server for ASP.NET
╰ TXTextControl Namespace
╰ ServerTextControl Class
The ServerTextControl class implements a component that provide high-level text processing features for server-based applications. , TXTextControl.TextControl ╰ TX Text Control .NET for Windows Forms
╰ TXTextControl Namespace
╰ TextControl Class
The TextControl class implements a Windows Forms control with high-level text editing features. and TXTextControl.WPF.TextControl ╰ TX Text Control .NET for WPF
╰ WPF Namespace
╰ TextControl Class
The WPF.TextControl class class implements a control with high-level text editing features. . The document that is loaded into the connected Text Control is automatically used as the mail merge template.

The following code shows how to create a Mailmerge instance and how to connect it to a ServerTextControl:

using (MailMerge mailMerge = new MailMerge()) {
mailMerge.TextComponent = textControl1;
}
view raw test.cs hosted with ❤ by GitHub

In the next code snippet an Office Open XML (DOCX) template is loaded into a new ServerTextControl instance that is then connected to MailMerge:

TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() {
ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord };
using (TXTextControl.ServerTextControl serverTextControl =
new TXTextControl.ServerTextControl()) {
serverTextControl.Create();
serverTextControl.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls);
using (MailMerge mailMerge = new MailMerge()) {
mailMerge.TextComponent = serverTextControl;
}
}
view raw test.cs hosted with ❤ by GitHub

The template can be any MS Word document with merge fields that can be added using the pre-designed Reporting ribbon tab of the TX Text Control visual editor or using MS Word. The sample template is shown in the next screenshot:

Creating documents with TX Text Control

Merging with Data

MailMerge provides support for the following data sources:

  • DataTable
  • DataSet
  • IEnumerable objects
  • JSON
  • XML

For all of these data source, different Merge methods and implementations are available. For simplicity, the following JSON string is used as the data source:

[
{
"company_name": "Text Control, LLC",
"address":
{
"street": "1111 Text Control Way",
"zip": "28226",
"city": "Charlotte",
"country": "United States"
}
}
]
view raw data.json hosted with ❤ by GitHub

In the next code snippet, the MergeJsonData ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer Namespace
╰ MailMerge Class
╰ MergeJsonData Method
Merges data given as a JSON string into a document template. is used to merge the template with the given JSON data.

// enable MS Word merge fields
TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() {
ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord };
// load JSON data
string jsonData = System.IO.File.ReadAllText("data.json");
// create a temporary ServerTextControl
using (TXTextControl.ServerTextControl serverTextControl =
new TXTextControl.ServerTextControl()) {
serverTextControl.Create();
// load the template
serverTextControl.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls);
// create the mail merge engine
using (MailMerge mailMerge = new MailMerge()) {
// connect to ServerTextControl
mailMerge.TextComponent = serverTextControl;
// merge data into template
mailMerge.MergeJsonData(jsonData);
}
}
view raw test.cs hosted with ❤ by GitHub

The resulting document is shown in the screenshot:

Creating documents with TX Text Control

Exporting the Document

After a successful merge process, the resulting document is loaded into the connected Text Control instance and can be exported to any supported document format. The following code shows how the resulting document is getting exported as an Adobe PDF document.

TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() {
ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord };
string jsonData = System.IO.File.ReadAllText("data.json");
using (TXTextControl.ServerTextControl serverTextControl =
new TXTextControl.ServerTextControl()) {
serverTextControl.Create();
serverTextControl.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls);
using (MailMerge mailMerge = new MailMerge()) {
mailMerge.TextComponent = serverTextControl;
mailMerge.MergeJsonData(jsonData);
}
// export document as PDF
serverTextControl.Save("results.pdf", TXTextControl.StreamType.AdobePDF);
}
view raw test.cs hosted with ❤ by GitHub

Mail Merge Events

MailMerge provides many events ╰ 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. to control the merge process and to interact with fields by injecting custom data or logic. The following events can be used during the mail merge process:

Event Description
BarcodeMerged Occurs when a barcode has been merged successfully.
BlockMerging Occurs when a merge block is about to be merged.
BlockRowMerged Occurs when a merge block row has been merged successfully.
ChartMerged Occurs when a chart has been merged successfully.
DataRowMerged Occurs when a data row has been merged successfully.
FieldMerged Occurs when a field has been merged.
FormFieldMerged Occurs when a form field has been merged.
ImageFieldMerged Occurs when an image field, i.e., a merge field whose name is prefixed with "image:" has been merged.
ImageMerged Occurs when an image has been merged successfully.
IncludeTextMerging Occurs when an IncludeText field has been merged.

The number and the names of the events show that MailMerge provides way more than a simple mail merge process. MailMerge is a powerful rendering engine that supports repeating merge blocks, 1:n relationships, image merging, barcode support and populating form fields. Generally speaking, all document automation processes can be realized using the MailMerge class.

Reading Tip: Event Handling

MailMerge: Field Mapping and Handling of Unmerged Fields

Read More