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.

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.