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 Mail
╰ 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); |
The text of the field is displayed in the document.
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(); | |
} | |
} |
When the field is toggled, the field code is displayed in the document.
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); | |
} |
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.