Effective guidelines for PDF form field types

Types

This section explains how to use type declarations in Instant JSON records.

The optional keys are specified as follows:

{ optionalKey?: value; }

To reduce payload size, omit optional keys when their values are undefined.

Form fields

Form field types allow you to sync form fields across different devices.

Common types

There are some data types used by different form field types:

// Examples of common types of Instant JSON payloads.

// Additional action types.
formFieldEventTriggerType = "onChange"

// Additional action types for input events.
// K — Action to be performed when the user types a keystroke into a text field or combo box or modifies the selection in a scrollable list box.
formFieldInputEventTriggerType = "onInput"

// Form field flags.
formFieldFlags = ["readOnly", "required"]

// Form option.
formOption = {
  "label": "name",
  "value": "John Appleseed"
};

// Additional action types.
declare type FormFieldEventTriggerType =
	// V — When the field's value is changed. This action can check the new value for validity.
	| 'onChange'
		// C — Action to be performed to recalculate the value of a field.
		| 'onCalculate';

// Additional actions type for input events.
declare type FormFieldInputEventTriggerType =
	// K — Action to be performed when the user types a keystroke into a text field or combo box or modifies the selection in a scrollable list box.
	| 'onInput'
		// F — Action to be performed before the field is formatted to display its current value.
		| 'onFormat';

declare type FormFieldFlags = Array<
	'readOnly' | 'required' | 'noExport',
>;

declare type FormOption = {
	label: string,
	value: string,
};

Base form field shared properties

Some properties are common to all form fields and shared among all form field Instant types.

The following example shows a payload of this abstract type:

// Example of a base form field Instant JSON schema:

{
	"type": "pspdfkit/form-field/text",
	"pdfObjectId": 100,
	"annotationIds": ["100"],
	"name": "Email",
	"label": "Email", // Used to identify the field in the UI or for accessibility.
	"flags": ["required"]
}

declare type BaseFormField = {
	type:
		| 'pspdfkit/form-field/button'
		| 'pspdfkit/form-field/checkbox'
		| 'pspdfkit/form-field/combobox'
		| 'pspdfkit/form-field/listbox'
		| 'pspdfkit/form-field/radio'
		| 'pspdfkit/form-field/text'
		| 'pspdfkit/form-field/signature',
	pdfObjectId: number,
	annotationIds: Array<string>, // List of annotation IDs.
	name: string, // Unique identifiable name (fully qualified name).
	label: string, // Used to identify the field in the UI or for accessibility.
	flags?: FormFieldFlags,
};

Choice form field

Here’s an abstract type encompassing list box and combo box form fields:

// Example of the Instant JSON schema of a choice form field:

{
	"type": "pspdfkit/form-field/listbox",
	"pdfObjectId": 100,
	"annotationIds": ["101", "102"],
	"name": "Subscribe",
	"label": "Subscribe",
	"options": [
		{
			"label": "Yes",
			"value": "Yes"
		},
		{
			"label": "No",
			"value": "No"
		}
	],
	"multiSelect": false,
	"commitOnChange": false,
	"defaultValues": ["No"]
}

declare type ChoiceField = BaseFormField & {
	type: 'pspdfkit/form-field/listbox' | 'pspdfkit/form-field/combobox',
	options: Array<FormOption>,
	multiSelect: boolean,
	commitOnChange: boolean,
	defaultValues: Array<string>,
	additionalActions?: { [FormFieldEventTriggerType]: Action },
};

List box form field

// Example of the Instant JSON schema of a list box form field:

{
	"type": "pspdfkit/form-field/listbox",
	"pdfObjectId": 100,
	"annotationIds": ["101", "102"],
	"name": "Subscribe",
	"label": "Subscribe",
	"options": [
		{
			"label": "Yes",
			"value": "Yes"
		},
		{
			"label": "No",
			"value": "No"
		}
	],
	"multiSelect": false,
	"commitOnChange": false,
	"defaultValues": ["No"],
	"additionalActions": {
		"onInput": {
			"type": "goTo",
			"pageIndex": 3
		}
	}
}

