Introduction to Forms
A PDF document may contain any number of form fields that allow a user to enter information on 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 user input via JavaScript.
Form Support in PSPDFKit
PSPDFKit supports all form types specified by the PDF specification. We have to differentiate between field objects and annotation objects.
Type | Field Object | Annotation Object |
---|---|---|
Check, Radio, and Push Buttons | ButtonFormField |
ButtonFormElement |
List and Combo Boxes | ChoiceFormField |
ChoiceFormElement |
Text | TextFormField |
TextFieldFormElement |
Digital Signatures | SignatureFormField |
SignatureFormElement |
Retrieve Field and Annotation Objects
Using the PDFFormParser
(which can be retrieved from a Document
or a PDFDocumentProvider
), you can fetch either the field objects or annotation objects using the formFields
or forms
property.
If you need to retrieve a specific field or annotation object, you can use the findAnnotation(withFieldName:)
and findField(withFullFieldName:)
methods.
Field Objects
Field objects handle the state of the form field and offer appropriate methods for modifying the form field. Each form field has a fullyQualifiedName
that can be used to identify and retrieve a specific field object.
You can query the type
property to find out which kind of field object it is. This allows you to easily cast the PDFFormField
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 the Introduction to Annotations guide).
JavaScript Support
PSPDFKit has limited support for executing JavaScript attached to a document, annotations, or forms. Most validation rules should work out of the box, but we’re constantly working on improving the engine and increasing our coverage of the PDF specification’s support for JavaScript.
Filling Forms
You can make a form read-only by removing the Annotation.Tool.widget
value from PDFConfiguration.editableAnnotationTypes
:
1 2 3 4 5 6 | let configuration = PDFConfiguration { builder in var editableAnnotationTypes = builder.editableAnnotationTypes editableAnnotationTypes?.remove(.widget) builder.editableAnnotationTypes = editableAnnotationTypes } let pdfController = PDFViewController(document: document, configuration: configuration) |
1 2 3 4 5 6 | PSPDFConfiguration *configuration = [PSPDFConfiguration configurationWithBuilder:^(PSPDFConfigurationBuilder *builder) { NSMutableSet *editableAnnotationTypes = [builder.editableAnnotationTypes mutableCopy]; [editableAnnotationTypes removeObject:PSPDFAnnotationStringWidget]; builder.editableAnnotationTypes = editableAnnotationTypes; }]; PSPDFViewController *pdfController = [[PSPDFViewController alloc] initWithDocument:document configuration:configuration]; |
If a document does not have the DocumentPermissions.annotationsAndForms
and DocumentPermissions.fillForms
document permissions, the result will be the same for the user, meaning they won’t be able to fill any form fields.
Rename Form Field Names
Due to internal constraints, form field names can’t be renamed using a PDFFormField
or FormElement
instance. It is, however, possible to rename them using the Processor
. See formFieldNameMappings
. You can simply pass in a dictionary 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 that renaming form field names requires the Document Editor component to be enabled for your license.