JavaScript API

The pages about tables, fields, track changes and the other features of the Document Editor all build on the concepts of its JavaScript API. Before you write code that changes the document, get to know the TXTextControl object, when your code can use it, how its asynchronous methods return results and how its objects are organized.

What the JavaScript API Is

The Document Editor adds a global object named TXTextControl to the page. Its properties and methods give your code access to the document in the editor: the text and its formatting, tables, images, fields, sections, tracked changes and comments, the current selection and the input position. Its events tell your code what the user does.

All frontends use the same component in the browser, so the API is the same in an ASP.NET Core view, a plain JavaScript page, an Angular or React application and a Blazor page. Only the moment when the object becomes available differs.

The Document Viewer has an API of its own, the TXDocumentViewer object; see Document Viewer.

When the Object Is Available

Two moments matter: when the TXTextControl object exists, so that your code can attach event handlers, and when the editor raises textControlLoaded, after which your code can change the document.

In every frontend, wait for textControlLoaded before you read or change the document:

TXTextControl.addEventListener("textControlLoaded", function () {
  // The editor is ready: the document can be read and changed from here on
  TXTextControl.selection.setText("Hello from the JavaScript API");
});

Events describes the order of the events during initialization.

Settings of TXTextControl.init

In a plain JavaScript page, TXTextControl.init creates the editor from a ComponentSettings object, and its editorSettings property holds a DocumentEditorSettings object. Both were added in version 32.0. The JavaScript tutorial shows the call.

The formatting printer, like setFormattingPrinter, is only used by the Windows-based synchronization service of earlier versions. The platform-independent backend of the current version doesn't support printer-specific formatting, so the setting has no effect there; see Viewing and Printing.

Callbacks

Many methods of the API are asynchronous. They don't return a value; instead, they take a callback function that receives the result when it is available:

function showSelection() {
  TXTextControl.selection.getStart(function (start) {
    TXTextControl.selection.getLength(function (length) {
      console.log("The selection starts at " + start + " and is " + length + " characters long");
    });
  });
}

• Selection.getStart passes the start position of the selection to its callback.
• The second call runs inside the first callback, because it needs the result of the first. Code after getStart in the same function would run before the callback.
• Methods that return nothing, such as most set methods, take an optional callback that is called when the operation has completed. Use it when the next step depends on the change.

Some members return their result directly: btoaUTF8 and atobUTF8 encode and decode strings, and properties such as TXTextControl.selection return objects directly.

Handle Errors

Many methods take an optional error callback as their last parameter. It receives an ErrorArgument with the error message in msg. By default, an error that isn't handled is thrown. Set handled to true to stop that:

function getTableCount() {
  TXTextControl.tables.getCount(function (count) {
    console.log(count + " tables");
  }, function (error) {
    console.log("Failed: " + error.msg);
    error.handled = true; // don't throw the error
  });
}

The unhandledError event is raised before an error is thrown, so a single handler can log all errors that no error callback handles.

Promises and async/await

The API has no methods that return promises. When several calls depend on each other, nested callbacks become hard to read. Wrap a call in a Promise and use async and await instead:

function getSelectionRange() {
  return new Promise(function (resolve, reject) {
    TXTextControl.selection.getStart(function (start) {
      TXTextControl.selection.getLength(function (length) {
        resolve({ start: start, length: length });
      }, reject);
    }, reject);
  });
}

async function logSelection() {
  var range = await getSelectionRange();
  console.log(range.start + ", " + range.length);
}

Awaiting each step also keeps the order: calls that are sent one after another without waiting aren't guaranteed to complete in that order. This matters especially when a loop changes the text of many elements. The blog article New JavaScript API: Working with Callbacks and Promises explains the pattern.

The Object Model

Text Parts

A document consists of text parts: the main text, the headers and footers and the text frames. Each text part is a FormattedText object, which provides the collections of that part, such as tables, paragraphs, textFields, formFields, trackedChanges and comments, and its own selection.

TXTextControl itself inherits from FormattedText and represents the main text. TXTextControl.tables therefore returns the tables of the main text, while a HeaderFooter or a TextFrame returns its own tables through the same property. In the reference, these inherited members are documented on the FormattedText page.

Collections

Collections such as TableCollection or SectionCollection derive from Collection, which provides three methods:

• getCount passes the number of elements to its callback.
• elementAt passes the element at an index.
• forEach calls a function for each element with the element, its index and the number of elements.

Each collection adds its own methods, such as add, getItem and remove.

Objects of the Main Text

Besides the inherited collections, TXTextControl has properties for the whole document, for example:

To select text, assign an object with the start position and the length: TXTextControl.selection = { start: 2, length: 5 };. A SubTextPart is a part of the text that your code defines, to work with a smaller piece of the document. Editing Text and Subtext Parts describe both.

Enumerations

Enumerations are properties of the TXTextControl object, for example TXTextControl.StreamType.WordprocessingML or TXTextControl.HighlightMode.Always. Pass these names instead of numbers.

Obsolete Members

Some older properties are marked obsolete in the reference and will be removed. They have been replaced by get and set methods, which follow the callback model: use setIsTrackChangesEnabled instead of the isTrackChangesEnabled property, and setEditMode instead of editMode. The event textControlChanged is obsolete as well; use changed. Articles written for older versions still use some of these members.

Group Changes Into One Undo Step

When your code makes several changes, each one is a step of its own for the user's undo command. Call beginUndoAction with a name before the changes and endUndoAction after them, and all changes in between are undone and redone in one step.

Remove the Editor

In a single-page application, the page isn't reloaded when the user navigates to another view. Before you remove the editor from the page or create it again, call removeFromDom. It closes the WebSocket connection gracefully and removes the editor with its event handlers and CSS references. If your code adds the editor script to the page dynamically, remove its script element as well before you load it again.

Find Members in the Reference

The JavaScript API reference lists every object with its properties, methods, callbacks and enumerations. For each method, it documents the parameters in their order, which parameters are optional, and the callback type with the value it receives. The members that a version added are listed on the What's New pages, for example Version 34.0.

Next Steps

• Events: react to what users do in the editor.
• Loading and Saving Documents: load and save documents from JavaScript.
• Text and Paragraph Formatting: format the selection.
• Tables: add and change tables.