Fields

Fields mark parts of a document that your application fills or evaluates later, and they link text to other places. The JavaScript API of the Document Editor inserts, finds and removes text fields, MS Word fields, hypertext links, bookmarks and links to them, so that you can build templates and links from your application.

The examples extend the view of the ASP.NET Core tutorial.

What a Field Is

A field is a marked piece of text with properties such as a name and an ID. The text of a field can be read and replaced as a unit, which makes fields the place for content that your application fills or evaluates: a customer name, a date, a link.

TX Text Control has several kinds of fields. Each kind has its own collection in the JavaScript API:

Two more kinds have pages of their own: form fields, which users fill out, on Form Fields, and page number fields, which exist only in headers and footers, on Headers and Footers.

Merge Fields in Templates

The fields of mail merge templates are MS Word fields of the type MERGEFIELD. Users insert them from the Reporting tab of the ribbon, whose lists of field names come from JSON data that your code loads with loadJsonData. "Insert Merge Fields in the Document Editor" in Merge Fields shows how, and Merge Blocks does the same for merge blocks.

From code, addMergeField inserts a merge field, and showMergeFieldDialog opens the dialog box for a field type such as MergeField, IfField or DateField.

Insert Text Fields and MS Word Fields

Fields are inserted at the current input position. The following code inserts a text field and an MS Word merge field, and lists the fields of the document. Add it below the editor in Views/Home/Index.cshtml:

<input type="button" onclick="insertTextField()" value="Insert Text Field" />
<input type="button" onclick="insertWordField()" value="Insert Word Field" />
<input type="button" onclick="listWordFields()" value="List Word Fields" />

<script>
    function insertTextField() {
        TXTextControl.textFields.addWithText("Customer name", function (textField) {
            textField.setName("CustomerName", function () {
                // Let users type in front of and behind the field
                textField.setDoubledInputPosition(true);
            });
        }, function (error) {
            console.log(error.msg);
        });
    }

    function insertWordField() {
        TXTextControl.applicationFields.add(
            TXTextControl.ApplicationFieldFormat.MSWord,
            "MERGEFIELD",
            "«CompanyName»",
            ["CompanyName"],
            function (applicationField) {
                applicationField.getTypeName(function (typeName) {
                    console.log("Inserted a " + typeName + " field");
                });
            },
            function (error) {
                console.log(error.msg);
            });
    }

    function listWordFields() {
        TXTextControl.applicationFields.forEach(function (applicationField) {
            applicationField.getTypeName(function (typeName) {
                applicationField.getParameters(function (parameters) {
                    applicationField.getText(function (text) {
                        console.log(typeName + " " + (parameters ? parameters.join(" ") : "") + ": " + text);
                    });
                });
            });
        });
    }
</script>

The code works as follows:

• TextFieldCollection.addWithText inserts a text field with an initial text and passes it to the callback. setName gives it a name that your code uses to find it.
• setDoubledInputPosition adds an input position at the beginning and the end of the field, so that users can type inside or outside the field.
• ApplicationFieldCollection.add takes the field format, MSWord from ApplicationFieldFormat, the type name, the visible text and the parameters. For a MERGEFIELD, the first parameter is the name of the field.
• getTypeName and getParameters read the type and the parameters; getParameters passes null for a field without parameters.

An application field stores the type and the parameters of an MS Word field, but it doesn't implement the logic of the field. A MERGEFIELD, for example, is filled by MailMerge on the server.

Edit and Remove Fields

A TextField and all kinds of fields based on it share these methods:

TextFieldCollection.getItem passes the field at the input position, or the field with an ID as the third parameter, or null. remove removes a text field. ApplicationFieldCollection.remove takes a second parameter that decides whether the text of the field stays in the document.

Show Field Codes

MS Word can show a field as its field code, such as { MERGEFIELD CompanyName }, instead of its text. The ribbon of the Document Editor has no button for this, but the parameters of an application field contain everything a field code needs. Template designers can use such a view to check which field is where. The following code switches the field at the input position, or all MS Word fields of the document, between their text and their field code:

<input type="button" onclick="toggleFieldCodeAtInputPosition()" value="Toggle Field Code" />
<input type="button" onclick="toggleAllFieldCodes()" value="Toggle All Field Codes" />

<script>
    function toggleFieldCode(applicationField) {
        applicationField.getText(function (text) {
            applicationField.getTypeName(function (typeName) {
                if (text.indexOf("{ " + typeName) === 0) {
                    // The field shows its code: restore the text stored in the name
                    applicationField.getName(function (fieldText) {
                        applicationField.setText(fieldText, function () {
                            applicationField.setName("");
                        });
                    });
                } else {
                    // Store the text in the name and show the field code
                    applicationField.getParameters(function (parameters) {
                        applicationField.setName(text, function () {
                            applicationField.setText("{ " + typeName + " " +
                                (parameters || []).join(" ") + " }");
                        });
                    });
                }
            });
        });
    }

    function toggleFieldCodeAtInputPosition() {
        TXTextControl.applicationFields.getItem(function (applicationField) {
            if (applicationField !== null) {
                toggleFieldCode(applicationField);
            }
        });
    }

    function toggleAllFieldCodes() {
        TXTextControl.applicationFields.forEach(toggleFieldCode);
    }
