Programmatically associate error messages with inputs

Can you provide a sample of code with this and some instructions to repeat this?

We'll also want to know it's a core issue and not a webform issue.

Thanks!

Thanks for filing this @Lus. Adding IDs to error messages is a good idea. It already occurred to me that we can programmatically associate error messages to their inputs. I've been meaning to file a feature request for it myself but never got around to it. Lets flesh this out into a plan.

There are 3 ways of doing this:

1. Use aria-describedby. This has wide support, but isn't always treated as important by assistive tech (depends on user settings in some cases). Since inputs might have an associated error message AND some help text, it's probably a good idea to get the IDs in order so the error message is announced first. That's because when aria-describedby has multiple IDREFs, they are concatenated into a single string. Putting the error message first should reduce the likelihood of it being skipped.
2. Use aria-errormessage, introduced by the ARIA 1.1 recommendation. This doesn't have as wide support yet, but has the advantage of better semantics. So assistive tech (in theory) can treat error messages as things to be announced even if users don't want to hear descriptions.
3. A belt-and-braces approach using both aria-describedby and aria-errormessage. The first points at the error text and the description, and the second just points at the error. I've read encouraging things about this approach as a short-term approach. It works very well, at the cost of some extra verbosity in browser/screenreader combinations which support both properties. Later when support for aria-errormessage is more widespread, we can change to keeping the description and error separated.

Bonus points if we can make this work regardless of whether inline form errors module is enables. Programmatic associations like this don't depend on DOM order. It will be great if screen reader users can get the error message even though it's far away at the top of the page.

Updating the vague title.

Also, this probably isn't specific to webform or inline form errors module. It'll probably be best to make it work at lower level in Drupal's Form API.

Well, I meant in particular the inline form errors, since the drupal Error messages (at the top) are in fact a list of errors in a form of anchor links. So we would add an ID for every <li> ?

You only get the list of anchor links when the Inline Form Errors module is enabled. That's not what I meant.

When Inline Form Errors module is disabled, you actually get the error messages at the top of the page.

So what I meant is, the error message can be associated by IDREF whether it is near the form element, or far away at the top of the page.

I'll give your code a closer look soon.

@Lus,
I got this error:

Error: Call to a member function renderPlain() on null in Drupal\Core\Form\FormErrorHandler->displayErrorMessages() (line 99 of /home/myuser/www/myproject/web/core/lib/Drupal/Core/Form/FormErrorHandler.php)

Thanks.

Hi @Lus,
Yes, a Webform with Ajax enabled.
And yes, Inline Form Errors module is activated.

A contrib module is trying this too: A11Y: Form helpers.

It's worth studying, but it assumes Inline Form Errors module is enabled. This core issue should still seek to make the IDREFs work regardless of whether the Inline Form Errors module is enabled.

@Lus - Thanks for working on this. I see many more patches have been posted since I was last here. I haven't tested or studied them in depth, but will try to do that soon.

Do you know how to create an interdiff? Those help reviewers follow the progress of a patch as it evolves.

I skimmed the latest patch from #24....

