JavaScript API

All code for the features of the Document Viewer uses the TXDocumentViewer object, so its basics come first: what the object is, when your code can use it in each frontend, which methods return promises, how the object model is organized and how it differs from the API of the Document Editor.

What the JavaScript API Is

TXDocumentViewer is a JavaScript object that controls the Document Viewer in the browser: it loads and saves documents, searches, prints and gives access to annotations, form fields, tracked changes, signatures and the toolbar. The ASP.NET Core HTML helper and a plain JavaScript page create the viewer as a web component, and the Angular and React components load the same viewer script and initialize the viewer in an element of their own, so the same API works in every frontend.

When the Object Is Available

TXDocumentViewer exists only after the viewer has been initialized. The viewer then raises the documentViewerLoaded event on the window object, and your code uses the object in a handler of this event or later:

No TypeScript type definitions are documented for the object; TypeScript code in Angular and React declares it as any.

Promises and Return Values

The methods that load and save documents work asynchronously and return promises. Most other members return their result directly:

Methods such as find, scrollToPage, printDocument and the toggle methods return nothing. Apart from event handlers, only the signature process uses callbacks, set with signatures.setSubmitCallback and signatures.setBeforeSubmitCallback.

The following script loads a document, waits until it has been loaded and saves it as PDF when users click a button, with async and await. Replace the script element of Views/Home/Index.cshtml of the ASP.NET Core tutorial:

<input type="button" onclick="saveAsPdf()" value="Save as PDF" />

<script>
    window.addEventListener("documentViewerLoaded", async function () {
        // TXDocumentViewer exists from here on
        var loaded = await TXDocumentViewer.loadDocument(
            btoa("<strong>Loaded with JavaScript</strong>"), "loaded.html");
        console.log("Document loaded: " + loaded);

        // Most other members return their result directly
        console.log("Annotations: " + TXDocumentViewer.annotations.export());
    });

    async function saveAsPdf() {
        try {
            var result = await TXDocumentViewer.saveDocument(TXDocumentViewer.StreamType.AdobePDF,
                { mergeFormFields: true, embedAnnotations: false });
            var base64 = await result.base64();
            console.log("PDF created: " + base64.length + " base64 characters");
        } catch (error) {
            console.error("The document couldn't be saved:", error);
        }
    }
</script>

• await waits for the promise of loadDocument, so the next line runs after the document has been loaded.
• annotations.export returns its JSON string directly.
• saveDocument and base64 are awaited one after the other. The try block catches errors of both calls; the reference doesn't document other ways to handle errors.

The Object Model

TXDocumentViewer has these properties, each returning an object with its own methods:

TXDocumentViewer.signatures returns the Signatures object, described in Digital Signatures.

The methods of TXDocumentViewer itself:

The formats of saveDocument are values of TXDocumentViewer.StreamType: InternalUnicodeFormat, MSWord, AdobePDF and WordprocessingML. Settings objects such as SignatureSettings and DocumentLoadSettings are plain JavaScript objects with the properties the reference lists.

Several Viewers on One Page

With the web component, a page can contain several viewers. TXDocumentViewer refers to the viewer that was initialized last. Each tx-document-viewer element also provides the methods of the viewer, so your code addresses a specific viewer through its element:

document.getElementById("viewer1").loadDocument(btoa("<strong>Viewer 1</strong>"), "viewer1.html");
document.getElementById("viewer2").loadDocument(btoa("<strong>Viewer 2</strong>"), "viewer2.html");

Each viewer raises its own documentViewerLoaded event.

The APIs of the Viewer and the Document Editor

The Document Viewer and the Document Editor have separate JavaScript APIs:

Both can be used on the same page. JavaScript API of the Document Editor describes the editor's API.

Find Members in the Reference

The JavaScript API - Document Viewer reference lists every object with its properties and methods. For each method, it gives the parameters in their order, the return type and, for most members, the version in which the member was introduced. Some features of the viewer are released with versions of the Document Viewer package between the versions of TX Text Control, such as the zoomChanged event in version 33.2.1, and aren't yet listed in the reference.

Next Steps

• Events: all events of the viewer.
• Loading Documents: load documents with loadDocument.
• Architecture: what happens between the browser and the server.