Web Forms Document Viewer (Legacy)

Before the HTML5 Document Viewer, ASP.NET Web Forms applications displayed documents with a server control of its own: DocumentServer.Web.DocumentViewer, introduced in version 15.0, together with the DocumentServer.DocumentController that loads and prepares the documents on the server. The reference of version 34.0 still documents both classes. What follows is for maintaining Web Forms applications that use them.

Legacy control. Text Control's current guides don't cover this control, and it lacks features of the HTML5 Document Viewer, such as annotations and document signing. For new pages, use the ASP.NET MVC Document Viewer on the .NET Framework, which the blog article Using the MVC DocumentViewer in ASP.NET Web Forms also adds to Web Forms projects, or the viewer in ASP.NET Core.

How the Viewer Works

• DocumentViewer is an ASP.NET server control in the namespace TXTextControl.DocumentServer.Web, derived from System.Web.UI.WebControls.CompositeControl. It shows the pages of a document in the browser, with a toolbar for navigating and zooming. It can't edit the text of a document, but in edit mode it shows input fields for the form fields of a document.
• DocumentController in the namespace TXTextControl.DocumentServer does the document handling on the server. It is a component derived from System.ComponentModel.Component and works with a ServerTextControl, which you assign to its TextComponent property. Its methods throw an exception when TextComponent is not set.
• The viewer uses the controller that you assign to its DocumentController property.

Set Up the Page

The setup below follows Text Control's GitHub sample TextControl.DocumentViewer.Styles, a Web Forms project last updated for version 32.0. It references these assemblies from the Assembly folder of the installation: TXDocumentServer.dll, TXDocumentServer.Web.DocumentViewer.dll, TXDrawing.dll, TXDrawing.Windows.Forms.dll, TXTextControl.dll and TXTextControl.Server.dll. Check that the folder of your installation contains TXDocumentServer.Web.DocumentViewer.dll before you start.

Because the controller uses ServerTextControl, the project needs a licenses.licx file with this line for version 34.0:

TXTextControl.ServerTextControl, TXTextControl.Server, Version=34.0.1900.500, Culture=neutral, PublicKeyToken=6b83fe9a75cfb638

The page registers the control under a tag prefix and places it in an UpdatePanel, which needs a ScriptManager on the page:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="index.aspx.cs" Inherits="ViewerApp.index" %>

<%@ Register Assembly="TXDocumentServer.Web.DocumentViewer" Namespace="TXTextControl.DocumentServer.Web" TagPrefix="cc1" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>DocumentViewer</title>
</head>
<body>
    <form id="form1" runat="server">
        <asp:ScriptManager ID="ScriptManager1" runat="server"></asp:ScriptManager>

        <asp:UpdatePanel ID="UpdatePanel1" runat="server">
            <ContentTemplate>
                <cc1:DocumentViewer ID="DocumentViewer1" runat="server" Height="400px" Width="795px" />
            </ContentTemplate>
        </asp:UpdatePanel>
    </form>
</body>
</html>

The code-behind creates the controller, connects it to a ServerTextControl and to the viewer and loads a document:

using System;
using System.Web.UI;

namespace ViewerApp
{
    public partial class index : Page
    {
        private TXTextControl.DocumentServer.DocumentController documentController1;
        private TXTextControl.ServerTextControl serverTextControl1;

        protected void Page_Load(object sender, EventArgs e)
        {
            // The controller does its work with a ServerTextControl
            documentController1 = new TXTextControl.DocumentServer.DocumentController();
            serverTextControl1 = new TXTextControl.ServerTextControl();
            documentController1.TextComponent = serverTextControl1;

            DocumentViewer1.DocumentController = documentController1;
            DocumentViewer1.LoadDocument(
                Server.MapPath("documents/Demo.rtf"),
                TXTextControl.DocumentServer.FileFormat.RichTextFormat);
        }
    }
}

• LoadDocument loads a file from a path on the server. With the path alone, the file type is taken from the extension; the second parameter sets it explicitly as a FileFormat value: MSWord, RichTextFormat, WordprocessingML or InternalUnicodeFormat.
• LoadDocumentFromMemory loads a document from a variable, for example a document that MailMerge has just created.
• DocumentPath is the alternative to a method call: the viewer loads the file the next time it is initialized. The extension of the file must match its type, because the viewer passes the type it derives from the extension to the controller.

Navigate and Zoom

The look of the toolbar and the pages is set with CSS; the GitHub sample above replaces the button images and the background with a style sheet.

Fill In Form Fields

With EditMode set to Edit, the viewer shows an input field at the position of every form field of the document; the default, ReadOnly, shows the document only. FieldBorderStyle (None, Dashed, Dotted or Solid, the default) and FieldBorderColor set the borders of the fields in edit mode.

To get what the user entered, call SaveUserInput, for example in the click handler of a button. The method raises the SaveFormData event, whose FormData property holds the input as a System.Data.DataTable:

// Attach the handler in Page_Load:
// DocumentViewer1.SaveFormData += DocumentViewer1_SaveFormData;

private void DocumentViewer1_SaveFormData(object sender,
    TXTextControl.DocumentServer.Web.DocumentViewer.SaveFormDataEventArgs e)
{
    // Store the form input as XML
    e.FormData.WriteXml(Server.MapPath("~/App_Data/formdata.xml"));
}

On the server, the controller sets the value of a form field with MergeField, which takes the field's FormFieldAdapter and the new value. GetFieldAdapters returns the adapters of all fields, or of the fields of one page, as a FieldAdapterCollection. Check boxes are drawn with the character codes CharCodeChecked (254) and CharCodeUnchecked (168) of the CheckBoxFont, Wingdings by default.

Save the Document

Save has three overloads:

• Save(string path) and Save(string path, FileFormat format) save the document to a path on the server. Build the path with Server.MapPath.
• Save(FileFormat format) raises the SaveDocument event instead, and your handler decides what happens to the document. Document holds it as a byte array, and FileFormat its format.

// Attach the handler in Page_Load:
// DocumentViewer1.SaveDocument += DocumentViewer1_SaveDocument;

private void DocumentViewer1_SaveDocument(object sender,
    TXTextControl.DocumentServer.Web.DocumentViewer.SaveDocumentEventArgs e)
{
    // Write the snapshot of the document to a file
    System.IO.File.WriteAllBytes(Server.MapPath("~/App_Data/result.docx"), e.Document);
}

For RichTextFormat, the reference writes the bytes as ASCII text with System.IO.File.WriteAllText instead.

DocumentController Members

The controller also works without the viewer, as a helper for templates:

Next Steps

• ASP.NET MVC Document Viewer: the current viewer on the .NET Framework.
• ASP.NET Web Forms Document Editor: the editor control of Web Forms.
• .NET Framework Applications: the files to deploy.