Section:

Fields and Widgets

Form fields and widget annotations are the two main components of a form workflow. Form fields represent the data entry points for users, while widget annotations serve as the visual elements that encapsulate these fields, providing interactive components like checkboxes, text boxes, and dropdown menus. The sections below cover some of the common use cases when working with form fields and widgets.

Creating form fields

Creating form fields requires you to define the value and type of the field, along with some optional parameters. You can find a detailed explanation on field creation by visiting Creating form fields. Below is a simple example of a text field.

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { Annotations, annotationManager } = instance.Core;
4    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
5    annotationManager.getFieldManager().addField(field);
6  });

Related Links

Setting widget flags

WidgetFlags allow you to define certain behaviors of a field and its associated widgets. The available flags may change over time, but these are the currently supported WidgetFlags. A WidgetFlags object can be passed to a form field at creation to define the default state of the field.

Apryse Docs Image

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4    const { WidgetFlags } = Annotations;
5
6    const flags = new WidgetFlags();
7    flags.set(WidgetFlags.MULTILINE, true);
8    flags.set(WidgetFlags.REQUIRED, true);
9
10    const field = new Annotations.Forms.Field('Field Name', {
11      flags
12      type: 'Tx'
13    });
14
15    annotationManager.getFieldManager().addField(field);
16  });

Related Links

Updating widget flags

You can update WidgetFlags by accessing the WidgetFlags that have been added to the field. This can be done by calling the set method. All WidgetFlags accept a boolean value to determine the desired state.

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4    const { WidgetFlags } = Annotations;
5
6    // Create a field with READ_ONLY flag set to true.
7    const flags = new WidgetFlags();
8    flags.set(WidgetFlags.READ_ONLY, true);
9    const field = new Annotations.Forms.Field('Field Name', {
10      flags
11      type: 'Tx',
12    });
13
14    // Modify the flag to set READ_ONLY to false.
15    field.flags.set(WidgetFlags.READ_ONLY, false);
16    annotationManager.getFieldManager().addField(field);
17  });

Related Links

Updating field values

The most consistent way to update a field's value is to call the setValue method on the field object. This will result in the field being updated along with all of the associated widgets.

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4
5    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
6
7    field.setValue("Hello World");
8    annotationManager.getFieldManager().addField(field);
9  });

Related Links

Highlighting Widgets

Form field highlighting is enabled by default to visually indicate interactive fields in the UI. This applies to:

  • Text fields
  • Choice fields
  • Signature fields
  • Checkboxes
  • Radio buttons

However, highlight is not applied to push buttons. Highlighting is a UI-only visual cue and does not change the underlying widget styling or appearance.

Form Fields highlighted

You could choose to enable or disable the highlight with the following APIs:

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4
5    const annotationManager = instance.Core.documentViewer.getAnnotationManager();
6    const fieldManager = annotationManager.getFieldManager();
7  
8    // Enable/disable standard widget highlighting
9    fieldManager.enableWidgetHighlighting();
10    fieldManager.disableWidgetHighlighting();
11  });

Related Links

Configuring multiple widgets for a single field

The PDF specification allows multiple widgets to be associated with a single field, ensuring consistency across these widgets. For instance, a user may want to enter their first name only once and have it shown in multiple places in the form. We support this functionality by passing the same field into different widgets during object creation.

Apryse Docs Image

JavaScript

1function createWidget (field, options, x, y, Annotations) {
2  let newWidget = new Annotations.TextWidgetAnnotation(field, options);
3  newWidget.PageNumber = 1;
4  newWidget.X = x;
5  newWidget.Y = y;
6  newWidget.Width = 50;
7  newWidget.Height = 20;
8  return newWidget;
9}
10
11WebViewer(...)
12  .then(instance => {
13    const { annotationManager, Annotations } = instance.Core;
14
15    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
16
17    const widgetAnnot = createWidget(field, {}, 100, 100, Annotations);
18    const widgetAnnot02 = createWidget(field, {}, 200, 200, Annotations);
19
20    annotationManager.getFieldManager().addField(field);
21    annotationManager.addAnnotations([widgetAnnot, widgetAnnot02]);
22    annotationManager.drawAnnotationsFromList([widgetAnnot]);
23  });

Related Links

Configuring widgets across multiple pages

You can also link widget annotations across multiple pages to a single form field. The same update behavior mentioned in the previous section applies. In the example below, we extend the createWidget function to accept a Page argument. Finally, we attach multiple cross-page widgets to a single field. This allows you to have shared fields across multiple PDF pages, streamlining data entry and ensuring that updates to one widget are automatically propagated to the other widgets that relate to the same field.

Apryse Docs Image

JavaScript

1function createWidget (field, options, x, y, Annotations, page = 1) {
2  let newWidget = new Annotations.TextWidgetAnnotation(field, options);
3  newWidget.PageNumber = page;
4  newWidget.X = x;
5  newWidget.Y = y;
6  newWidget.Width = 50;
7  newWidget.Height = 20;
8  return newWidget;
9}
10
11WebViewer(...)
12  .then(instance => {
13    const { annotationManager, Annotations } = instance.Core;
14
15    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
16
17    const widgetAnnot01_page1 = createWidget(field, {}, 100, 100, Annotations);
18    const widgetAnnot02_page1 = createWidget(field, {}, 200, 200, Annotations);
19    const widgetAnnot03_page2 = createWidget(field, {}, 200, 200, Annotations, 2);
20    const widgetAnnot04_page3 = createWidget(field, {}, 200, 200, Annotations, 3);
21
22    const widgetsToAdd = [
23      widgetAnnot01_page1,
24      widgetAnnot02_page1,
25      widgetAnnot03_page2,
26      widgetAnnot04_page3
27    ];
28
29    annotationManager.getFieldManager().addField(field);
30    annotationManager.addAnnotations(widgetsToAdd);
31    annotationManager.drawAnnotationsFromList(widgetsToAdd);
32  });

Related Links

Additional field properties

The field has optional additional properties that can further define its behavior.

Max length

This defines the maximum number of characters that can be inputted into the field.

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4
5    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
6    field.set({ maxLen: 5 });
7
8    annotationManager.getFieldManager().addField(field);
9  });

Related Links

Tooltips

This defines the tooltip that will be displayed when a user hovers over the widget annotation.

Apryse Docs Image

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4
5    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
6    field.set({ tooltipName: `I'm a tooltip!` });
7
8    annotationManager.getFieldManager().addField(field);
9  });

Related Links

Options

Options are only applicable to list box and combo box field types. They define the possible values a user can select when interacting with these fields.

Apryse Docs Image

JavaScript

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4
5    const options = [
6      { value: 'option1', displayValue: '1' },
7      { value: 'option2', displayValue: '2' },
8      { value: 'option3', displayValue: '3' },
9      { value: 'option4', displayValue: '4' },
10    ];
11
12    // Creates a listbox field. WidgetFlags.COMBO is false by default, so no `flags` object is needed.
13    field = new Annotations.Forms.Field('Field Name', {
14      type: 'Ch',
15      options
16    });
17
18    annotationManager.getFieldManager().addField(field);
19  });

Related Links

Checkbox Widgets and Appearances

Checkbox widgets can also have appearances like Annotations. However, some files can have appearances that don’t match their values. If the value or appearance state is set to On, then the checkbox will be checked in WebViewer.

Checkbox Value

Appearance

Rendered State

On

On

On

Off

Off

Off

On

Off

On

Off

On

On

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales