Gnostice Document Studio .NET > Going Deeper > Document Viewing > ASP.NET

The ASP.NET Document Viewer supports interactive form filling of PDF forms. The viewer automatically identifies form fields in loaded PDF documents and allows the user to interactively fill them. The viewer provides several options to control and configure the form filling process. Note that for password protected PDF files that impose a restriction on filling the form the fields are shown as read-only and cannot be filled. To enable filling of such PDF files either the correct password has to be provided or the system-wide setting ForceFullPermission must be set to true.

Enable Form Filling

The code snippet below shows how to enable interactive form filling by configuring the ViewerPreferences on the server. For more information about this please see the topic on server-side events.

  public MyServerEventsHandler : ServerEventsHandler
  {
      // Method called when the server starts up
      public virtual void OnServerStart(OnServerStartEventArgs serverStartEventArgs)
      {
         // serverStartEventArgs.ViewerPreferences contains the preferences for the viewer
         // The preferences need to be set when the server starts up and they cannot be
         // changed after that
         var viewerPreferences = serverStartEventArgs.ViewerPreferences;

         // Set interactivity preferences
         viewerPreferences.Interactivity.AllowFormFilling = true;

         // Set security preferences
         // Setting ForceFullUserPermissions to true allows PDF security restrictions to be overridden
         viewerPreferences.Security.ForceFullUserPermissions = true;
      }
  }

Highlight Color

The highlight color of the form fields can be changed by setting the preference on the client-side. We use the highlightColor property to do this. We can also make the form fields to appear transparent with varying levels of transparency by setting the alpha channel value of the highlightColor property.

  $(document).ready(function () {
    var preferences = new gnostice.Preferences();
    // Specifies highlight color for the interactive form fields.
    preferences.interactiveElements.formFields.highlightColor = "rgba(204, 215, 255, 0.5)";
    var documentViewer = new gnostice.DocumentViewer('doc-viewer-id', preferences);
  }

Submit Form

After filling in the form field values the user can submit the data to the server. Submitting data to the server can be achieved in multiple ways. PDF forms documents can contain a Submit push button within the document with the action type of the push button set to Submit. When the user clicks on the Submit button the values get submitted to the URL configured in the Submit button. This is one approach of submitting form values to the server. For this to work the PDF form must be created with a properly configured Submit button with the Submit URL set to the server you want to receive the data at.

Another approach is to place a Submit button on the web page containing the Document Viewer and then to use the submitForm JavaScript API on the Document Viewer. This would be the approach to take when the PDF document does not contain a Submit button. The submitForm API accepts an URL and submits the form field values to that URL. You can call the submitForm method in the click event of the Submit button placed on the web page outside the viewer frame. The method also accepts parameters such as fields to submit, etc.

The code snippet below shows the usage of the submitForm API.

  $(document).ready(function () {
    $("#submitForms").click(function() {
      var submitUrl = "http://www.gnostice.com/datasubmit";
      var submitMethod = gnostice.SubmitMethod.POST;
      var includeNoValueFields = false;
      var submitFields = null; // Submit all the fields
      var isIncludeList = true;
      documentViewer.Forms.submitForm(submitUrl, submitMethod, includeNoValueFields, submitFields, isIncludeList);
    });
  });

The following table shows the fieldName-fieldValue pairs which are submitted to the server during the submit action for different types of form fields.

Field Type	FieldName Content	FieldValue Content
Text box	Form field mapping name (if present) or form field name	Form field value
Check box		Form Field export value (if present) or form field name of checked box
Radio button		Form Field export value (if present) or form field name of selected radio button item
List box (single select)		Form field export value (if present) or form field display value of selected item
List box (multi select)		Comma separated list of form field export value (if present) or form field display value of selected items
Combo box (single select)		Form field export value (if present) or form field display value of selected item
Combo box (multi select)		Comma separated list of form field export value (if present) or form field display value of selected items

Reset Form

The Document Viewer provides a JavaScript API for resetting the form fields to their default values. Similar to submit action this can also be achieved in multiple ways. PDF forms documents can contain a Reset push button within the document with the action type of the push button set to "Reset". When the user clicks on the Reset button the fields get reset to their default values. This is one approach of resetting form values.

Another approach is to place a Reset button on the web page containing the Document Viewer and then to use the resetForm JavaScript API on the Document Viewer. This would be the approach to take when the PDF document does not contain a Reset button. You can call the resetForm method in the click event of the Reset button placed on the web page. The method accepts parameters such as fields to reset, etc.

The code snippet below shows the signature and usage of the resetForm API.

  $(document).ready(function () {
    $("#resetForms").click(function(){
      var resetFields = null; //Reset all the fields
      var isIncludeList = true;
      documentViewer.Forms.resetForm(resetFields, isIncludeList);
    });
  });

Save

To save form field values back to the document on the server the Document Viewer provides the save JavaScript API and the associated beforeDocumentSave and afterDocumentSave events on the client-side. The code snippet below shows the usage of the save API:

  $(document).ready(function () {
    $("#saveBtn").click(function() {
      // Save the changes back to the document on the server
      documentViewer.save();
    });

    // beforeDocumentSave event handler
    documentViewer.addEventListener(gnostice.EventNames.beforeDocumentSave, function (data: any) {
      console.log("Before document save() " + data.documentUri);
    });

    // afterDocumentSave event handler
    documentViewer.addEventListener(gnostice.EventNames.afterDocumentSave, function (data: any) {
      console.log("After document save() " + data.documentUri);
    });
  });

Once the document is saved on the server an event (afterDocumentSave) is genereated on the server. You can use this to get the saved document. The code snippet below shows how this can be done. For more details see the topic server-side events.

  public class MyServerEventsHandler : ServerEventsHandler
  {
      public override void AfterDocumentSave(AfterDocumentSaveEventArgs documentSaveEventArgs)
      {
          // Read-only property that contains a unique ID assigned to every loaded document
          // This identifier can be used to keep track of the document during the current session
          var documentId = documentSaveEventArgs.DocumentId;

          // Read-only property that contains the stream of the updated document
          var savedDocStream = documentSaveEventArgs.DocStream;
      }
  }

The print JavaScript method can be used to print the document being viewed and filled. Note that the printing happens on the computer where the document is being viewed. When the print method is invoked the document is first saved and then printed.

  $(document).ready(function () {
    $("#printBtn").click(function() {
      // To print the document
      documentViewer.print();
    });
  });

Download

The download and downloadAs JavaScript methods can be used to download the document being viewed and filled as a file. When these methods are invoked the document is first saved and then downloaded.

  $(document).ready(function () {
    $("#downloadBtn").click(function() {
      // To download the document
      documentViewer.download();
    });

    $("#downloadAsBtn").click(function() {
      // To download the document in the format specified by extension.
      documentViewer.downloadAs(“.tiff”);
    });
  });