Introduction to Forms

A PDF document may contain any number of form fields that allow a user to enter information into a PDF page. The concept of forms in PDFs is similar to a form in the physical world. As it’s an electronic format, PDF offers certain advantages to users — for example, the ability to edit entered information at a later date. Document creators also gain advantages, such as the ability to limit the user input to a standardized input format and to react to a user input via JavaScript.

Form Support in PSPDFKit

PSPDFKit supports all form types specified by the PDF specification.

We differentiate between field objects and annotation objects; field objects have no visual representation of their own and are represented by FormField, while annotation objects are visual representations of a single control inside a form field and are represented by FormElement.

With form elements being programmatically accessible, you can easily prefill all your forms or submit filled-in form values to your server. We modeled our forms API around the FormProvider, which can be accessed via PdfDocument#getFormProvider. It can be used to retrieve all form fields or elements in a document or to query form fields by their name.

For a complete example of how to fill forms programmatically, take a look at FormFillingExample in our Catalog app.

Retrieving Field and Annotation Objects

Using the FormProvider (which can be retrieved from a PdfDocument), you can fetch field objects with the getFormFields() method. Associated annotations can be retrieved by retrieving associated FormElements using the getFormElements() call on each field and then calling getAnnotation() on each element.

If you need to retrieve a specific field object, you can use the getFormFieldWithFullyQualifiedName() method on FormProvider. Annotations can then be retrieved from associated fields.

Form selection can be controlled with a new API in PdfFragment. This is analogous to the existing annotation selection API. A single FormElement can be selected by calling setSelectedFormElement; you can query for the selected form element with getSelectedFormElement; and you can exit form editing mode via exitCurrentlyActiveMode. We also have a set of listeners that can be registered on PdfFragment for listening to form element updates, selection changes, and clicks. Take a look at FormManager for a list.

Field Objects

Field objects handle the state of form fields and offer appropriate methods to modify them. Each form field has a fully qualified name (retrievable by calling getFullyQualifiedName()) that can be used to identify and retrieve a specific field object.

You can call the getType() getter to find out which kind of field object it is. This allows you to easily cast the FormField to the correct type.

Annotation Objects

Each field object has one or more annotations linked to it. The main purpose of an annotation object is to offer a graphical element on top of a PDF (see Introduction to Annotations for more on this).

JavaScript Support

PSPDFKit supports the execution of JavaScript attached to a document, annotations, and forms. Most validation rules should work out of the box, and we’re constantly working on improving the engine and increasing our coverage of the specifications. For more information, have a look at the JavaScript Support guide.

Renaming Form Field Names

Due to internal constraints, form field names can’t be renamed using FormField or FormElement instances. It is, however, possible to rename them using PdfProcessor; see the setFormFieldMappings call on PdfProcessorTask. You can simply pass in a map containing your source form field name and the new form field name.

As an example, this can be useful if you have a template PDF with form fields that needs to be appended to a different PDF file. Form field names must be unique, and it would not be possible to append the same template multiple times without changing the names.

Please note, the renaming of form fields requires the Document Editor component to be enabled for your license.

Reacting to Clicks on Form Elements

PdfActivity and PdfFragment include fully featured support for form filling. The default on-click behavior of form elements depends on their type:

• Taps on push buttons lead to an execution of the Action, which is set on the form element.
• Taps on signature fields start the signing flow.
• Taps on other fields lead to form element selection as well as to entering the form editing mode.

Default tap behavior can be fully customized by registering OnFormElementClickedListener via addOnFormElementClickedListener() on PdfFragment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

fragment.addOnFormElementClickedListener { formElement ->
    when {
        formElement.type == FormType.SIGNATURE -> {
            // Implement custom signature flow here.
            ...

            // By returning `true`, you intercept the event and prevent PSPDFKit from showing the signature picker itself.
            true
        }
        formElement.type == FormType.PUSHBUTTON -> {
            // Implement custom push button click handling.
            ...

            // By returning `true`, you intercept the event and prevent PSPDFKit from executing the button's action.
            true
        }
        else -> {
            // This click event is not interesting for us. Return `false` to let PSPDFKit handle this click event.
            false
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

fragment.addOnFormElementClickedListener(formElement -> {
    if (formElement.getType() == FormType.SIGNATURE) {
        // Implement custom signature flow here.
        ...

        // By returning `true`, you intercept the event and prevent PSPDFKit from showing the signature picker itself.
        return true;
    } else if (formElement.getType() == FormType.PUSHBUTTON) {
        // Implement custom push button click handling.
        ...

        // By returning `true`, you intercept the event and prevent PSPDFKit from executing the button's action.
        return true;
    }

    // This click event is not interesting for us. Return `false` to let PSPDFKit handle this click event.
    return false;
});

Reacting to Form Element Selection

Most form elements, with the exception of buttons and signature fields, can be selected for interactive editing. You can get notified about this via OnFormElementSelectedListener and OnFormElementDeselectedListener, both of which can be registered on PdfFragment.

Form selection also leads to entering the form element editing mode. You can react to its lifecycle by registering OnFormElementEditingModeListener on PdfFragment. If you want to learn more, refer to the custom form editing UI guide article that describes how to use this listener to integrate PSPDFKit’s form filling UI when using custom activities built around PdfFragment.