Introduction to Forms
Form support of PSPDFKit
PSPDFKit supports all form types specified by the PDF specification. We have to differentiate between the field objects and the annotation objects.
Type | Field Object | Annotation Object |
---|---|---|
Check, Radio and Pushbuttons | ButtonFormField |
ButtonFormElement |
List and Comboboxes | ChoiceFormField |
ChoiceFormElement |
Text | TextFormField |
TextFormElement |
Digital Signatures | SignatureFormField |
SignatureFormElement |
We differentiate between field objects and the 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 pre-fill 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 the document or 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 the field objects by using getFormFields()
method. Associated annotations can be retrieved by retrieving associated FormElement
s using 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 method getFormFieldWithFullyQualifiedName()
on FormProvider
. Annotation 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 by getSelectedFormElement
and exit form editing mode via exitCurrentlyActiveMode
. We also have 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
The field objects handle the state of the form field and offer appropriate methods to modify the form field. Each form field as 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 right type.
Annotation objects
Each field object has one or more annotations linked to it. The main purpose of the annotation object is to offer a graphical element on top of the PDF (see Introduction to Annotations).
JavaScript Support
PSPDFKit supports execution of JavaScript attached to a document, annotations, and especially 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 JavaScript Support article.
Renaming form field names
Form field names can't be renamed using FormField
or FormElement
instances, due to internal constraints. It is, however, possible to rename them using the PdfProcessor
. See 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, this requires the Document Editor component to be enabled for your license.