Form Creation

Since version 2019.5, PSPDFKit for Web has included support for creating and removing form fields from a document, provided the license includes the Form Designer feature.

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

Make sure to create a form field after its associated widget annotation is created, since widget annotations that don’t have a matching form field will be removed. When the widget annotation has been added to the document on the correct page, you can call PSPDFKit.Instance#createFormField().

You can add any kind of form field to a document. For more information about the available form field types, check out the PSPDFKit.FormFields documentation.

Add a Text Form Field

The following examples consolidate both creating the widget annotation and a TextFormField:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Create a new text form field.
const widget = new PSPDFKit.Annotations.WidgetAnnotation({
  pageIndex: 0,
  formFieldName: "MyFormField",
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 100,
    top: 75,
    width: 200,
    height: 80
  })
);
instance.createAnnotation(widget)
  .then(annotation => {
    instance.createFormField(
      new PSPDFKit.FormFields.TextFormField({
        name: "MyFormField",
        annotationIds: new PSPDFKit.Immutable.List([annotation.id]),
        value: "Text shown in the form field"
      }
    )
  });

It’s important to specify the formFieldName property on the widget annotation to link it to the name property of the corresponding form field that, in the case of the former example, is created immediately afterward. Likewise, the annotationIds property of the form field needs to be properly set with a PSPDFKit.Immutable.List of widget annotations linked to it.

Add Radio Buttons and Checkboxes

PSPDFKit.FormFields.RadioButtonFormField and PSPDFKit.FormFields.CheckboxButtonFormField may use more than a single widget annotation to represent the different available form field values. The current form field value can be retrieved from PSPDFKit.FormFields.FormField#value for any form field type except for PSPDFKit.FormFields.SignatureFormField:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
// Create two radio buttons and position them in the document.
// Note that both widget annotations have the same `formFieldName` value.
const radioWidget1 = new PSPDFKit.Annotations.WidgetAnnotation({
  pageIndex: 0,
  formFieldName: "MyFormField",
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 100,
    top: 100,
    width: 20,
    height: 20
  })
});
const radioWidget2 = new PSPDFKit.Annotations.WidgetAnnotation({
  pageIndex: 0,
  formFieldName: "MyFormField",
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 130,
    top: 100,
    width: 20,
    height: 20
  })
});
Promise.all([
  instance.createAnnotation(radioWidget1),
  instance.createAnnotation(radioWidget2)
]).then(([{ id: radioWidget1Id }, { id: radioWidget2Id }]) => {
  instance.createFormField(
    new PSPDFKit.FormFields.RadioButtonFormField({
      name: "MyFormField",
      annotationIds: new PSPDFKit.Immutable.List([
        radioWidget1Id,
        radioWidget2Id
      ]),
      options: new PSPDFKit.Immutable.List([
        new PSPDFKit.FormOption({
          label: "Option 1",
          value: "1"
        }),
        new PSPDFKit.FormOption({
          label: "Option 2",
          value: "2"
        })
      ]),
      defaultValue: "1"
    })
  );
});

Add Combo and List Boxes

PSPDFKit.FormFields.ComboBoxFormField and PSPDFKit.FormFields.ListBoxFormField allow you to select a value from multiple choices. The possible choices can be specified in the options property, and initially selected values can be set on the values property. They are available to both form field types since they inherit from PSPDFKit.FormFields.ChoiceFormField:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
const widget = new PSPDFKit.Annotations.WidgetAnnotation({
  pageIndex: 0,
  formFieldName: "MyFormField",
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 100,
    top: 75,
    width: 150,
    height: 60
  })
});

instance.createAnnotation(widget).then(annotation => {
  instance.createFormField(
    new PSPDFKit.FormFields.ComboBoxFormField({
      name: "MyFormField",
      annotationIds: new PSPDFKit.Immutable.List([annotation.id]),
      values: new PSPDFKit.Immutable.List(["orange"]), // initially selected value(s)
      options: new PSPDFKit.Immutable.List([
        // Available values.
        new PSPDFKit.FormOption({ label: "Apple", value: "apple" }),
        new PSPDFKit.FormOption({ label: "Banana", value: "banana" }),
        new PSPDFKit.FormOption({ label: "Orange", value: "orange" })
      ])
    })
  );
});

Update Form Fields and Widget Annotations

To update a form field, you can use the PSPDFKit.Instance#updateFormField() method. You can also use it to change the widget annotations associated with the form field.

The widget annotations can be updated using PSPDFKit.Instance#updateAnnotation(), just like any other annotation. Please see the Updating and Removing Annotations section of the Introduction to Annotations guide to learn more.

Remove Form Fields and Widget Annotations

You can easily remove any form field from a document using PSPDFKit.Instance#deleteFormField(). This call will also remove the associated widget annotations.