Update hook_help and DO docs for Inline Form Errors

This looks fine to me:

The Inline Form Errors module makes form errors more accessible and user friendly. It places the error messages next to the form elements themselves and adds a summary of all errors. For more information, see the <a href=":inline_form_error">online documentation for the Inline Form Errors module</a>.

Thanks @dmsmidt!

I applied the patch to the latest 8.4.x (no surprise there, considering how new it is), and I was also able to apply it to the latest 8.3.x. In both cases, the text displayed as expected.

However, while I think the wording is essentially fine as is, I think it can be improved slightly by changing it to be like this:

The Inline Form Errors module makes form errors more accessible and user friendly by placing the error messages next to the form elements themselves and displaying a summary of all errors at the top of the page. For more information, see the online documentation for the Inline Form Errors module.

It puts the "how" and the "what" in the same sentence with a connecting word, rather than having them in separate sentences. (I think it flows better when reading it that way.)
I also added a tad more clarification on a couple of points in the included text.

For your convenience, I've attached a patch that includes those changes.

What about something more like "...summary of all errors, usually displayed at the top of the page."?

I read through the other hot issues for this module, and I don't think I can be much help with them, so I can see what I can come up with for the d.o documentation, but I will need to spend some time familiarizing myself with the module and it's code, so I actually know what it does.
Also, I think the last two points are still a work in progress, so I might wait until they are done before writing much about them.

Not sure that the 'at the top of the page' is necessary.

Yes, presently d.o just has "Documentation for the experimental Drupal 8 Inline Form Errors module." here:
https://www.drupal.org/docs/8/core/modules/inline-form-errors

So should this be identical to the text in core, or longer?

Ok, this is just a place holder:
https://www.drupal.org/docs/8/core/modules/inline-form-errors

Really this content should all go in:
https://www.drupal.org/docs/8/core/modules/inline-form-errors/inline-for...

I've created a "What is IFE - for users?" & "IFE for Developers". Just added one screenshot as a placeholder. The text needs more work, but it is an improvement.

Okay, I removed the at the top part. Here's the updated patch for scrutiny.

I also removed that text from the documentation page.

Thanks!

I've tested oadaeh's patch from comment #11.

Before:

After:

The text has reference to the module being experimental has been removed as requested by the first part of the description. The online documentation also matches this text.

I would say that the patch is fine and can be committed.

But the second part of the summary, about adding more information, has not been done yet. For that reason I'm setting the issue back to needs work.

I've updated the summary showing what is still to do.

For the documentation pages, we could point out which parts of WCAG this helps with. That might help people who are tasked with evaluating Drupal.

Most specifically, it is Drupal 8's implementation of WCAG 2.0 technique G139: Creating a mechanism that allows users to jump to errors.

Overall, it helps with WCAG 2.0 Guideline 3.3 - Input Assistance, and to some extent Success Criterion 2.4.1 - Bypass Blocks.

Who benefits from Inline Form Errors?

• People who use screen magnifiers can find details of an error next to the input field which it applies to.
• Likewise users with small screens (such as mobile phones) can see the field and error message on screen together, without needing to scroll up and down.
• People who only use a keyboard can reach fields with errors with less effort.
• Screen reader users can find the error message near the relevant field.

release managers: some of this might help in the D8.4.0 release notes too?

The description in the IFE info file is misleading in a couple of ways.

type: module
name: Inline Form Errors
description: 'Adds WCAG 2.0 accessibility compliance for web form errors, 

1. WCAG 2.0 doesn't mention the word "compliance" anywhere - the word it uses is "conformance" (I know... the difference is lost on me).
2. The current description kind of implies that if you enable this module, then your website WILL be conformant with WCAG 2.0. That's too bold a claim IMO. All the module can do is help you achieve WCAG conformance, not guarantee it. Designers and themers could still make poor choices with regards to colour, or when customizing the message block, etc..
   In any case, our IFE approach is only one of the suggested ways to implement G139: Creating a mechanism that allows users to jump to errors, which in turn is considered an "additional advisory technique" for WCAG Guideline 3.3. It's not going to be the best approach for all situations, so we have #2856950: Add a possibility to disable inline form errors for a complete form to help developers who need to take a different approach.