</script>

The code works as follows:

• getText passes the visible text of the field. If it starts with { and the type name, the field shows its code.
• To show the code, the code stores the visible text with setName and builds the field code from getTypeName and getParameters. setText replaces the visible text; the type and the parameters of the field don't change.
• To show the text again, getName passes the stored text, and setName("") removes it. The merge fields that the Reporting tab inserts have no name, so the name is free for this purpose.
• ApplicationFieldCollection.getItem without an ID passes the field at the input position, or null.

Click Toggle All Field Codes in a template with merge fields: every field shows its code, and a second click restores the texts. Because the field code is the visible text of the field, switch the fields back before you save the template.

The blog article Toggle Field Codes in TX Text Control shows the same approach in C# for the Windows Forms control.

Insert Hyperlinks and Bookmarks

The following code inserts a hyperlink, a bookmark and a link to the bookmark. It also handles clicks on the links: the events tell your code which link was clicked, and your code decides what happens:

<input type="button" onclick="insertHyperlink()" value="Insert Hyperlink" />
<input type="button" onclick="insertBookmark()" value="Insert Bookmark" />
<input type="button" onclick="insertLinkToBookmark()" value="Insert Link to Bookmark" />

<script>
    TXTextControl.addEventListener("textControlLoaded", function () {
        // Scroll to the target of a clicked link in the document
        TXTextControl.addEventListener("documentLinkClicked", function (e) {
            TXTextControl.documentTargets.getItem(function (target) {
                if (target !== null) {
                    target.scrollTo();
                }
            }, null, e.target.targetName);
        });

        // Open a clicked hyperlink in a new browser tab
        TXTextControl.addEventListener("hypertextLinkClicked", function (e) {
            window.open(e.hypertextLink.target, "_blank");
        });
    });

    function insertHyperlink() {
        TXTextControl.hypertextLinks.add("Text Control", "https://www.textcontrol.com/", function (link) {
            link.setDescriptiveText("Text Control website");
        });
    }

    function insertBookmark() {
        TXTextControl.documentTargets.add("summary", function (target) {
            if (target === null) {
                console.log("No bookmark can be added at this position.");
            }
        });
    }

    function insertLinkToBookmark() {
        TXTextControl.documentTargets.getItem(function (target) {
            if (target !== null) {
                TXTextControl.documentLinks.add("See the summary", target);
            }
        }, null, "summary");
    }
</script>

• HypertextLinkCollection.add takes the visible text and the target URL. setDescriptiveText sets the text that screen readers use for the link.
• DocumentTargetCollection.add inserts a bookmark with a target name and passes it to the callback, or null if no bookmark can be added at the input position.
• DocumentTargetCollection.getItem finds a bookmark by its ID or target name, the third parameter.
• DocumentLinkCollection.add inserts a link with a text and the bookmark it points to.
• The documentLinkClicked handler receives the target name of the clicked link, and DocumentTarget.scrollTo scrolls to the bookmark. The hypertextLinkClicked handler receives the URL in hypertextLink.target.

Users insert hyperlinks and bookmarks in dialog boxes, which showHtmlDialog opens with HyperlinkDialog or InsertBookmarkDialog. setDocumentTargetMarkers shows markers at the positions of bookmarks.

Find All Fields of a Document

getTextFieldsByType passes an array with information about all fields of one or more kinds, selected with a value of TextFieldType such as ApplicationField, HypertextLink, FormFields or All. Each element is a TextFieldInfo with the name, ID, text and position of the field:

function listAllFields() {
  TXTextControl.getTextFieldsByType(TXTextControl.TextFieldType.All, function (fields) {
    fields.forEach(function (field) {
      console.log(field.type + " " + field.name + ": " + field.text);
    });
  }, function (error) {
    console.log(error.msg);
  });
}

The objects in the array are copies of the field data at the time of the call. To change a field, get it from its collection.

Users see the fields of a document in the Field Navigation sidebar, which showSideBar opens with SideBarType.FieldNavigator. The Field Navigation button of the Reporting tab opens it as well:

React to Field Events

The editor raises textFieldCreated and textFieldDeleted, textFieldClicked when the user clicks into a field and textFieldEntered and textFieldLeft when the input position moves into or out of a field. The handlers receive TextFieldEventArgs with the field information in textField. Events lists all events.

Next Steps

• Form Fields: fields that users fill out.
• Content Controls: content controls from MS Word documents.
• Subtext Parts: mark longer parts of the text.
• Merge Fields in Mail Merge and Reporting: fill merge fields with data.
• Fields in Document Processing: work with fields on the server.