docs(input): better accessibility in examples #11079

marcysutton · 2015-02-17T00:37:28Z

The input and ngModel docs examples have no labels or accessible error handling. They could do more to encourage accessibility best practices. This change does two things:

Adds labels to each input.
Wraps error messages with `role="alert" so they will announce in a screen reader.

Even though Angular 2.0 is coming soon, these docs will live on with the 1.0 project so it makes sense to show more accessible examples. (Better late than never.)

gkalpak · 2015-02-17T08:48:44Z

I wonder if it is a good idea to use the <label>...<input .../></label> form (see below) in order to avoid clattering the views (and avoid having to add id attributes to inputs that don't need it).

<label>
  Some label:
  <input type="text" name="input" ng-model="example.text" />
</label>

marcysutton · 2015-02-17T19:01:03Z

@gkalpak because this is primarily for developer education, I opted for explicit labels on purpose. A common accessibility problem is to leave off the for="" and not properly link the <label> and the <input> elements (or to leave off <label> entirely). Showing how they are linked together does more for developer education, which has been sorely lacking in Angular in the past.

You can read about implicit vs. explicit labeling vs. aria-labelledby here: http://www.paciellogroup.com/blog/2011/07/html5-accessibility-chops-form-control-labeling/

gkalpak · 2015-02-17T19:29:16Z

Interestingly enough, although the author seems to suggest using for / id instead of wrapping, the test results seem to indicate that wrapping is more reliable than for / id ! Do I miss something ?

marcysutton · 2015-02-17T21:38:29Z

The support differences look pretty minimal to me. This post is also from 2012, so take it with a grain of salt.

zamith · 2015-02-27T21:23:36Z

👍

pauljadam · 2015-02-27T21:44:40Z

+1 please fix a11y in the docs it's very very bad, all the angularJS books have not a11y just like the docs, wrapped labels are fine in my testing, yes it's less code and will look more readable, any a11y we can get the better!

ckundo · 2015-02-27T22:03:27Z

src/ng/directive/input.js

+           <label for="input">Single word:</label>
+           <input id="input" type="text" name="input" ng-model="example.text"
+                  ng-pattern="example.word" required ng-trim="false">
+           <span role="alert">


Does role=alert announce assertively/immediately? Is that the desired experience for a form validation?

When I tested it, it matched the speed that the visual message would come up in context to what you're typing...it was especially useful for validations related to input length, so you'd know exactly when the error occurred.

That's really cool! Good to know.

ckundo · 2015-02-27T22:21:54Z

Huge +1 in general. Great to see improved accessibility in the docs, and the role=alert pattern on form validations is super cool and a unique accessibility feature to Angular. The duplicate ids might be a blocker until resolved, but otherwise, I vote ship it 🚀!

marcysutton · 2015-02-27T22:36:59Z

Thanks for the feedback! I've simplified a lot of the labeling based on comments in this PR.

marcysutton · 2015-03-02T04:21:33Z

@ckundo @gkalpak I did a search for <input> and found a bunch more places that needed accessibility help, including stuff like ng-src in ng/directive/attrs.js, where the "good" example is missing an alt attribute:

The buggy way to write it:
 <img src="http://www.gravatar.com/avatar/{{hash}}"/>
The correct way to write it:
 <img ng-src="http://www.gravatar.com/avatar/{{hash}}"/>

Can you take another look if you get a chance? Thanks so much.

ckundo · 2015-03-02T16:33:22Z

src/ng/directive/input.js

-
+           <label>Single word:
+             <input type="text" name="input" ng-model="example.text"
+                  ng-pattern="example.word" required ng-trim="false">


Alignment with the attributes above is not quite right.

ckundo · 2015-03-02T16:38:52Z

Is there some guideline around line length? 80 characters is a sane guideline, but I don't know if the project adheres to that. @gkalpak do you know?

ckundo · 2015-03-02T16:40:38Z

@marcysutton it occurred to me that the role=alert changes might be better off in a separate PR. Do you think that change can be isolated?

ckundo · 2015-03-02T16:41:28Z

src/ng/directive/ngClass.js

       <hr>
       <p ng-class="style">Using String Syntax</p>
-       <input type="text" ng-model="style" placeholder="Type: bold strike red">
+       <label><input type="text" ng-model="style" placeholder="Type: bold strike red">


Is this missing a closing tag? </label>

It is indeed! Good catch.

gkalpak · 2015-03-02T16:59:14Z

src/ng/directive/attrs.js

@@ -144,7 +144,7 @@
 *
 * The correct way to write it:
 * ```html
- * <img ng-srcset="http://www.gravatar.com/avatar/{{hash}} 2x"/>
+ * <img ng-srcset="http://www.gravatar.com/avatar/{{hash}} 2x" alt="Description" />


I suggest the same change is made to the buggy way above.
Since this example is about src vs ngSrc, we don't want to distract the reader into thinking alt has anything to do with that.

Gotcha. That makes sense to me.

@gkalpak @marcysutton why not add the alt to both?

Done! Great suggestion.

ckundo · 2015-03-02T18:06:13Z

Besides the formatting fixes, I think the role=alert and a vs button concerns might be better in a separate PR, but that may be a little fussy. Also noted that the last file in the changes has new content, which was different. All the other changes should have no effect on the presentation of the page, so thought I'd raise it.

@marcysutton thanks a million for this work. Keep it up!