1. @@ -40,10 +68,47 @@ public function handleFormErrors(array &$form, FormStateInterface $form_state) {
   
   +          '#wrapper_attributes' => [

   I like the idea of using #wrapper_attributes, because that's flexible enough for any wrapper.

2. @@ -40,10 +68,47 @@ public function handleFormErrors(array &$form, FormStateInterface $form_state) {
   
   +            'id' => $id . '--status-message'

   Nitpick: we are talking about errors, so maybe the ID suffix would be better as '--error-message'. It would make the markup easier to understand.

3. @@ -162,6 +227,11 @@ protected function setElementErrorsFromFormState(array &$form, FormStateInterfac
   
   +      $elements['#attributes']['aria-describedby'] = $elements['#id'] . '--status-message';

   This looks fragile. Remember that the aria-describedby attribute accepts an ID reference list. In other words, it can point to multiple IDs. So it should be treated as an array of values, and we are adding an additional IDREF.

   A majority of our inputs will already have another IDREF pointing to the description. See Drupal\Core\Form\FormBuilder::doBuildForm() for this. We don't want to over-write the description IDREF.

   What we're aiming for is something like this: aria-describedby="edit-foo--error-message edit-foo--description". The intended effect is that screen readers will announce the error message AND still announce the extra help description for the input. The error message is the most important, so that comes first. We'll need something like this:

   array_unshift($elements['#attributes']['aria-describedby'], $elements['#id'] . '--error-message';

   A snag is that the existing logic in Drupal\Core\Form\FormBuilder::doBuildForm() also makes this mistake, and assumes there will only be a single IDREF value. I'll file a separate issue about that, because it's a wider problem than error messages IDs.

I have updated patch.
Kindly review patch.

Trying to fix latest patch

Fix more test cases, Please review.

One hard thing is going to be multi-value fields. Errors on sub-items like street name or telephone number are set on the address or telephone parent elements. I don't think putting the aria-describedby on the parent elements is going to be useful for screen readers and it's hard to discern which child element the error applies to.

Yes, there are certainly going to be special cases for some kinds of complex Form API elements. Address, image fields, various date/time fields, and perhaps Form API '#type' => '#checkboxes'. There is already some special-case code for some of these to manage labels and descriptions.

"Multi-value" fields are different from these.

I have created an issue fork. I started with the patch in #34. I made the new id values both end in --error-message (one was still --status-message). I made it use aria-errormessage instead of aria-describedby. I have it set aria-invalid where aria-errormessage is set (this was already being set elsewhere later, but it makes sense to ensure that both are set together).

In testing from Webform, it still doesn't set the --error-message in the id of the error. This will probably require a change to form-element.html.twig.

1. +++ b/core/lib/Drupal/Core/Form/FormErrorHandler.php
   @@ -14,6 +15,34 @@ class FormErrorHandler implements FormErrorHandlerInterface {
   +    // Instantiates this form class.
   ...
   +      // Load the service required to construct this class.
   

   These comments about DI aren't necessary.

2. +++ b/core/lib/Drupal/Core/Form/FormErrorHandler.php
   @@ -39,10 +68,34 @@ public function handleFormErrors(array &$form, FormStateInterface $form_state) {
   -    // Loop through all form errors and set an error message.
   

   We've lost this comment about setting an error message.

Re-rolled the patch in #34, addressed the changes specified in #43 and added a missing use Symfony\Component\DependencyInjection\ContainerInterface; statement in core/lib/Drupal/Core/Form/FormErrorHandler.php file.

Thank you!

Thanks!

Updated merge request with changes in #44.

I'm reviewing this issue (both path #44 and MR1063) and I see correctly the new aria-describedby or aria-errormessage but they link to non-existent ID.
The error message only has this content:

<div class="form-item--error-message">
    <strong>This field is mandatory.</strong>
</div>

Is there something that needs to be set up ?

THere's been loads of activity since the rtbc in #45 so this issue can't really be RTBC as this activity has not been reviewed.

Plus I've just added some more comments to the code.

The issue summary could do with an update to outline the problem and how it is being fixed.

The MR also seems light on test coverage - I would expect some test coverage of the new HTML that is being output.

Thanks for the patch, but i am unable to see the id for the error message after applying this patch (aria-described-by attribute is added correctly though to the element that didnt validate correctly). Am I missing anything here?

Tagging for 3.3.1.

Rebased and address the feedback from alex.

Unfortunately this doesn't work. It was really broken and the ID attachement didn't seem to work at all. I fixed that but it only works for simple elements. When trying to attach to groups like radios or checkboxes, the ID in displayErrorMessages is the collection, but the ID in setElementErrorsFromFormState is the ID of the specific input and these don't match.

For example testing on umami search,

edit-type--error-message

but the element is

edit-type-article

referencing

edit-type-article--error-message

Definitely needs a lot of tests.

got some tests in place that identify some of the pending issues. not passing because we've got some hard problems to solves still.

I have rebased both merge requests.

I rebased !1063.

What's the difference between the two MRs? It looks like they've both been kept up-to-date.

Updated 7080 to fix the merge conflict in the test

And as for the differences between the branches looks like 7080 takes care of template changes and other items required for the new attributes to work. The other has the base changes but not template changes.

In 1063 i added the aria-errormessage in RenderElementBase too, because I wasn't getting it in de form output else.

The patch works, but it shows two duplicate error messages in my theme.

Hid 2 of 3 of visible branches. The one I have left visible (active one) contains the most changed files. So I assume it built on the other MR which I have hidden. The '11.x' MR contained no changes so seems like it should definitely be hidden.

Seem to have fixed one PHPSTAN/ PHPCS error. There is still one PHPSTAN error:

https://git.drupalcode.org/issue/drupal-3083103/-/jobs/9376769

I just created MR from branch 3083103-improve-error-accessibility against 3083103-programmatically-associate-error-11 with improvements to the current patch. The changes address three areas:

1. Error wrappers: The templates were using hard-coded <div> wrappers — fieldset and details had no class at all, and the id was built directly from element['#id']in Twig rather than passed from preprocess. Now FormPreprocess passes error_id as a template variable, all three templates use create_attribute() with consistent form-item--error-message class, and errors are no longer blindly suppressed.
2. Error placement: fieldset and details placed errors before children, while form-element placed them after. Standardized all three to render errors after children, before the description.
3. Accessibility: aria-errormessage alone is not sufficient — VoiceOver+Safari and TalkBack don't support it. Added aria-describedby as a fallback (with deduplication to avoid duplicates when both FormErrorHandler and RenderElementBase set it). Also strips aria-errormessage and aria-invalid from child radios/checkboxes to prevent invalid attributes on individual inputs. Introduced #error_id property so elements can override the default ID convention. Fixed displayErrorMessages() to use a proper render array (#type container) instead of raw #prefix/#suffix HTML.
4. Also fixed the unit test — the renderer mock was set up for renderPlain but the code calls renderInIsolation, and the Prophecy renderer wasn't initialized in setUp().

thank you! could you please also create a MR for the feature branch (3083103-improve-error-accessibility) you've created for your changes so it could become testable?

Is this not what inline form errors does?

@smustgrave

I tested IFE for this yesterday.

My observation was that IFE doesn't currently link invalid fields to error messages with aria-describedby, though it was supposed to.

Use ARIA described-by to semantically associate the error message with the field in a machine-readable, assistive technology-friendly way.

I saw that the MR here touches IFE tests, so am just about to test it. Postponing until there's more data.

Here's what I got for required errors with a hacked version of the form_test module's #required test form.

Test cases

Note: I merged main into the MR for these tests (locally only; did not push to gitlab).

1. On main, without Inline Form Errors
2. With MR, without Inline Form Errors
3. On main, with Inline Form Errors
4. With MR, with Inline Form Errors

Result

So far, without Inline Form Errors, the MR appears to work as expected.

I still observed that Inline Form Errors doesn't do this currently, and AFAICT the MR fixes it. See the result details for the markup.

Discussion

Questions for the accessibility experts:

Do we want to use aria-errormessage instead of aria-describedby?

In #accessibility Slack yesterday, the recommendation was to use aria-describedby:

Yes, aria-errormessage has more support than it used to but there are still significant gaps. Prepending error messages to the referenced aria-describedby is still the best option.

Adrian Roselli says this about aria-errormessage as of Aug 15, 2023:

• The message associated via aria-errormessage paired with a live region is generally not exposed onblur;
• The message associated via aria-errormessage is generally not exposed when navigating through fields;
• The virtual cursor is the only certain way to encounter a message associated using aria-errormessage.

If we do go with aria-describedby, is it sufficient to prepend the error message id to aria-describedby instead of prepending the error message itself to the description text?

Either way, the pipeline is failing. This also could use a rebase to bring in #1797438: HTML5 validation is preventing form submit and not fully accessible for easier manual testing.

With regard to Inline Form Errors, this might be blocked on #3557245: Use $element['#attributes]['id'] instead of $element['#id'] to create a link anchor. Not sure yet.

Result details

1. On main, without Inline Form Errors

Page-top errors markup

<div data-drupal-messages="">
  <div role="contentinfo" aria-label="Error message">
    <div role="alert">
      <h2 class="visually-hidden">Error message</h2>
      Enter a name.
    </div>
  </div>
</div>

Field markup

<div
  class="js-form-item form-item form-type-textfield js-form-type-textfield form-item-textfield js-form-item-textfield">
  <label for="edit-textfield" class="js-form-required form-required">Name</label>
  <input data-drupal-selector="edit-textfield" aria-describedby="edit-textfield--description" type="text"
    id="edit-textfield" name="textfield" value="" size="60" maxlength="128" class="form-text required error"
    required="required" aria-invalid="true">

  <div id="edit-textfield--description" class="description">
    Description for name field
  </div>
</div>

2. With MR, without Inline Form Errors

Page-top errors markup

<div data-drupal-messages="">
  <div role="contentinfo" aria-label="Error message">
    <div role="alert">
      <h2 class="visually-hidden">Error message</h2>
      <div id="edit-textfield--error-message">Enter a name.</div>
    </div>
  </div>
</div>

Field markup

<div
  class="js-form-item form-item form-type-textfield js-form-type-textfield form-item-textfield js-form-item-textfield">
  <label for="edit-textfield" class="js-form-required form-required">Name</label>
  <input data-drupal-selector="edit-textfield" aria-describedby="edit-textfield--description"
    aria-errormessage="edit-textfield--error-message" aria-invalid="true" type="text" id="edit-textfield"
    name="textfield" value="" size="60" maxlength="128" class="form-text required error"
    required="required">

  <div id="edit-textfield--description" class="description">
    Description for name field
  </div>
</div>

3. On main, with Inline Form Errors

Page-top errors block

<div data-drupal-messages="">
  <div role="contentinfo" aria-label="Error message">
    <div role="alert">
      <h2 class="visually-hidden">Error message</h2>
      1 error has been found:
      <ul class="item-list__comma-list">
        <li><a href="#edit-textfield">Name</a></li>
      </ul>
    </div>
  </div>
</div>

Field markup

<div
  class="js-form-item form-item form-type-textfield js-form-type-textfield form-item-textfield js-form-item-textfield form-item--error">
  <label for="edit-textfield" class="js-form-required form-required">Name</label>
  <input data-drupal-selector="edit-textfield" aria-describedby="edit-textfield--description" type="text"
    id="edit-textfield" name="textfield" value="" size="60" maxlength="128" class="form-text required error"
    required="required" aria-invalid="true">

  <div class="form-item--error-message">
    Enter a name.
  </div>
  <div id="edit-textfield--description" class="description">
    Description for name field
  </div>
</div>

4. With MR, with Inline Form Errors

Page-top errors markup

<div data-drupal-messages="">
  <div role="contentinfo" aria-label="Error message">
    <div role="alert">
      <h2 class="visually-hidden">Error message</h2>
      1 error has been found: <ul class="item-list__comma-list">
        <li><a href="#edit-textfield">Name</a></li>
      </ul>
    </div>
  </div>
</div>

Field markup

<div
  class="js-form-item form-item form-type-textfield js-form-type-textfield form-item-textfield js-form-item-textfield form-item--error">
  <label for="edit-textfield" class="js-form-required form-required">Name</label>
  <input data-drupal-selector="edit-textfield" aria-describedby="edit-textfield--description"
    aria-errormessage="edit-textfield--error-message" aria-invalid="true" type="text" id="edit-textfield"
    name="textfield" value="" size="60" maxlength="128" class="form-text required error"
    required="required">

  <div id="edit-textfield--error-message" class="form-item--error-message">
    Enter a name.
  </div>
  <div id="edit-textfield--description" class="description">
    Description for name field
  </div>
</div>

I still think the fix should be in the inline_form_error module, especially since the test coverage is located there. Shouldn't add test coverage for a module we aren't fixing :)

Also by putting there we could do away with the service and template updates probably, or least change it to an attributes array so the module could dynamically add the ID without much twig change, which need a CR.