declare type ListBoxFormField = ChoiceField & {
	type: 'pspdfkit/form-field/listbox',
	additionalActions?: {
		[
			| FormFieldEventTriggerType
			| FormFieldInputEventTriggerType]: Action,
	},
};

Combo box form field

// Example of the Instant JSON schema of a combo box form field:

{
	"type": "pspdfkit/form-field/combobox",
	"pdfObjectId": 100,
	"annotationIds": ["101", "102"],
	"name": "Subscribe",
	"label": "Subscribe",
	"options": [
		{
			"label": "Yes",
			"value": "Yes"
		},
		{
			"label": "No",
			"value": "No"
		}
	],
	"multiSelect": false,
	"commitOnChange": false,
	"defaultValues": ["No"],
	"edit": false,
	"doNotSpellCheck": false
}

declare type ComboBoxFormField = ChoiceField & {
	type: 'pspdfkit/form-field/combobox',
	edit: boolean,
	doNotSpellCheck: boolean,
};

Checkbox form field

// Example of the Instant JSON schema of a checkbox form field:

{
	"pdfObjectId": 100,
	"annotationIds": ["100"],
	"name": "Accept",
	"label": "Accept",
	"flags": ["required"],
	"options": [
		{
			"label": "Yes",
			"value": "Yes"
		},
		{
			"label": "No",
			"value": "No"
		}
	],
	"defaultValues": ["No"]
}

declare type CheckBoxFormField = BaseFormField & {
	type: 'pspdfkit/form-field/checkbox',
	options: Array<FormOption>,
	defaultValues: Array<string>,
	additionalActions?: { [FormFieldEventTriggerType]: Action },
};

Radio button form field

// Example of the Instant JSON schema of a radio button form field:

{
	"type": "pspdfkit/form-field/radio",
	"pdfObjectId": 100,
	"annotationIds": ["101", "102"],
	"name": "Color",
	"label": "Color",
	"options": [
		{
			"label": "Blue",
			"value": "Blue"
		},
		{
			"label": "Red",
			"value": "Red"
		}
	],
	"noToggleToOff": true,
	"radiosInUnison": false, // Not supported in Web.
	"defaultValue": "Blue"
}

declare type RadioButtonFormField = BaseFormField & {
	type: 'pspdfkit/form-field/radio',
	options: Array<FormOption>,
	noToggleToOff: boolean,
	radiosInUnison: boolean, // Not supported in Web.
	defaultValue: string,
};

Text form field

// Example of the Instant JSON schema of a text form field:

{
	"type": "pspdfkit/form-field/text",
	"pdfObjectId": 100,
	"annotationIds": ["100"],
	"name": "Name",
	"label": "Name", // Used to identify the field in the UI or for accessibility.
	"password": false,
	"maxLength": 100,
	"doNotSpellcheck": true,
	"doNotScroll": false,
	"multiLine": false,
	"comb": false,
	"defaultValue": ""
}

declare type TextFormField = BaseFormField & {
	type: 'pspdfkit/form-field/text',
	password: boolean,
	maxLength?: number,
	doNotSpellcheck: boolean,
	doNotScroll: boolean,
	multiLine: boolean,
	comb: boolean,
	defaultValue: string,
	additionalActions?: {
		[
			| FormFieldEventTriggerType
			| FormFieldInputEventTriggerType]: Action,
	},
};

Signature form field

// Example of the Instant JSON schema of a signature form field:

{
	"type": "pspdfkit/form-field/signature",
	"pdfObjectId": 100,
	"annotationIds": ["100"],
	"name": "Your signature",
	"label": "Your signature"
}

declare type SignatureFormField = BaseFormField & {
	type: 'pspdfkit/form-field/signature',
};

Button form field

// Example of the Instant JSON schema of a button form field:

{
	"type": "pspdfkit/form-field/button",
	"pdfObjectId": 100,
	"annotationIds": ["100"],
	"name": "A button",
	"label": "A button"
}

declare type ButtonFormField = BaseFormField & {
	type: 'pspdfkit/form-field/button',
};