DS Server

Javascript: ApplicationFieldCollection.add Method

Method|Introduced in 28.0

Description

Inserts a new application field at the current input position.

Syntax

<void> ApplicationFieldCollection.add(<ApplicationFieldFormat> format, <string> typeName, <string> text, <string[]> parameters, [<RequestApplicationFieldCallback> callback], [<ErrorCallback> errorCallback])

Parameters

Parameter	Description
format	Specifies the format of the field. The format depends on the application that supports the field. It can be ApplicationFieldFormat.MSWord or ApplicationFieldFormat.HighEdit.
typeName	Specifies the type name of the field. For example the type name of a Microsoft Word MergeField is MERGEFIELD.
text	Specifies the visible text of the field.
parameters	Specifies an array of strings which are the field's parameters. The order and format of the strings depend on the field's format. For example a Microsoft Word MergeField has the following format: MERGEFIELD FieldName [switches]. In this case the first string of the array is the FieldName and the following strings are possible switches. If a field has no parameters, null can be specified.
callback	Optional. Receives the added ApplicationField.
errorCallback	Optional. Is called when the operation failed with an error.

Examples

The following example inserts a Microsoft Word merge field for a customer name and inspects the live field returned by the add callback.

function onTxError(error) {
    console.error("TX Text Control error:", error.msg);
    error.handled = true;
}

TXTextControl.textParts.getMainText(function(mainText) {
    mainText.applicationFields.add(
        TXTextControl.ApplicationFieldFormat.MSWord,
        "MERGEFIELD",
        "CustomerName",
        ["CustomerName", "\\* MERGEFORMAT"],
        function(applicationField) {
            applicationField.getID(function(id) {
                console.log("Customer merge field added with ID:", id);
            }, onTxError);
        },
        onTxError
    );
}, onTxError);