Documents for PDF .NET Edition
GrapeCity Documents PDF Viewer / Form Filler
In This Topic
    Form Filler
    In This Topic

    Form Filler feature, in GcDocs PDF Viewer, enhances your PDF form filling experience by allowing you to:

    While filling PDF forms, you can use either of the following methods:

    The PDF form field values, when filled in Form filler dialog are reflected in the underlying PDF form. You can also save the filled form on client by using SupportApi.

    Note: SupportAPI is only needed if you want to save the filled form on client. Otherwise, load a PDF Form with custom form input types (explained below in this topic), enable the Form Filler dialog, fill the PDF Form within the Form Filler dialog, or even print a filled form on the client without using SupportApi.

    Fill Forms using Form Filler Dialog

    The 'Form Filler' button is provided in GcDocs PDF Viewer toolbar which is always visible but is enabled only when a PDF form is present in the Viewer.

     

    On clicking the 'Form Filler' button, the Form filler dialog is displayed as shown in the below image.


    The Form filler dialog can also be displayed by using below code:

    Index.cshtml
    Copy Code
    if(viewer.hasForm) {
       viewer.showFormFiller();
    }
    

    Customize Input Form Types

    You can customize the display of custom form input types and add validation options like minimum length, placeholder string, pattern, required field etc. which are displayed in the Form filler dialog. The below example elaborates the same by setting up a GcDocs PDF Viewer project as covered in View PDF.

    The GcDocs PDF Viewer's initialization code needs to be updated to set various formFiller options:

    Index.cshtml
    Copy Code
    function loadPdfViewer(selector) {
        var options = {};
        options = setupFormFiller(options);
        var viewer = new GcPdfViewer(selector, options);
        viewer.addDefaultPanels();
        viewer.toolbarLayout.viewer = {
            default: ['open', 'form-filler', '$navigation', '$split', 'text-selection', 'pan', '$zoom', '$fullscreen', 'print', 'title', 'about'],
            mobile: ['open', 'form-filler', '$navigation', 'title', 'about'],
            fullscreen: ['$fullscreen', 'open', 'form-filler', '$navigation', '$split', 'text-selection', 'pan', '$zoom', 'print', 'title', 'about']
        };
        viewer.open("Commercial-Rental-Application-Form.pdf");
    }
    function setupFormFiller(baseOptions) {
        var options = baseOptions || {};
        // Form Filler options:
        options.formFiller = {
        };
        return options;
    }
    

    The sample PDF form used in this example is a tenant application form which seeks the details of a tenant for house rental purposes. You can also download the form here.

    Customize UI Appearance and Input Type Behavior

     

    Add Validation Properties for Form Input Types 

    Form Event Handlers

    Form filler feature provides various event handlers:

    Custom Form Input Types

    Apart from the form fields supported by standard PDF specification, GcDocs PDF Viewer supports custom form input types. These are inherited from the textbox field and are listed below:

    A PDF form with custom input form fields can be created by using GcExcel Templates or by using GcProps property in GcPdf. The form can then be filled in GcDocs PDF Viewer or Form Filler dialog with added validations and other properties.

    'Date' Custom Form Input Type

    The Date input type provides datepicker interface to choose dates easily. However, there might be issues with 'date' type input because of its limited browser support. Refer this link for more information.

    The following table describes the properties which can be applied to a 'date' input type.

    Property Value Description
    type "date" Specifies the type of text box.
    autofocus "true" or "false" Indicates whether an input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    autocomplete "bday"
    "bday-day"
    "bday-month"
    "bday-year"
    Uses the autocomplete attribute on the date input component when asking for date of birth.  Refer this link for details.
    defaultvalue "2018-01-01" Default value.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether the input type is read-only, or not.
    required "true" or "false" Indicates whether the form filling is required or not.
    title "Tooltip"
    "First line\nSecond line"
    Uses the title property to specify text that most browsers display as a tooltip.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage "The date cannot be empty." Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'date' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "dateField1";
    field.GcProps["type"] = "date";
    field.GcProps["required"] = true;
    field.GcProps["validationmessage"] = "The date cannot be empty.";
    doc.AcroForm.Fields.Add(field);
    

    'Time' Custom Form Input Type

    Time input type provides time picker interface to choose time easily. Refer this link for details on browser support and additional attributes.

    The following table describes the properties which can be applied to a 'time' input type.

    Property Value Description
    type time Specifies the type of text box.
    autofocus true Indicates whether an input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    defaultvalue 18:00 Default value.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether an input type is read-only, or not.
    required "true" or "false" Indicates whether the form filling is required or not.
    title "Tooltip"
    "First line\nSecond line"
    Uses the title property to specify text that most browsers will display as a tooltip.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage "The time cannot be empty." Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'time' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "timeField1";
    field.GcProps["type"] = "time";
    field.GcProps["required"] = true;
    field.GcProps["validateoninput"] = true;
    field.GcProps["validationmessage"] = "Please, enter time.";
    doc.AcroForm.Fields.Add(field);
    

    'Telephone' Custom Form Input Type

    Telephone input type can be used to enter and edit a telephone number. Refer this link for details on browser support and additional attributes.

    The following table describes the properties which can be applied to a 'tel' input type.

    Property Value Description
    type "tel" Specifies the type of text box.
    autofocus "true" Indicates whether a input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    autocomplete "on"
    "off"
    "tel"
    "tel-country-code"
    "tel-national"
    "tel-area-code"
    "tel-local"
    "tel-local-prefix"
    "tel-local-suffix"
    "tel-extension"
    A typical implementation of autocomplete simply recalls previous values entered in the same input field.
    defaultvalue "123-456-7890" Default value.
    pattern "^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$"
    "^[0-9]{3}$"
    A regular expression the entered value must match to pass constraint validation.
    placeholder "Input phone" Text to display inside the input type when it has no value.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether an input type is read-only, or not.
    required "true" or "false" Indicates whether the form filling is required or not.
    title "Tooltip"
    "First line\nSecond line"
    Uses the title property to specify text that most browsers will display as a tooltip.
    minlength 1 Minimum number of characters which can be considered valid.
    maxlength 10 Maximum number of characters to be accepted.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage "The phone cannot be empty." Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'tel' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "telField1";
    field.GcProps["type"] = "tel";
    field.GcProps["title"] = "Text area code";
    field.GcProps["placeholder"] = "###";
    field.GcProps["pattern"] = @"^[0-9]{3}$";
    field.GcProps["validateoninput"] = true;
    field.GcProps["validationmessage"] = @"Valid format: 3 digits";
    doc.AcroForm.Fields.Add(field);
    

    'Number' Custom Form Input Type

    Number input type can be used to enter a number. Refer this link for details on browser support and additional attributes.

    The following table describes the properties which can be applied to a 'number' input type.

    Property Value Description
    type “number" Specifies the type of text box.
    autofocus "true" Indicates whether an input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    defaultvalue "123" Default value.
    placeholder "Input number" Text to display inside the input type when it has no value.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether the input type is read-only, or not.
    required "true" or "false" Indicates whether the form filling is required, or not.
    title "Tooltip"
    "First line\nSecond line"
    Uses the title property to specify text that most browsers will display as a tooltip.
    min 1 Minimum value to accept for this input.
    max 10 Maximum value to accept for this input.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage "The number is incorrect." Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'number' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "numberField1";
    field.GcProps["type"] = "number";
    field.GcProps["title"] = "Enter number between 1 and 100";
    field.GcProps["placeholder"] = "[1-100]";
    field.GcProps["required"] = true;
    field.GcProps["min"] = 1;
    field.GcProps["max"] = 100;
    field.GcProps["validateoninput"] = true;
    field.GcProps["validationmessage"] = "The number is incorrect.";
    doc.AcroForm.Fields.Add(field);
    

    'Email' Custom Form Input Type

    Email input type can be used to enter an e-mail address. Refer ths link for details on browser support and additional attributes.

    The following table describes the properties which can be applied to an 'email' input type.

    Property Value Description
    type "email" Specifies the type of the text box.
    autofocus "true" Indicates whether an input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    autocomplete "email" A typical implementation of autocomplete simply recalls previous values entered in the same input field, but more complex forms of autocomplete can exist. For instance, a browser could integrate with a device's contacts list to autocomplete email addresses in an email input type.
    defaultvalue "email@example.com" Default value.
    pattern ".+@globex.com"
    "\S+@\S+\.\S+"
    A regular expression the entered value must match to pass constraint validation.
    placeholder "Input your email" Text to display inside the input type when it has no value.
    minlength 1 Minimum number of characters which can be considered valid.
    maxlength 10 Maximum number of characters to be accepted.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether the input type is read-only, or not.
    required "true" or "false" Indicates whether the form filling is required, or not.
    title "Tooltip"
    "First line\nSecond line"
    Uses the title property to specify text that most browsers will display as a tooltip.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage "The email cannot be empty. " Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'email' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "emailField1";
    field.GcProps["type"] = "email";
    field.GcProps["title"] = "Input your e-mail address";
    field.GcProps["placeholder"] = "Input your email";
    field.GcProps["pattern"] = @".+@globex.com";
    field.GcProps["validateoninput"] = true;
    field.GcProps["validationmessage"] = @"The domain must be globex.com";
    doc.AcroForm.Fields.Add(field);
    

    'Password' Custom Form Input Type

    Password input type provides a way to securely enter a password. Refer this link for details on browser support and additional attributes.

    The following table describes the properties which can be applied to a 'password' input type.

    Property Value Description
    type "password" Specifies the type of text box.
    autofocus "true" or "false" Indicates whether an input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    autocomplete

    "on"

    "off"

    "current-password"

    "new-password"

    "one-time-code"

    Allows the user's password manager to automatically enter the password.
    defaultvalue "anypassword!1" Default value.
    inputmode "numeric" If your recommended (or required) password syntax rules would benefit from an alternate text entry interface than the standard keyboard, you can use the inputmode attribute to request a specific one. The most obvious use case for this is if the password is required to be numeric (such as a PIN). Mobile devices with virtual keyboards, for example, may opt to switch to a numeric keypad layout instead of a full keyboard, to make entering the password easier.
    pattern

    "[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2, 3}$”

    "^[0-9]{3,3}$"
    "[0-9a-fA-F]{4,8}"

    Regular expression that should match the entered value to pass constraint validation.
    placeholder "Input your password" Text to display inside the input type when it has no value.
    minlength 1 Minimum number of characters which can be considered valid.
    maxlength 10 Maximum number of characters to be accepted.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether an input type is read-only, or not.
    required "true" or "false" Indicates whether the form filling is required, or not.
    title

    "Tooltip"

    "First line\nSecond line"

    Uses the title property to specify text that most browsers will display as a tooltip.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage "The password cannot be empty. "
    "Password must be 3 digits."

    Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'password' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "pinField1";
    field.GcProps["type"] = "password";
    field.GcProps["title"] = "Input your PIN";
    field.GcProps["placeholder"] = "PIN";
    field.GcProps["pattern"] = @"^[0-9]{3,3}$";
    field.GcProps["maxlength"] = 3;
    field.GcProps["validateoninput"] = true;
    field.GcProps["autocomplete"] = "one-time-code";
    field.GcProps["validationmessage"] = @"The PIN must be 3 digits.";
    doc.AcroForm.Fields.Add(field);
    

    'Text' Custom Form Input Type

    Text input type can be used to create basic single-line text input type. This is the default input type. Refer this link for details on browser support and additional attributes.

    The following table describes the properties which can be applied to a 'text' input type.

    Property Value Description
    type "text" Specifies the type of text box.
    autofocus "true" or "false" Indicates whether an input type should automatically get focus when the Form filler dialog is activated or when the page loads.
    autocomplete

    "off"

    "name"

    "honorific-prefix"

    "given-name"

    "additional-name"

    "family-name"

    "honorific-suffix"

    "nickname"

    "username"

    "organization-title"

    "organization"

    "street-address"

    "address-line1"

    "address-line2"

    "address-line3"

    "address-level4"

    "address-level3"

    "address-level2"

    "address-level1"

    "country"

    "country-name"

    "cc-name"

    "cc-given-name"

    "cc-additional-name"

    "cc-family-name"

    "cc-number"

    "cc-exp"

    "cc-exp-month"

    "cc-exp-year"

    "cc-csc"

    "cc-type"

    Lets users specify if they need to provide assistance for automated filling of form field values, as well as guidance to the browser  about what type of information is expected in the field.

     

     

    defaultvalue "any text" Default value.
    inputmode "numeric" If your recommended (or required) password syntax rules would benefit from an alternate text entry interface than the standard keyboard, you can use the inputmode attribute to request a specific one. The most obvious use case for this is if the password is required to be numeric (such as a PIN). Mobile devices with virtual keyboards, for example, may opt to switch to a numeric keypad layout instead of a full keyboard, to make entering the password easier.
    pattern "^[0-9]{3,3}$"
    "[0-9a-fA-F]{4,8}"
    A regular expression the entered value must match to pass constraint validation.
    placeholder "Input here " Text to display inside the input type when it has no value.
    multiline "true" or "false" Set this property to true to use the text area as a user input element.
    minlength 1 Minimum number of characters which can be considered valid.
    maxlength 10 Maximum number of characters to be accepted.
    disabled "true" or "false" Indicates whether an input type is disabled, or not.
    readonly "true" or "false" Indicates whether an input type is read-only, or not.
    required "true" or "false" Indicates whether form filling is required, or not.
    spellcheck "true" or "false" The spellcheck property is an enumerated attribute that defines whether the element may be checked for spelling errors.
    title

    "Tooltip"

    "First line\nSecond line"

    Uses the title property to specify text that most browsers will display as a tooltip.
    validateoninput "true" or "false" True indicates whether validation should be performed immediately during user input, otherwise input validation will be performed on blur event.
    validateonmessage

    "The password cannot be empty. "

    "Password must be 3 digits."

    Represents a localized message that describes the validation constraints that the control does not satisfy (if any).

    The 'text' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "textField1";
    field.GcProps["type"] = "text";
    field.GcProps["title"] = "Input text";
    field.GcProps["placeholder"] = "Input here";
    field.GcProps["maxlength"] = 10;
    field.GcProps["validateoninput"] = true;
    field.GcProps["validationmessage"] = "The value is incorrect, maximum length is 10.";
    doc.AcroForm.Fields.Add(field);
    

    GcPdf Examples for Other Input Types

    The 'month' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "monthField1";
    field.GcProps["type"] = "month";
    field.GcProps["title"] = "Enter month.";
    field.GcProps["placeholder"] = "month";
    field.GcProps["required"] = true;
    field.GcProps["validationmessage"] = "The month value cannot be empty.";
    doc.AcroForm.Fields.Add(field);
    

    The 'range' input type and its properties can also be added to a PDF form by using the following example code in GcPdf.

    C#
    Copy Code
    // Create a new PDF document
    var doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    var field = new TextField();
    field.Widget.Page = page;
    field.Widget.Rect = new RectangleF(40, 40, 72 * 3, 24);
    field.Widget.TextFormat.Font = tf.Font;
    field.Widget.TextFormat.FontSize = tf.FontSize;
    field.Name = "rangeField1";
    field.GcProps["type"] = "range";
    field.GcProps["title"] = " Please select a number between 1 and 1000.";
    field.GcProps["min"] = 1;
    field.GcProps["max"] = 1000;
    doc.AcroForm.Fields.Add(field);
    

    Properties Supported by Form Input Types

    The following table provides consolidated information about properties supported by different input types.

    Attribute Input Type Description
    autocomplete All Input type.
    autofocus All Automatically focus the form control when the page is loaded.
    defaultvalue All The default value.
    disabled All Whether the form control is disabled.
    displayname All Text label for the input control. Applicable only if the input type appears in the Form Filler dialog box.
    min number and date Minimum value to accept for the input.
    max number and date Maximum value to accept for the input.
    maxlength password, search, tel, text and url Maximum length (number of characters) of value.
    minlength password, search, tel, text and url Minimum length (number of characters) of value
    multiline text Set this property to true if you want to use the textarea as a user input element.
    multiple email Boolean. Whether to allow multiple values or not.
    pattern password, text and tel Pattern value must match to be valid.
    placeholder password, search, tel, text and url Text that appears in the form control when it has no value set.
    readonly All Boolean. The value is not editable.
    required All Boolean. A value is required or must be check for the form to be submittable.
    spellcheck search and text Whether the element may be checked for spelling errors.
    type All Type of form control.
    validateonmessage All Localized validation message.
    validateoninput All Indicates whether validation should be performed immediately during user input.

    To know more about how to create a PDF form by using custom input form types in GcPdf, refer Fill Custom Form Input Types.