edit:
If the maintainers are ok accepting these all as one PR, by all means keep them together, it's less work to keep them together at this point.

gkalpak · 2015-03-02T20:21:23Z

It generally LGTM. Really great work ! 👍 @marcysutton

A couple of notes:

Alignment is not super-correct. It would nice to have everything align/indented consistently of course, but I can leave without as well :)
I prefer closing /> (with the /), but that seems to not be directly related to this PR (plus is a matter of personal preference anyway).
Although I generally agree that button is preferable to a (when used as a button), as do look better in certain cases. Couldn't we go with the as (e.g. for X "buttons") and put a role attribute or something. Since many people do use as anyway, it would be good to raise awareness around "doing it right" (if you have to).

marcysutton · 2015-03-02T21:06:16Z

Thanks again for your thorough review, this is awesome!

Edited alignment to be more consistent.
I did a find and replace for <br> in the files I had edited and changed any occurrences to <br/> since it was pretty easy.
The reason I changed the <a>s to <button>s is because they all had empty hrefs and were essentially doing the work of buttons (ng-click only, no routing). Adding role=button wouldn't negate the need for an empty href to make it a valid element. It's just easier to make them buttons. :)

If it's okay to leave this all in one branch, it will save me from having to do the work of splitting it up and creating additional PRs. In the future I'll try to break it up though. I know it's a big one! Thanks again for all your help.

ckundo · 2015-03-02T21:53:46Z

@marcysutton thanks, LGTM! 👍

marcysutton · 2015-04-11T23:40:39Z

src/ng/compile.js

-      <input ng-model="name"> <br>
-      <textarea ng-model="html"></textarea> <br>
+      <input ng-model="name"> <br/>
+      <textarea ng-model="html"></textarea> <br/>


These should have labels too. Oops! I'll fix them up later.

Closes angular#11079

googlebot added the cla: yes label Feb 17, 2015

marcysutton force-pushed the input-docs branch from a9c19fa to bad9343 Compare February 17, 2015 00:48

marcysutton force-pushed the input-docs branch from bad9343 to f102135 Compare February 27, 2015 20:12

ckundo reviewed Feb 27, 2015
View reviewed changes

marcysutton force-pushed the input-docs branch from f102135 to f97f931 Compare February 27, 2015 22:36

ckundo reviewed Mar 2, 2015
View reviewed changes

gkalpak reviewed Mar 2, 2015
View reviewed changes

marcysutton force-pushed the input-docs branch from 76cca2d to 27baeab Compare March 2, 2015 21:05

Narretz added this to the Backlog milestone Mar 8, 2015

Narretz added the type: docs label Mar 8, 2015

Marcy Sutton added 2 commits April 11, 2015 14:20

docs(): better accessibility in form examples

8da30b0

docs(): better accessibility in ng docs

448b3b5

marcysutton force-pushed the input-docs branch from 27baeab to 448b3b5 Compare April 11, 2015 21:23

marcysutton closed this in 2a156c2 Apr 11, 2015

marcysutton reviewed Apr 11, 2015
View reviewed changes

marcysutton deleted the input-docs branch April 14, 2015 18:29

netman92 pushed a commit to netman92/angular.js that referenced this pull request Aug 8, 2015

docs(): better accessibility in docs examples

05afb5f

Closes angular#11079

gkalpak mentioned this pull request Oct 5, 2015

docs(tutorial/10 - Event Handlers): describe your change... #12948

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(input): better accessibility in examples #11079

docs(input): better accessibility in examples #11079

marcysutton commented Feb 17, 2015

gkalpak commented Feb 17, 2015

marcysutton commented Feb 17, 2015

gkalpak commented Feb 17, 2015

marcysutton commented Feb 17, 2015

zamith commented Feb 27, 2015

pauljadam commented Feb 27, 2015

ckundo Feb 27, 2015

marcysutton Feb 27, 2015

ckundo Feb 27, 2015

ckundo commented Feb 27, 2015

marcysutton commented Feb 27, 2015

marcysutton commented Mar 2, 2015

ckundo Mar 2, 2015

ckundo commented Mar 2, 2015

ckundo commented Mar 2, 2015

ckundo Mar 2, 2015

marcysutton Mar 2, 2015

gkalpak Mar 2, 2015

marcysutton Mar 2, 2015

ckundo Mar 2, 2015

marcysutton Mar 2, 2015

ckundo commented Mar 2, 2015

gkalpak commented Mar 2, 2015

marcysutton commented Mar 2, 2015

ckundo commented Mar 2, 2015

marcysutton Apr 11, 2015

docs(input): better accessibility in examples #11079

docs(input): better accessibility in examples #11079

Conversation

marcysutton commented Feb 17, 2015

gkalpak commented Feb 17, 2015

marcysutton commented Feb 17, 2015

gkalpak commented Feb 17, 2015

marcysutton commented Feb 17, 2015

zamith commented Feb 27, 2015

pauljadam commented Feb 27, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ckundo commented Feb 27, 2015

marcysutton commented Feb 27, 2015

marcysutton commented Mar 2, 2015

Choose a reason for hiding this comment

ckundo commented Mar 2, 2015

ckundo commented Mar 2, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ckundo commented Mar 2, 2015

gkalpak commented Mar 2, 2015

marcysutton commented Mar 2, 2015

ckundo commented Mar 2, 2015

Choose a reason for hiding this comment