TX Text Control .NET Server

Events

Topic

To save annotations when they change or continue a process when a document is signed, your code reacts to the events of the Document Viewer. Each event is listed with when the viewer raises it and what its handler receives, and the code shows how handlers are attached in each frontend.

Attach Event Handlers

The viewer raises two kinds of events:

  • documentViewerLoaded is raised on the window object when the viewer has been initialized. From then on, the TXDocumentViewer object exists.
  • All other events are raised by the viewer itself. Your code attaches handlers to them with TXDocumentViewer.addEventListener, which takes the name of the event and a function.

Attach the handlers of the viewer's events in the handler of documentViewerLoaded. The reference documents no method that removes them.

Event Reference

EventIs raised whenThe handler receives
documentViewerLoaded (on window)The viewer has been initialized and is ready to load documentsAn event whose target, the window object, holds TXDocumentViewer
documentLoadedA document has been loadedNothing documented
annotationsChangedAn annotation has been changedNothing documented; read the annotations with annotations.export
signaturesCompletedThe user has signed all signature boxesNothing documented
documentLinkClickedA link to a target in the document has been clickedAn event object with preventDefault, which stops the viewer from scrolling to the target
hypertextLinkClickedA link to a URL has been clickedAn event object with preventDefault, which stops the viewer from navigating to the URL
zoomChangedThe zoom level has changedAn event object whose newValue is the new zoom level

zoomChanged was introduced with version 33.2.1 of the Document Viewer package and isn't yet listed in the reference of addEventListener. Since version 31.2.2 of the package, event names are case-insensitive.

Log the Events

The following script logs the events of the viewer to the browser console. Replace the script element of Views/Home/Index.cshtml of the ASP.NET Core tutorial, open the developer tools of the browser and reload the page:

<script>
    window.addEventListener("documentViewerLoaded", function (e) {
        console.log("Document Viewer loaded");
        console.log(e.target.TXDocumentViewer); // the TXDocumentViewer object

        TXDocumentViewer.addEventListener("documentLoaded", function () {
            console.log("Document loaded");
        });

        TXDocumentViewer.addEventListener("annotationsChanged", function () {
            console.log("Annotations changed: " + TXDocumentViewer.annotations.export());
        });

        TXDocumentViewer.addEventListener("signaturesCompleted", function () {
            console.log("All signature boxes have been signed");
        });

        TXDocumentViewer.addEventListener("documentLinkClicked", function (e) {
            console.log("Document link clicked"); // the viewer scrolls to the target
        });

        TXDocumentViewer.addEventListener("hypertextLinkClicked", function (e) {
            e.preventDefault(); // don't navigate to the URL
            console.log("Hypertext link clicked");
        });

        TXDocumentViewer.addEventListener("zoomChanged", function (e) {
            console.log("Zoom changed: " + e.newValue);
        });

        TXDocumentViewer.annotations.showToolbar(true);

        // Load a document after the handlers are attached, so that documentLoaded is logged
        TXDocumentViewer.loadDocument(btoa("<strong>Sample Content</strong>"), "sample.html");
    });
</script>

The code works as follows:

  • The handler of documentViewerLoaded receives an event whose target is the window object, from which it can read TXDocumentViewer.
  • The handlers of the viewer's events are attached inside it, because TXDocumentViewer doesn't exist before.
  • The script loads a document with loadDocument after attaching the handlers. Whether documentLoaded is raised for a document that the view passes when the viewer starts, before documentViewerLoaded, isn't documented.

Add a note with the annotation toolbar and zoom in: the console logs both events.

Form Field Events

The form fields of a document have events of their own, Focus, Blur and Change, which forms.addEventListener attaches instead of TXDocumentViewer.addEventListener. Form Field Events describes them.

Events in Other Frontends

The events are the same in every frontend; only the place where your code waits for documentViewerLoaded differs:

  • Angular: a component method with @HostListener('window:documentViewerLoaded', ['$event']), in which the handlers are attached with TXDocumentViewer.addEventListener.
  • React: a documentViewerLoaded handler added to window in useEffect.
  • JavaScript: a handler added to window in a script of the HTML page.

JavaScript API shows the code of each frontend.

Next Steps