</pedantic>

I'd suggest:
description: 'Places error messages adjacent to form inputs, for improved usability and acessibility.'

Updated the patch with new info file.

Updated the documentation, Added known limitations (considering HTML 5), Who benefits from Inline Form Errors?, How to disable IFE for a complete form and How to hide inline error messages for certain elements.

Some nit-picking:
"user-friendly" needs a hyphen.

Strictly speaking the module doesn't make the errors more accessible - it makes identifying the form errors more accessible and provides the different messages for different fields.

Maybe "The Inline Form Errors module makes it easier for users to identify at which form elements errors needs to be resolved by providing a summary of all errors and by placing the individual error messages next to the form elements themselves."

I would also suggest a sentences under "Uses"

Displaying error messages inline
If a user does not fill in a form correctly (for example by not filling out a required field), then a warning message with links to each individual form element is displayed at the top of the form. The individual error messages are displayed next to each form element.

Displaying error messages in browsers with HTML5 form validation
In browsers that support HTML5 form validation, users will first see the error messages generated by their browser. In this case, the inline form error messages are only displayed after the HTML5 validation errors have been resolved. 

I've made a patch.

+++ b/core/modules/inline_form_errors/inline_form_errors.info.yml
@@ -1,6 +1,6 @@
+description: 'Places error messages adjacent to form inputs, for improved usability and acessibility.'

acessibility > accessibility

I fixed the typo in the description.

Fixed 1 of #26.
Didn't understand 2 of #26.

Added patch for point 2 of #26.

Thanks pk188 and shashikant_chauhan.

Patch #27 didn't provide an interdiff, but I can confirm it addressed #26 part 1:

Remove 'at'.
Maybe say: 'which error(s)' instead of 'which error'.

Patch #28 did exactly what was asked in #26 part 2, but the grammar isn't quite right. It should say:

(for example by not filling out a required fields)

New patch attached.

Any updates on this issue?

Thanks for all the work on this module!

Patch #29 looks good, but I have a couple of nitpicks.

1. +++ b/core/modules/inline_form_errors/inline_form_errors.module
   @@ -15,7 +15,13 @@ function inline_form_errors_help($route_name, RouteMatchInterface $route_match)
   +      $output .= '<p>' . t('The Inline Form Errors module makes it easier for users to identify which error(s) needs to be resolved by providing a summary of all errors and by placing the individual error messages next to the form elements themselves. For more information, see the <a href=":inline_form_error">online documentation for the Inline Form Errors module</a>.', [':inline_form_error' => 'https://www.drupal.org/docs/8/core/modules/inline-form-errors']) . '</p>';
   

   Should the word "see" be replaced with "visit" to accommodate users with vision issues?

2. +++ b/core/modules/inline_form_errors/inline_form_errors.module
   @@ -15,7 +15,13 @@ function inline_form_errors_help($route_name, RouteMatchInterface $route_match)
   +      $output .= '<dd>' . t('In browsers that support HTML5 form validation, users will first see the error messages generated by their browser. In this case, the inline form error messages are only displayed after the HTML5 validation errors have been resolved.') . '</dd>';
   

   Should the word "see" be replaced with "visit" to accommodate users with vision issues?

Re: #31

Should the word "see" be replaced with "visit" to accommodate users with vision issues?

No. Generally it's OK to use everyday language like this; many style guides (etc) from disability organisations recommend it. For more info, see:

• Communicating effectively with people who are blind
• How to Communicate with Someone who is Blind
• What do you do when you see a blind person?
• When You Meet A Blind Person
• ... and plenty others.

The bracketed "error(s)" made the text less readable because it would require the verb in two different forms as well, so therefore it should be avoided in help texts like this where the goal is to give the user a fast understanding of what the module does. "One or more errors" would be the better way, if we really want to bring across that's it can be either, but in this case and context simply saying "errors" is a sufficiently clear option.

And while I was on it: I use the original patch name again because as long as we are building on somebody else's work, it is simply bad form to rename the patches - even if that's what your software might automatically do...

Fail was https://www.drupal.org/pift-ci-job/721893 (edit: #2891911: Random fail in Drupal\Tests\locale\Functional\LocaleTranslationUiTest::testStringTranslation).

However, there is a coding standards issue also shown there:

core/modules/inline_form_errors/inline_form_errors.module
line 19	Concat operator must be surrounded by a single space

coding standard issue resolved.

I don't think the interdiff is right, but the patch itself seems to be. :)

Since this was just a coding standards fix and https://www.drupal.org/pift-ci-job/721917 shows it is indeed resolved, this can be back at RTBC.

Okay, and now my committer review:

+++ b/core/modules/inline_form_errors/inline_form_errors.module
@@ -15,7 +15,13 @@ function inline_form_errors_help($route_name, RouteMatchInterface $route_match)
+      $output .= '<dd>' . t('If a user wrongly fills in form elements (for example by forgetting required fields), then a warning message with links to each individual form element is displayed at the top of the form. The individual error messages are displayed next to each form element.') . '</dd>';

I think this sentence needs work for two reasons:

• "Wrongly" is a bit emotionally loaded. "Incorrectly" or "Invalidly" might be better choices.
• It makes it sound like it means "If a user mistakenly entered something in a form field they should have left blank" (especially confusing with the parenthetical following) instead of "If a user entered something that's invalid or incorrect".

So, maybe it would be better to say something like:

If a user makes invalid entries in form elements...

Please feel free to improve that suggestion. :) Edit: I guess "entries" also implies that they filled out the fields, which is also confusing with the parenthetical. :) So please do improve on my suggestion.

The rest of the text looks good to me.

Thanks all!

"Fills out form elements in an invalid way" maybe?

Aside: I learned something new from #32; thanks @andrewmacpherson for those references!

Good point - users should not be blamed, but also "invalid" is a rather technical wording.

So how about this?
"If not all form elements are filled in correctly (for expample if a required field is left blank), then a warning message with links to each individual form element is displayed at the top of the form. The individual error messages are displayed next to each form element."

Changed the wording as proposed. I've also changed the patch name back to avoid confusion.

martin107, thanks for fixing the coding standard. In general, it is better to keep the original patch name because then it obvious that the next patch is a based on the previous one, and not something different or starting from scratch.

Thanks @ifrik. I like #44; removing "forgetting" is also a good improvement.

The sentence is getting a bit grammatically complicated though. Maybe:

When a form is not filled in correctly (for example, if a required field is left blank), a warning message with a link to each form element is displayed at the top of the form. The individual error messages are displayed next to each form element.

Or:

When a form is not filled in correctly (for example, if a required field is left blank), a warning message is displayed at the top of the form. This message links to the affected form elements, and individual error messages are displayed next to each form element.

I like #47 too, so here's an updated patch.

Alright, this looks good! Thanks @andrewmacpherson, @dmsmidt, and @ifrik.

Thanks @shashikant_chauhan for submitting a patch earlier. In this case I did not grant issue credit for #28 because the change was very small and made the sentence grammatically incorrect. Next time, for a better chance of receiving issue credit, I suggest carefully reading the patch you're updating and seeing what other changes might be needed for the update you make. You can help more by reading the whole issue carefully and participating in the overall discussion. I suggest the same for @pk188 as well.

I applied the patch and read the help page as a whole on an installed site. I also read over the updated documentation at https://www.drupal.org/docs/8/core/modules/inline-form-errors/inline-for... -- it's really nicely done! Great work, everyone. I also credited people who helped with the handbook page.

We're getting really close to the feature being stable. Yay!