Form Creation

In PSPDFKit 7.0, we added programmatic support for creating and removing form fields from a document. This can be useful, for instance, when a PDF document needs to be digitally signed but doesn't contain a digital signature field.

Adding a Signature Form Field

A form field is the model representation of a visual form in the document. To be able to create a form field, you have to first create the form element (also known as widget annotation). For more information on the difference between a form field and a form element, please see Introduction to Forms. This works the same as adding any other annotation, as can be seen in Programmatically creating annotations.

When the annotation has been added to the document at the correct page, you can call insertedSignatureFieldWithFullyQualifiedName:documentProvider:formElement:error: on PSPDFSignatureFormElement. Note that this can fail and you need to check the return value.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
do {
    // Create a new signature form element.
    let signatureFormElement = PSPDFSignatureFormElement()
    // Position it in the document.
    signatureFormElement.boundingBox = CGRect(x: 100, y: 100, width: 100, height: 20)
    // Add it to the third page.
    signatureFormElement.pageIndex = 2
    // Add it to the document.
    document.add([signatureFormElement])

    // Insert a form field for the form element.
    let signatureFormField = try PSPDFSignatureFormField.insertedSignatureField(withFullyQualifiedName: "Digital Signature", 
                                                                                documentProvider: documentProvider, 
                                                                                formElement: signatureFormElement)
} catch {
    // Handle error
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Create a new signature form element.
PSPDFSignatureFormElement *signatureFormElement = [[PSPDFSignatureFormElement alloc] init];
// Position it in the document.
signatureFormElement.boundingBox = CGRectMake(100.f, 100.f, 100.f, 20.f);
// Add it to the third page.
signatureFormElement.pageIndex = 2;
// Add it to the document.
[document addAnnotations:@[signatureFormElement] options:nil];

// Insert a form field for the form element.
NSError *error;
PSPDFSignatureFormField *signatureFormField = [PSPDFSignatureFormField insertedSignatureFieldWithFullyQualifiedName:@"Digital Signature"
                                                                                                   documentProvider:documentProvider
                                                                                                        formElement:signatureFormElement
                                                                                                              error:&error];
if (!signatureFormField) {
    // Handle error.
}

You can add any kind of form field to the document, not just signature form fields. Please see Forms API overview for more information.

Adding Radio Buttons and Checkboxes

PSPDFButtonFormField with types PSPDFFormFieldTypeRadioButton and PSPDFFormFieldTypeCheckBox support more than one form element. In addition to that, they also have a onStateName. Each button can have a onStateName which represents the value when the button is checked. If it is unchecked, the value is always set to Off.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
do {
    // Create two radio buttons and position them in the document.
    let radio1 = PSPDFButtonFormElement()
    radio1.boundingBox = CGRect(x: 100, y: 100, width: 20, height: 20)
    radio1.pageIndex = 0
    let radio2 = PSPDFButtonFormElement()
    radio2.boundingBox = CGRect(x: 130, y: 100, width: 20, height: 20)
    radio2.pageIndex = 0

    // The `buttonValues` specify the radio buttons `onStateName`
    let buttonValues = ["RadioButton1", "RadioButton2"]

    let radioButtonFormField = try PSPDFButtonFormField.insertedButtonField(with: .radioButton, fullyQualifiedName: "RadioButton",
                                                                            documentProvider: documentProvider, 
                                                                            formElements: [radio1, radio2], 
                                                                            buttonValues: buttonValues)
} catch {
    // handle error
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Create two radio buttons and position them in the document.
PSPDFButtonFormElement *radio1 = [[PSPDFButtonFormElement alloc] init];
radio1.boundingBox = CGRectMake(100.f, 100.f, 20.f, 20.f);
radio1.pageIndex = 0;
PSPDFButtonFormElement *radio2 = [[PSPDFButtonFormElement alloc] init];
radio2.boundingBox = CGRectMake(130.f, 100.f, 20.f, 20.f);
radio2.pageIndex = 0;

// The `buttonValues` specify the radio buttons `onStateName`
NSArray<NSString *> *buttonValues = @[@"RadioButton1", @"RadioButton2"];

NSError *error;
PSPDFButtonFormField *radioButtonFormField = [PSPDFButtonFormField insertedButtonFieldWithType:PSPDFFormFieldTypeRadioButton 
                                                                            fullyQualifiedName:@"RadioButton" 
                                                                              documentProvider:document.documentProviders[0]
                                                                                  formElements:@[radio1, radio2]
                                                                                  buttonValues:buttonValues 
                                                                                         error:&error];
if (!radioButtonFormField) {
    // handle error
}

Removing Form Fields and Form Elements

You can easily remove any form field or form element from a document using the PSPDFFormParser. Simply either call removeFormElements:error: or removeFormFields:error:.