Technique PDF12:Providing name, role, value information for form fields in PDF documents

Applicability

Tagged PDF documents with interactive form fields.

This technique relates to:

Description

The objective of this technique is to ensure that assistive technologies can gather information about and interact with form controls in PDF content.

The types of PDF form controls are: text input field, check box, radio button, combo box, list box, and button.

Providing name, role, state, and value information for all form components enables compatibility with assistive technology, such as screen readers, screen magnifiers, and speech recognition software used by people with disabilities.

The PDF specification defines how name, role, and value are set for form controls in Section 12.7.4 (Field Types) of PDF 1.7 (ISO 32000-1), as shown in the following table. The Comments column explains how Adobe Acrobat Pro displays the corresponding information.

Interactive Form Dictionary Entries Used to Define Comments
FT Role Controls that share field type also use field flags to set the appropriate role. In Adobe Acrobat the role for form controls is set automatically.
TU Name In Adobe Acrobat the TU entry value is provided via the Tooltip field in the form control's Properties dialog. This should not be confused with the T entry which is defined as the Name in Acrobat's form control properties dialog - the name field in the Properties dialog is not used to provide the name for a control when read by assistive technologies.
CA Name (Pushbuttons only) In Adobe Acrobat the CA entry value is provided via the label field in the form control's Properties dialog.
V Value The Value entry is set by the user interacting with the control, where a value is needed.
DV Default Value In Adobe Acrobat the DV entry value can be set in the form control's Properties dialog.

The following table describes how the role, name, value, and state are defined for PDF form controls created using Adobe Acrobat Pro. Adobe LiveCycle Designer provides the same controls as well as several additional ones: see Example 2 below.

PDF form element Role (FT entry) Name (TU entry) Value (V entry) Configurable States
Text field Text /Tx Tooltip Default value (DV entry in field dictionary) can be set in the Properties dialog. Value is entered by user. Read Only, Required, Multiline, Password
Check box Check box /Btn Tooltip V entry is set to 'Yes' or 'No' depending on Checked state. Read Only, Required, Checked
Radio button Radio button /Btn (Field Flag set to 'Radio') Tooltip V entry is set to 'Yes' or 'No' depending on Checked state. Read Only, Required, Checked
Combo box Combo box /Ch (Field Flag set to 'Combo') Tooltip Default value (/DV) can be set in the Properties dialog. Value is determined by user selection. Read Only, Required
List box Drop-down list /Ch Tooltip Default value (/DV) can be set in the Properties dialog. Value is determined by user selection. Read Only, Required
Button Push button /Btn (Field Flag set to 'Pushbutton') Label (CA entry instead of TU entry) Push buttons do not have or require a value. Read Only, Required
Signature field Text /Sig Tooltip Default value (DV entry in field dictionary) can be set in the Properties dialog. Value is entered by user. Read Only, Required

Examples

Example 1: Specifying name, role, value and/or state for a form field using Adobe Acrobat 9 Pro

This example is shown with Adobe Acrobat Pro. There are other software tools that perform similar functions. See the list of other software tools in .

This example uses a check box for illustration; the procedure is the same for other form controls. In Form Editing mode:

  1. Access the context menu for the form field you are creating or modifying.
  2. Select the Properties... dialog for the form field.
  3. Specify the name by adding a value to the tool tip field. This will used by the accessibility API as the Name for the control and should usually be set to match the text used as a visual label for the control.
  4. Select the Options tab.
  5. Specify the default value and the default state, if appropriate.

The image below shows the Check Box Properties dialog, open in the General tab. (The Name field in the dialog is not needed for accessibility.)

General tab on the Check Box Properties dialog, showing name and tool tip fields for a check box

The image below shows the Check Box Properties dialog, open in the Options tab.

Options tab on the Check Box Properties dialog, showing value and state fields for a check box.

This example is shown in operation in the working example of specifying name, role, value using Acrobat Pro.

Example 2: Specifying name, value, and state for a form field using Adobe LiveCycle Designer ES 8.2.1

This example is shown with Adobe LiveCycle Designer. There are other software tools that perform similar functions. See the list of other software tools in .

In Adobe LiveCycle Designer, you use the Object Library to create form objects and the Object Palette to specify name, role, state or value for the object.

The following image shows the Object Palette.

LiveCycle Designer Object Library showing the form objects available for form creation.

The following three images show the tabs in the Object palette. In the first the Field tab is open for specifying the type (or role) of the field.

LiveCycle Designer Object palette, Field tab.

The next image shows the Value tab, with options that can be applied to the field.

LiveCycle Designer Object palette, Value tab options.

The third images shows the Binding tab, specifying the name of the field.

LiveCycle Designer Object palette, Binding tab.

This example is shown in operation in the working example of specifying name, role, value using LiveCycle Designer.

Example 3: Adding a checkbox in a PDF document using the /Btn field type

The following code fragment illustrates code that is typical for a simple check box field such as shown in Examples 1 and 2. This is typically accomplished by an authoring tool. 

1 0 obj
  << /FT /Btn     % Role
     /TU Retiree  % Name
     /V /Yes      % Value
     /AS /Yes
     /AP << /N << /Yes 2 0 R /Off 3 0 R>>
  >>
endobj

Other sources

No endorsement implied.

Tests

Procedure

  1. For the form control, verify that name, role, and value/state are specified by one of the following:

    • Use a screen reader to navigate to the form control and check that it can be activated or that its value can be changed. Verify that the name (tooltip) and role are announced.
    • Use a tool capable of showing the form field information to open the PDF document and verify that the form control has the correct name, role, value, and state (if appropriate) information.
    • Use a tool that exposes the document through the accessibility API, and verify that the form control has the correct name, role, value, and state (if appropriate) information.

Expected Results

  • #1 is true.