In TX Text Control, a merge field is a type of placeholder or special field within a document that is used to insert dynamic data during a document merge process. Merge fields are typically used in document automation scenarios, such as creating personalized letters, invoices, or reports, where specific pieces of data - such as names, addresses, dates, or other variable information - are dynamically inserted into the document.

Merge fields that can be automatically merged with data such as JSON or XML using 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 are compatible with MS Word.

In previous versions of the Editor ribbon UI, we had a button to toggle between the actual human-readable field text and the actual field codes - a feature that is sort of hidden in MS Word. This feature confused many end users because most of them don't really know what field codes are, and they shouldn't.

TX Text Control is popular because non-technical users can create their reporting or automation templates using only MS Word. So in later versions we decided to remove this button from the UI. But in some cases, for power users, it might be helpful to toggle between these states.

Inserting Merge Fields

Consider the following code, which adds a new merge field to a document.

MergeField mergeField = new MergeField();
mergeField.Name = "MyMergeField";
mergeField.NumericFormat = "0.00";
mergeField.DateTimeFormat = "dd.MM.yyyy";
mergeField.TextBefore = "before";
mergeField.TextAfter = "after";
mergeField.Text = "??" + mergeField.Name + "??";
mergeField.ApplicationField.HighlightMode = HighlightMode.Activated;
textControl1.ApplicationFields.Add(mergeField.ApplicationField);
view raw test.cs hosted with ❤ by GitHub

The text of the field is displayed in the document.

Fields in TX Text Control

Toggling Merge Fields

The following code can use the Parameters ╰ TX Text Control .NET Server for ASP.NET
╰ TXTextControl Namespace
╰ ApplicationField Class
╰ Parameters Property
Gets or sets the field's parameters. array to generate the field code string that will be used as the new field text when toggling.

private void ToggleFieldCodes(ApplicationField applicationField)
{
// Toggle the field codes of an ApplicationField
if (applicationField.Text.StartsWith("{ " + applicationField.TypeName))
{
// Reapply the stored field text
applicationField.Text = applicationField.Name;
}
else
{
// Store the current field text
applicationField.Name = applicationField.Text;
var fieldTextBuilder = new StringBuilder("{ " + applicationField.TypeName + " ");
fieldTextBuilder.Append(string.Join(" ", applicationField.Parameters.Select(p => p.Replace("\"", ""))));
fieldTextBuilder.Append(" }");
applicationField.Text = fieldTextBuilder.ToString();
}
}
view raw test.cs hosted with ❤ by GitHub

When the field is toggled, the field code is displayed in the document.

Fields in TX Text Control

JavaScript Version

The same task can be accomplished in the online editor with the following JavaScript code:

function processFieldCode(appField) {
appField.getText(text => {
appField.getName(name => {
appField.getTypeName(typeName => {
if (text.startsWith(`{ ${typeName}`)) {
appField.setText(`??${name}??`);
} else {
appField.getParameters(params => {
const paramString = `{ ${typeName} ${params.join(" ")} }`;
appField.setText(paramString);
});
}
});
});
});
}
function toggleFieldCodes() {
TXTextControl.applicationFields.getItem(processFieldCode);
}
view raw test.js hosted with ❤ by GitHub

Conclusion

TX Text Control provides an easy way to insert merge fields into a document and toggle between field text and field code. This feature is useful for power users who need to see the field code for debugging or troubleshooting purposes.