Drupal 7 page replaced by Building accessible forms
This document records how the new Building accessible forms page replaces the Drupal 7 page of the same name. It identifies retained concepts, corrected guidance, new coverage, and the archival text for the Drupal 7 page.
Page replaced
| Drupal 7 source | Current destination | Treatment |
|---|---|---|
| Building accessible forms | Building accessible forms | Rewritten for supported Drupal versions, Drupal Form API, WCAG 2.2, ATAG 2.0, current browser behavior, and complete-workflow testing. |
Detailed changes
| Drupal 7 guidance | Change | Reason |
|---|---|---|
| Place important information and instructions at the top of the form. | Retained and made more specific. | The replacement distinguishes general instructions from control-specific help and requires instructions before they are needed. |
| Indicate required fields with a red asterisk or an icon with alternative text. | Replaced with Drupal’s #required property and consistent text and programmatic state. |
A color, symbol, or icon is not sufficient by itself. Form API should generate the required state instead of theme-specific markup. |
Associate each label using matching for and id attributes. |
Retained through Drupal Form API. | The relationship remains correct, but module and theme developers should normally use #title rather than constructing labels and IDs manually. |
Use a title attribute if there is no room for a visible label. |
Removed. | The title attribute is an unreliable replacement for a persistent label and is unavailable to many keyboard, touch, speech-input, and magnification users. |
| Move labels off-screen when the design has no room. | Narrowed to exceptional cases using #title_display set to invisible. |
Visible labels are generally more usable. A visually hidden label is appropriate only when the rendered context still identifies the control and the result is tested. |
| Place labels close to their controls. | Retained and expanded. | The replacement requires the relationship to remain clear after zoom, reflow, and text-spacing changes. |
| Include the required-field indicator inside the label. | Handled through Form API output. | The current page avoids prescribing hand-written indicator markup that may conflict with Drupal’s generated label and state. |
| Place help text between the label and field. | Reframed around timing, proximity, and programmatic association. | Exact visual placement depends on the control and layout. The important outcome is that instructions are available before input and associated with the control. |
| Allow people to hide or show help text. | Removed as a general requirement. | Disclosure may be useful for lengthy optional help, but hiding required instructions can create a barrier. The decision depends on the form. |
Use fieldset and legend for related controls. |
Retained. | The replacement explains the programmatic grouping purpose and warns that visual borders or proximity are not equivalent. |
| Write legends and labels to avoid excessive repetition. | Retained in concise form. | Legends and labels must make sense together while remaining understandable individually. |
| Divide lengthy forms into pages or sections. | Retained and expanded. | The replacement adds progress information, state preservation, back navigation, privacy, and security considerations. |
| Summarize errors, link to affected fields, and highlight them. | Retained and expanded. | The replacement covers text identification, correction guidance, programmatic relationships, value preservation, focus, Ajax, and responsive layouts. |
| Allow confirmation or undo for important actions. | Retained and tied to applicable WCAG error-prevention requirements. | The original advice was correct but too general to guide legal, financial, data-changing, or other serious submissions. |
| General WebAIM forms link. | Replaced by the current W3C Forms Tutorial and Drupal Form API documentation. | The replacement prioritizes current primary and Drupal-specific sources. |
Coverage added
The current page adds:
- Drupal Form API properties and a current example.
- Native HTML controls and valid input types.
- WCAG autocomplete tokens and input-purpose identification.
- Persistent labels, placeholders, visible-label consistency, and speech input.
- Browser, client-side, Ajax, and server-side validation working together.
- Inline Form Errors module scope and limitations.
- Conditional fields, loading states, status messages, and dynamic requirements.
- Redundant-entry, accessible-authentication, password-manager, and copy-and-paste requirements.
- Timeouts, re-authentication, and data preservation.
- Custom-control semantics, states, keyboard behavior, and testing.
- ATAG responsibilities for authoring forms and their output.
- Complete-workflow testing with keyboard, zoom, reflow, autofill, invalid input, assistive technology, and disabled users.
- The limits of automated form testing.
Suggested archival text
Replace the body of the Drupal 7 Building accessible forms page with:
<p><strong>This Drupal 7 page is archived and no longer maintained.</strong> See <a href="https://www.drupal.org/docs/getting-started/accessibility/building-accessible-forms">Building accessible forms</a> for current guidance covering Drupal Form API, labels, instructions, validation, errors, dynamic forms, and testing. Drupal 7 reached end of life on January 5, 2025. See <a href="https://www.drupal.org/about/drupal-7/d7eol/partners">Drupal 7 End of Life</a> for migration resources and extended-support options.</p>Sources checked
- Building accessible forms, Drupal 7
- Drupal Form API
- Inline Form Errors module overview
- Web Content Accessibility Guidelines 2.2
- Authoring Tool Accessibility Guidelines 2.0
- W3C Forms Tutorial
- W3C Labeling Controls
- W3C Form Instructions
- W3C Validating Input
- Understanding Error Identification
- Understanding Redundant Entry