When providing users with the ability to modify documents after they have been generated by 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. , there are several options you can utilize.

Merge Data

Consider the following scenario where a particular JSON data source is being used for template creation.

[
{
"id": 1,
"customer": {
"id": 1,
"name": "John Doe",
"street": "123 Main St",
"city": "Anytown",
"state": "TX",
"zip": "12345"
},
"items": [
{
"id": 1,
"name": "Widget",
"price": 9.99,
"quantity": 2
},
{
"id": 2,
"name": "Thing",
"price": 5.99,
"quantity": 5
},
{
"id": 3,
"name": "Gadget",
"price": 199.99,
"quantity": 1
}
],
"total": 0
},
{
"id": 2,
"customer": {
...
view raw data.json hosted with ❤ by GitHub

The controller loads this JSON and passes it to the view, where it is loaded into the editor to populate the dropdowns with the correct merge field names.

public IActionResult Index()
{
string json = System.IO.File.ReadAllText("App_Data/data.json");
ViewBag.Data = json;
return View();
}
view raw test.cs hosted with ❤ by GitHub

Sending Data to Endpoint

The view code loads the JSON and makes a jquery AJAX call to send the create template to the Merge endpoint.

@using TXTextControl.Web.MVC
@Html.TXTextControl().TextControl().LoadDataFromJson(ViewBag.Data).Render()
<input type="button" onclick="mergeDocument()" value="Merge Document" />
@section Scripts {
<script>
function mergeDocument() {
TXTextControl.saveDocument(TXTextControl.StreamType.InternalUnicodeFormat, function (results) {
$.ajax({
url: '@Url.Action("Merge")',
type: 'POST',
contentType: "application/json",
data: JSON.stringify(results),
success: function (data) {
TXTextControl.loadDocument(TXTextControl.StreamType.InternalUnicodeFormat, data);
}
});
});
}
</script>
}
view raw test.cshtml hosted with ❤ by GitHub

The editor enables users to create the template by adding available merge fields and merge blocks.

Creating documents with TX Text Control

After the merge process, the returned document contains merged content and the field functionality is removed.

Creating documents with TX Text Control

Preserve Empty Fields

Now consider that there are fields in the template that have no data. By default, these fields are removed after the merge.

Creating documents with TX Text Control

The following screenshot shows the merged document with the empty "MERGEFIELD" field removed.

Creating documents with TX Text Control

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 to false, these fields are retained and the field functionality is preserved.

using (MailMerge mm = new MailMerge())
{
mm.TextComponent = tx;
mm.RemoveEmptyFields = false;
// load json data
string json = System.IO.File.ReadAllText("App_Data/data.json");
// merge data
mm.MergeJsonData(json, true);
}
view raw test.cs hosted with ❤ by GitHub

Learn More

The MailMerge class provides several settings to control the merge process and formatting in the resulting document. There are several switches to control how text fields, blocks, images, and blank lines are handled. This article provides an overview of when and how to use each option.

MailMerge Class Settings Explained

Preserve Field Functionality

But now consider a scenario in which you want the merged fields to be editable after the merge process is complete. In this case, there is not a property that is available, but there is a typical workflow that allows this to be realized. Each field provides an event that fires when fields are merged. It is usually used to change the contents of the field after the merge.

The advantage of this process is that the functionality of the field is maintained after the field is changed.

The following code attaches the event to the MailMerge object, passing the merged content back to the field.

[HttpPost]
public IActionResult Merge([FromBody] Content results)
{
using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl())
{
tx.Create();
tx.Load(Convert.FromBase64String(results.Data), TXTextControl.BinaryStreamType.InternalUnicodeFormat);
using (MailMerge mm = new MailMerge())
{
mm.TextComponent = tx;
mm.FieldMerged += Mm_FieldMerged;
// load json data
string json = System.IO.File.ReadAllText("App_Data/data.json");
// merge data
mm.MergeJsonData(json, true);
}
tx.Save(out byte[] data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);
return Ok(Convert.ToBase64String(data));
}
}
private void Mm_FieldMerged(object sender, MailMerge.FieldMergedEventArgs e)
{
e.MergedField = e.MergedField;
}
view raw test.cs hosted with ❤ by GitHub

As a result, the merge fields are populated, but the field functionality remains intact.

Creating documents with TX Text Control

This allows users to modify these fields and other content and merge the template again Another use case is previewing live data during the template creation process without losing field functionality.