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 have to differentiate between field objects and annotation objects.

Retrieving Field and Annotation Objects

Using the PSPDFFormParser (which can be retrieved from a PSPDFDocument or a PSPDFDocumentProvider), 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 methods findAnnotationWithFieldName: and findFieldWithFullFieldName:.

Field Objects

Field objects handle the state of the form field and offer appropriate methods to modify 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 PSPDFFormField to the correct 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 the Introduction to Annotations guide).

JavaScript Support

PSPDFKit has limited support for executing 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.

Filling Forms

You can make a form read-only by removing the PSPDFAnnotationStringWidget value from PSPDFConfiguration.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 the document does not have the PSPDFDocumentPermissionsAnnotationsAndForms and PSPDFDocumentPermissionsFillForms document permissions, the result will be the same for the user, meaning they won’t be able to fill any form fields.

Renaming Form Field Names

Due to internal constraints, form field names can’t be renamed using a PSPDFFormField or PSPDFFormElement instance. It is, however, possible to rename them using the PSPDFProcessor. 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 this requires the Document Editor component to be enabled for your license.