Version X18 (28.0) comes with a complete JavaScript API for the online document editor shipped with TX Text Control .NET Server.

The complete JavaScript API documentation can be found in our online docs:

JavaScript API

This article describes typical tasks for MailMerge and reporting applications such as inserting merge fields, merge blocks and how to loop through these MailMerge elements.

Inserting Merge Fields

In the new API, each element, like a TextField, is accessible through it's own collection. The following code snippet shows how to insert a merge field, that is compatible with MailMerge, using the ApplicationFieldCollection.

The collection is accessible through the applicationFields property. The add method inserts a new field at the current input position.

TXTextControl.applicationFields.add(
        TXTextControl.ApplicationFieldFormat.MSWord, 
        "MERGEFIELD", 
        "FieldText", 
        ["FieldName"], 
        af => {
                var highlightColor = "rgba(9, 165, 2, 0.3)";
                var highlightMode = TXTextControl.HighlightMode.Always;

                af.setHighlightColor(highlightColor);
                af.setHighlightMode(highlightMode);
        }
);

The last parameter in the above call of the add method returns the inserted field in a callback. In this code snippet, this returned object is used to add additional properties that are not available in the constructor of the add method.

The above snippet shows how to insert merge fields (or any other supported type) into a document. The same can be achieved by using the addMergeField method to make things easier for the most typical fields.

var mergeField = new TXTextControl.MergeField();

mergeField.name = "company";
mergeField.text = "«company»";
mergeField.numericFormat = "$#,###.00"

TXTextControl.addMergeField(mergeField);

Looping Through Fields

The next code snippet is using the forEach method that is available for each collection in the JavaScript API. This method executes a callback for all elements in a collection. The code loops through all ApplicationFields and returns it's name.

TXTextControl.applicationFields.forEach(function(appField) { 
        appField.getName(function(name) { console.log(name) });
})

The below code snippet changes the text of each field in the document:

TXTextControl.applicationFields.forEach(function(appField) { 
        appField.setText("new text");
})

Inserting Merge Blocks

A merge block that repeats content based on the hierarchical data using MailMerge, is a SubTextPart element. The name of the SubTextPart must have the specific prefix txmb_ followed by the name of the merge block. The following code inserts a merge block with the name myMergeBlock at the current input position:

TXTextControl.selection.getStart(function(curSelStart) { 
        curSel.getLength(function(curSelLength) {
                TXTextControl.subTextParts.add(
                        "txmb_myMergeBlock", 0, curSelStart + 1, curSelLength);
        })
});

The Selection object is used to retrieve the start and length index of the current selection which is then used in the add method of the SubTextPartCollection.

The next code snippet shows how to iterate through all SubTextParts in order to return valid merge block names:

TXTextControl.subTextParts.forEach(function(subTextPart) { 
        subTextPart.getName(function(name) { 
        
                var mergeBlockName;
        
                if (name.startsWith("txmb_")) {
                        mergeBlockName = name.substring(5, name.length);
                        console.log(mergeBlockName);
                }                       
        });
});

Read more about the improved JavaScript API in our documentation and download the trial version of TX Text Control .NET Server to test this on your own.