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 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 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.