TX Text Control .NET Server

Signature Fields

Topic

In contract, approval or onboarding workflows, a document is designed in the Document Editor and signed later. Preparing it for signing means understanding what a signature field is, inserting and naming signature fields, which users and your code can do, storing data about the expected signer and knowing what happens to the fields afterward.

The examples extend the view of the ASP.NET Core tutorial. Signature fields were introduced in version 31.0.

What a Signature Field Is

A signature field is a frame in the document that holds the image of a signature. The image can be added while the document is designed or later, when the document is signed. When the document is saved as PDF on the server, each signature field can also be associated with a digital certificate, which requires that the field has a name.

A signature field is placed like an image or a text frame: inline in the text, anchored to a paragraph or at a fixed position. What a Signature Field Holds in Digital Signatures lists its parts and the formats that keep it.

Signature fields are usually one step of a workflow:

  1. Design. A user or your code places named signature fields in the document in the Document Editor, and the document is saved.
  2. Sign. The Document Viewer shows the document, and users sign in the signature fields by drawing, typing or uploading a signature. See Signature Fields in Document Viewer.
  3. Certify. The backend loads the signed document and applies a certificate to each field when it saves the PDF. See "Sign Signature Fields" in Digitally Sign a PDF.

In a document with several signers, each signer gets a field with a different name.

Insert Signature Fields in the Editor

Users insert a signature field with Insert > Signature Field and draw it at the position where the signature belongs. When they select the field, the editor shows the Frame Formatting tab: its Signer Info group holds the data about the expected signer (Signer, Title, Address, Contact Info and Reason), and its Properties group the Name of the field:

Contract in the Document Editor with a selected signature field above the signer's name, and the Frame Formatting tab whose Signer Info group shows Tim Typer and whose Properties group shows the field name txsign

These boxes set the same values as the JavaScript code in the next section.

Insert Signature Fields From Code

TXTextControl.signatureFields returns the SignatureFieldCollection of the document. The following code inserts a named signature field at the input position with data about the expected signer, and logs the field a user selects. Add it below the editor in Views/Home/Index.cshtml:

<input type="button" onclick="insertSignatureField()" value="Insert Signature Field" />

<script>
    TXTextControl.addEventListener("textControlLoaded", function () {
        TXTextControl.addEventListener("signatureFieldSelected", function (e) {
            var signer = e.signatureField.signerData;
            console.log("Signature field " + e.signatureField.name + " selected" +
                (signer ? ", expected signer: " + signer.name : ""));
        });
    });

    function insertSignatureField() {
        // 2.5 x 1 inch in twips (1 inch = 1440 twips)
        TXTextControl.signatureFields.addAnchored({ width: 3600, height: 1440 },
            TXTextControl.HorizontalAlignment.Left,
            -1, // anchor at the current input position
            TXTextControl.FrameInsertionMode.DisplaceText,
            function (signatureField) {
                // A certificate can only be associated with a named field
                signatureField.setName("txsign", function () {
                    signatureField.setSignerData({
                        name: "Tim Typer",
                        title: "Sales Manager",
                        address: "",
                        contactInfo: "tim@example.com",
                        reason: "Contract approval"
                    });
                });
            },
            function (error) {
                console.log(error.msg);
            });
    }
</script>

The code works as follows:

  • addAnchored takes the size as an object with width and height in twips, the horizontal alignment, the text position (-1 for the input position) and a value of FrameInsertionMode. The callback receives the new SignatureField.
  • setName names the field "txsign", the name that the Getting Started example for signing uses.
  • setSignerData takes a SignerData object with the name, title, address, contact information and reason for signing. The data is stored with the document and used when the field is signed.
  • The signatureFieldSelected handler receives SignatureFieldEventArgs, whose signatureField contains the name and the signer data of the field.

The collection also inserts fields at a fixed position (addAtFixedPositionOnPage) or lets the user draw them (addWithMouse); Images explains the kinds of placement.

Set an Image, Read the Signer Data and Remove a Field

The following code sets the image of the selected signature field from an SVG file, shows the signer data of the field named "txsign" and removes that field:

<input type="file" id="signatureFile" accept=".svg,image/svg+xml" />
<input type="button" onclick="setSignatureImage()" value="Set Signature Image" />
<input type="button" onclick="showSignerData()" value="Show Signer Data" />
<input type="button" onclick="removeSignatureField()" value="Remove Signature Field" />

<script>
    function setSignatureImage() {
        var file = document.getElementById("signatureFile").files[0];
        if (!file) {
            return;
        }

        var reader = new FileReader();
        reader.onload = function () {
            // Keep only the Base64 data after the comma of the data URL
            var base64 = String(reader.result).split(",")[1];

            // Without an ID, getItem passes the selected signature field
            TXTextControl.signatureFields.getItem(function (signatureField) {
                if (signatureField === null) {
                    console.log("Select a signature field first.");
                    return;
                }
                signatureField.setImage(base64, null, function (error) {
                    console.log(error.msg);
                });
            });
        };
        reader.readAsDataURL(file);
    }

    function showSignerData() {
        TXTextControl.signatureFields.getItemByName(function (signatureField) {
            if (signatureField === null) {
                console.log("No field named txsign.");
                return;
            }
            signatureField.getSignerData(function (signerData) {
                console.log(signerData.name + ", " + signerData.title + ": " + signerData.reason);
            });
        }, null, "txsign");
    }

    function removeSignatureField() {
        TXTextControl.signatureFields.getItemByName(function (signatureField) {
            if (signatureField !== null) {
                TXTextControl.signatureFields.remove(signatureField);
            }
        }, null, "txsign");
    }
</script>
  • setImage takes the Base64-encoded image data. The file is read in the browser, as on Images.
  • getItem without an ID passes the selected field, and getItemByName the field with a name, or null.
  • getSignerData passes the stored SignerData.
  • remove removes the field from the document.

SignatureField.image returns a SignatureImage with the settings used when the signature image is saved with the document:

In event arguments, the same two values are the exportCompressionQuality and exportMaxResolution properties of a SignatureImageInfo.

TXTextControl.signatureFields.getItemByName(function (signatureField) {
    if (signatureField !== null) {
        // Compress the saved signature image with quality 80 and at most 300 dpi
        signatureField.image.setExportCompressionQuality(80);
        signatureField.image.setExportMaxResolution(300);
    }
}, null, "txsign");

React to Signature Field Events

The editor raises signatureFieldCreated, signatureFieldDeleted, signatureFieldSelected and signatureFieldDeselected. All handlers receive SignatureFieldEventArgs with the ID, name, position, signer data and image settings of the field. Events lists all events.

After the Design

Save the document with its signature fields as described in Loading and Saving Documents. The JavaScript API of the editor doesn't apply certificates: its save settings have no signature settings. Certificates are applied on the server with SaveSettings.SignatureFields, which associates a DigitalSignature with each named field. A PDF document with unsigned signature fields can also be signed later in a PDF reader such as Acrobat Reader.

The blog article Preparing Documents for E-Signing for Multiple Signers in .NET C# shows a workflow with several signers, and How to Sign Signature Fields with Custom Signer Information and Time Stamps in ASP.NET Core C# the signing on the server.

Next Steps