Document Viewer
The Document Viewer displays documents in the browser and lets users annotate them, fill out form fields and sign them, without changing their content. What follows covers what the viewer is, what your users and your code do with it, how it works and which packages and frontends are available. To set it up step by step, go to Getting Started: Document Viewer.
What the Document Viewer Is
The Document Viewer is a lightweight, read-only viewer for DOCX, PDF and other supported documents. It is based on standard HTML elements, so users need no plug-ins, Microsoft Word or Adobe Acrobat Reader. All document formats are shown with the same user interface: a toolbar at the top, page thumbnails on the left, the pages in the middle and a status bar with the page number, the zoom and the document name at the bottom.
Typical uses are invoice portals where documents are previewed and downloaded, review processes in which other users add annotations, and signing workflows in which users sign a contract or a form.
What Users Do With It
- Read documents. The viewer displays DOCX, PDF, RTF, HTML and the internal TX Text Control format (TX). DOC, the legacy Word binary format, requires the Classic engine. By default, a PDF is imported by the document engine like any other format; to show PDF pages as they are, the viewer can render them with PDF.js instead, as Loading Documents describes. The backend sends pages to the viewer as soon as they are rendered, so users can start reading a large document before all pages are ready.
- Navigate, search and print. Users scroll through pages and page thumbnails, zoom, search the document, print it with the browser's print function and download it as a PDF. If text selection is enabled, users can select text and copy it to the clipboard.
- Annotate. Users add drawings, stamps, sticky notes and comments to every supported document type. Annotations are stored separately from the document as a JSON string.
- Fill out forms. Users complete form fields in the document, such as text boxes, check boxes, drop-down lists and date pickers.
- Sign. Users draw, type or upload a signature and apply it to the signature boxes in the document.
- Review tracked changes. Users review the tracked changes in a document.
The viewer includes a mobile-friendly view for smaller screens.
What Developers Do With It
- Load documents. Pass a file path or a Base64-encoded document when the viewer is created, or call
loadDocumentin JavaScript at run time, for example after you have downloaded the document from your Web API. - Store and share annotations. Export the annotations as JSON with
annotations.export, store them, for example in your database, and show them again withannotations.load. Because the format is the same for all document types, the same review process works for DOCX and PDF. - Process form data. Check with
forms.validatewhether all required fields are completed, read the entered values withforms.getValues, or save the document with the entered values merged into it withsaveDocument. - Collect signatures. Pass signature settings when you load a document. They define the signature boxes and the URL of an endpoint in your backend. When the user has signed, the viewer's
TextControlcontroller in your backend posts the signature data, including the signed document, to that endpoint, where your code can, for example, save it as a digitally signed PDF withServerTextControl. - Configure the viewer. Settings control, for example, the docking, the toolbar, the thumbnail pane, text selection and how pages are rendered: as bitmaps, as SVG vector graphics or with the actual fonts. By default, the viewer chooses the render mode automatically.
- React to events. The viewer raises events such as
documentLoaded,annotationsChangedandsignaturesCompleted.
Document Viewer or Document Editor
| Document Viewer | Document Editor | |
|---|---|---|
| Purpose | View, annotate, fill out forms and sign documents | Create and edit documents and templates with WYSIWYG editing |
| Content can be changed | No | Yes |
| Communication with the backend | HTTP requests | A WebSocket connection |
| NuGet packages in ASP.NET Core | TXTextControl.Web.DocumentViewer | TXTextControl.Web and TXTextControl.Web.DocumentEditor.Backend |
Both components can be used in the same application. See Document Editor.
How It Works
The Document Viewer consists of a frontend that runs in the browser and an ASP.NET Core backend that renders the documents. The frontend is a web component with the element name tx-document-viewer, and all frontends share one JavaScript API, the TXDocumentViewer object. The backend is a controller named TextControl, which the TXTextControl.Web.DocumentViewer package adds to your application; it loads the document, renders its pages and sends them to the browser over HTTP. With the Classic engine, which you need to display DOC files because the Core engine cannot load them, you install TXTextControl.Web.DocumentViewer.Classic instead. Document Viewer in Product Architecture explains the parts and the packages for each engine, and Document Viewer Architecture describes them in detail.
Frontends
The viewer is available for ASP.NET Core, Angular, React, plain JavaScript and Blazor. In an ASP.NET Core MVC application, the viewer and its backend run in one project. With Angular, React or plain JavaScript, the frontend is a separate application: its basePath setting points to the URL of the backend, and the backend must allow cross-origin requests (CORS). Frontends and the ASP.NET Core Backend lists how the viewer is added in each frontend and which package it needs.
If you are not sure which frontend to use, start with ASP.NET Core. Everything you learn about the viewer settings and the JavaScript API also applies to the other frontends.
Getting Started has no Blazor tutorial for the viewer. In a Blazor Web App, the application references TXTextControl.Web.DocumentViewer and the engine package as its backend, registers controllers, calls app.UseTXDocumentViewer(), and loads documents from C# code into the component. The blog article Getting Started: Document Viewer for Blazor in ASP.NET Core shows the setup. It was written for version 33.0 and installs the packages from the local package source of the setup.
Key Classes and Objects
| Name | Type | Purpose |
|---|---|---|
| TXDocumentViewer | JavaScript object | The public API of the viewer in the browser, used by all frontends, with methods such as loadDocument and saveDocument |
| Annotations | JavaScript object | Shows the annotation toolbar, and exports and loads annotations |
| Forms | JavaScript object | Validates form fields and returns their values |
| Signatures | JavaScript object | Controls the signing process |
| SignatureSettings | JavaScript object | The settings of a signing process, such as the signature boxes and the URL that receives the signed document |
| TrackedChanges | JavaScript object | Works with the tracked changes in the document |
| ControlsFactory.DocumentViewer | .NET method | Creates the viewer in an ASP.NET Core view through Html.TXTextControl().DocumentViewer() |
| DocumentViewerSettings | .NET class | The settings of the viewer in an ASP.NET Core view, such as DocumentPath, DocumentData and RenderMode |
| SignatureData | .NET class | The result of a signing process, including the signed document, as your backend endpoint receives it |
Example
A separate backend for Angular, React or plain JavaScript is an ASP.NET Core Web API with a CORS policy and the Document Viewer middleware, app.UseTXDocumentViewer(); Create the Backend shows its Program.cs. In the browser, TXDocumentViewer is available after the viewer raises the documentViewerLoaded event, and your code then loads documents and works with annotations, as Load a Document With JavaScript and Work With Annotations show.
Next Steps
- Getting Started: Document Viewer with ASP.NET Core — create your first application with the viewer.
- Document Viewer — loading documents, annotations, signatures, the JavaScript API and events in detail.
- Digital Signatures — sign documents in the viewer and on the server.
- ServerTextControl — process the documents that users view and sign.