Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit e260fdc

Browse files
author
Marcy Sutton
committedNov 14, 2014
docs(ngAria): Add Usage Details and Examples
1 parent ffb14ae commit e260fdc

File tree

3 files changed

+310
-48
lines changed

3 files changed

+310
-48
lines changed
 

‎docs/content/api/index.ngdoc

+21
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,27 @@ or JavaScript callbacks.
161161
</tr>
162162
</table>
163163

164+
## {@link ngAria ngAria}
165+
166+
Use ngAria to inject common accessibility attributes into directives and improve the experience for users with disabilities.
167+
168+
<div class="alert alert-info">Include the **angular-aria.js** file and set ngAria as a dependency for this to work in your application.</div>
169+
170+
<table class="definition-table spaced">
171+
<tr>
172+
<td>
173+
{@link ngAria#service Services}
174+
</td>
175+
<td>
176+
<p>
177+
The {@link ngAria.$aria $aria} service contains helper methods for applying ARIA attributes to HTML.
178+
<p>
179+
<p>
180+
{@link ngAria.$ariaProvider $ariaProvider} is used for configuring ARIA attributes.
181+
</p>
182+
</td>
183+
</tr>
184+
</table>
164185

165186
## {@link ngResource ngResource}
166187

‎docs/content/guide/accessibility.ngdoc

+207-26
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,23 @@ assistive technologies used by persons with disabilities.
1212

1313
##Including ngAria
1414

15-
Using ngAria is as simple as requiring the ngAria module in your application. ngAria hooks into
15+
Using {@link ngAria ngAria} is as simple as requiring the ngAria module in your application. ngAria hooks into
1616
standard AngularJS directives and quietly injects accessibility support into your application
1717
at runtime.
1818

1919
```js
2020
angular.module('myApp', ['ngAria'])...
2121
```
2222

23+
###Using ngAria
24+
Most of what ngAria does is only visible "under the hood". To see the module in action, once you've
25+
added it as a dependency, you can test a few things:
26+
* Using your favorite element inspector, look for ngAria attributes in your own code.
27+
* Test using your keyboard to ensure `tabindex` is used correctly.
28+
* Fire up a screen reader such as VoiceOver to listen for ARIA support.
29+
[Helpful screen reader tips.](http://webaim.org/articles/screenreader_testing/)
30+
31+
##Supported directives
2332
Currently, ngAria interfaces with the following directives:
2433

2534
* <a href="#ngmodel">ngModel</a>
@@ -31,7 +40,7 @@ Currently, ngAria interfaces with the following directives:
3140

3241
<h2 id="ngmodel">ngModel</h2>
3342

34-
Most of ngAria's heavy lifting happens in the [ngModel](https://docs.angularjs.org/api/ng/directive/ngModel)
43+
Most of ngAria's heavy lifting happens in the {@link ngModel ngModel}
3544
directive. For elements using ngModel, special attention is paid by ngAria if that element also
3645
has a a role or type of `checkbox`, `radio`, `range` or `textbox`.
3746

@@ -47,15 +56,76 @@ attributes (if they have not been explicitly specified by the developer):
4756

4857
###Example
4958

50-
```html
51-
<md-checkbox ng-model="val" required>
52-
```
53-
54-
Becomes:
55-
56-
```html
57-
<md-checkbox ng-model="val" required aria-required="true" tabIndex="0">
58-
```
59+
<example module="ngAria_ngModelExample" deps="angular-aria.js">
60+
<file name="index.html">
61+
<style>
62+
[role=checkbox] {
63+
cursor: pointer;
64+
display: block;
65+
}
66+
[role=checkbox] .icon:before {
67+
content: '\2610';
68+
display: inline-block;
69+
font-size: 2em;
70+
line-height: 1;
71+
vertical-align: middle;
72+
speak: none;
73+
}
74+
[role=checkbox].active .icon:before {
75+
content: '\2611';
76+
}
77+
pre {
78+
white-space: pre-wrap;
79+
}
80+
</style>
81+
<div>
82+
<form ng-controller="formsController">
83+
<some-checkbox role="checkbox" ng-model="checked" ng-class="{active: checked}"
84+
ng-disabled="isDisabled" ng-click="toggleCheckbox()"
85+
required aria-label="Custom Checkbox" show-attrs>
86+
<span class="icon" aria-hidden="true"></span>
87+
Custom Checkbox
88+
</some-checkbox>
89+
</form>
90+
</div>
91+
<script>
92+
var app = angular.module('ngAria_ngModelExample', ['ngAria'])
93+
.controller('formsController', function($scope){
94+
$scope.checked = false;
95+
$scope.toggleCheckbox = function(){
96+
$scope.checked = !$scope.checked;
97+
}
98+
})
99+
.directive('someCheckbox', function(){
100+
return {
101+
restrict: 'E',
102+
link: function($scope, $el, $attrs) {
103+
$scope.$on('keypress', function(event){
104+
event.preventDefault();
105+
});
106+
}
107+
}
108+
})
109+
.directive('showAttrs', function() {
110+
return function($scope, $el, $attrs) {
111+
var pre = document.createElement('pre');
112+
$el.after(pre);
113+
$scope.$watch(function() {
114+
var $attrs = {};
115+
Array.prototype.slice.call($el[0].attributes, 0).forEach(function(item) {
116+
if (item.name !== 'show-$attrs') {
117+
$attrs[item.name] = item.value;
118+
}
119+
});
120+
return $attrs;
121+
}, function(newAttrs, oldAttrs) {
122+
pre.innerText = JSON.stringify(newAttrs, null, 2);
123+
}, true);
124+
}
125+
});
126+
</script>
127+
</file>
128+
</example>
59129

60130
ngAria will also add `tabIndex`, ensuring custom elements with these roles will be reachable from
61131
the keyboard. It is still up to **you** as a developer to **ensure custom controls will be
@@ -106,6 +176,24 @@ screen reader users won't accidentally focus on "mystery elements". Managing tab
106176
child control can be complex and affect performance, so it’s best to just stick with the default
107177
`display: none` CSS. See the [fourth rule of ARIA use](http://www.w3.org/TR/aria-in-html/#fourth-rule-of-aria-use).
108178

179+
###Example
180+
```css
181+
.ng-hide {
182+
display: block;
183+
opacity: 0;
184+
}
185+
```
186+
```html
187+
<div ng-show="false" class="ng-hide" aria-hidden="true"></div>
188+
```
189+
190+
Becomes:
191+
192+
```html
193+
<div ng-show="true" aria-hidden="false"></div>
194+
```
195+
*Note: Child links, buttons or other interactive controls must also be removed from the tab order.*
196+
109197
<h2 id="nghide">ngHide</h2>
110198

111199
>The [ngHide](https://docs.angularjs.org/api/ng/directive/ngHide) directive shows or hides the
@@ -116,33 +204,125 @@ The default CSS for `ngHide`, the inverse method to `ngShow`, makes ngAria redun
116204
`aria-hidden` on the directive when it is hidden or shown, but the content is already hidden with
117205
`display: none`. See explanation for <a href="#ngshow">ngShow</a> when overriding the default CSS.
118206

119-
<h2 id="ngclick">ngClick and ngDblClick</h2>
120-
If `ngClick` or `ngDblClick` is encountered, ngAria will add `tabIndex` if it isn't there already.
121-
Even with this, you must currently still add `ng-keypress` to non-interactive elements such as
122-
`<div>` or `<taco-button>` to enable keyboard access. Conversation is
123-
[currently ongoing](https://github.com/angular/angular.js/issues/9254) about whether ngAria
124-
should also bind `ng-keypress` to be more useful.
207+
<h2 id="ngclick-and-ngdblclick">ngClick and ngDblclick</h2>
208+
If `ng-click` or `ng-dblclick` is encountered, ngAria will add `tabindex` if it isn't there already.
209+
Even with this, you must currently still add `ng-keypress` to non-interactive elements such as `div`
210+
or `taco-button` to enable keyboard access. Conversation is currently ongoing about whether ngAria
211+
should also bind `ng-keypress`.
212+
213+
<h3>Example</h3>
214+
```html
215+
<div ng-click="toggleMenu()"></div>
216+
```
217+
218+
Becomes:
219+
```html
220+
<div ng-click="toggleMenu()" tabindex="0"></div>
221+
```
222+
*Note: ngAria still requires `ng-keypress` to be added manually to non-native controls like divs.*
125223

126224
<h2 id="ngmessages">ngMessages</h2>
127225

128226
The new ngMessages module makes it easy to display form validation or other messages with priority
129227
sequencing and animation. To expose these visual messages to screen readers,
130228
ngAria injects `aria-live="polite"`, causing them to be read aloud any time a message is shown,
131229
regardless of the user's focus location.
230+
###Example
231+
232+
```html
233+
<div ng-messages="myForm.myName.$error">
234+
<div ng-message="required">You did not enter a field</div>
235+
<div ng-message="maxlength">Your field is too long</div>
236+
</div>
237+
```
132238

133-
* * *
239+
Becomes:
240+
241+
```html
242+
<div ng-messages="myForm.myName.$error" aria-live="polite">
243+
<div ng-message="required">You did not enter a field</div>
244+
<div ng-message="maxlength">Your field is too long</div>
245+
</div>
246+
```
134247

135248
##Disabling attributes
136249
The attribute magic of ngAria may not work for every scenario. To disable individual attributes,
137-
you can use the {@link ngAria.$ariaProvider#config config} method:
138-
139-
```
140-
angular.module('myApp', ['ngAria'], function config($ariaProvider) {
141-
$ariaProvider.config({
142-
tabindex: false
250+
you can use the {@link ngAria.$ariaProvider#config config} method. Just keep in mind this will
251+
tell ngAria to ignore the attribute globally.
252+
253+
<example module="ngAria_ngDisabledExample" deps="angular-aria.js">
254+
<file name="index.html">
255+
<style>
256+
[role=checkbox] {
257+
cursor: pointer;
258+
display: block;
259+
}
260+
[role=checkbox] .icon:before {
261+
content: '\2610';
262+
display: inline-block;
263+
font-size: 2em;
264+
line-height: 1;
265+
vertical-align: middle;
266+
speak: none;
267+
}
268+
[role=checkbox].active .icon:before {
269+
content: '\2611';
270+
}
271+
</style>
272+
<form ng-controller="formsController">
273+
<div ng-model="someModel" show-attrs>
274+
Div with ngModel and aria-invalid disabled
275+
</div>
276+
<div role="checkbox" ng-model="checked" ng-class="{active: checked}"
277+
aria-label="Custom Checkbox" ng-click="toggleCheckbox()"
278+
ng-keypress="toggleCheckbox()" some-checkbox show-attrs>
279+
<span class="icon" aria-hidden="true"></span>
280+
Custom Checkbox for comparison
281+
</div>
282+
</form>
283+
<script>
284+
angular.module('ngAria_ngDisabledExample', ['ngAria'], function config($ariaProvider) {
285+
$ariaProvider.config({
286+
ariaInvalid: false,
287+
tabindex: true
288+
});
289+
})
290+
.controller('formsController', function($scope){
291+
$scope.checked = false;
292+
$scope.toggleCheckbox = function(){
293+
$scope.checked = !$scope.checked;
294+
}
295+
})
296+
.directive('someCheckbox', function(){
297+
return {
298+
restrict: 'A',
299+
link: function($scope, $el, $attrs) {
300+
$scope.$on('keypress', function(event){
301+
event.preventDefault();
302+
});
303+
}
304+
}
305+
})
306+
.directive('showAttrs', function() {
307+
return function(scope, el, attrs) {
308+
var pre = document.createElement('pre');
309+
el.after(pre);
310+
scope.$watch(function() {
311+
var attrs = {};
312+
Array.prototype.slice.call(el[0].attributes, 0).forEach(function(item) {
313+
if (item.name !== 'show-attrs') {
314+
attrs[item.name] = item.value;
315+
}
316+
});
317+
return attrs;
318+
}, function(newAttrs, oldAttrs) {
319+
pre.innerText = JSON.stringify(newAttrs, null, 2);
320+
}, true);
321+
}
143322
});
144-
});
145-
```
323+
</script>
324+
</file>
325+
</example>
146326

147327
##Common Accessibility Patterns
148328

@@ -171,6 +351,7 @@ Accessibility best practices that apply to web apps in general also apply to Ang
171351

172352
* [Using ARIA in HTML](http://www.w3.org/TR/aria-in-html/)
173353
* [AngularJS Accessibility at ngEurope](https://www.youtube.com/watch?v=dmYDggEgU-s&list=UUEGUP3TJJfMsEM_1y8iviSQ)
354+
* [Testing with Screen Readers](http://webaim.org/articles/screenreader_testing/)
174355
* [Chrome Accessibility Developer Tools](https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb?hl=en)
175356
* [W3C Accessibility Testing](http://www.w3.org/wiki/Accessibility_testing)
176357
* [WebAIM](http://webaim.org)

‎src/ngAria/aria.js

+82-22
Original file line numberDiff line numberDiff line change
@@ -5,33 +5,49 @@
55
* @name ngAria
66
* @description
77
*
8-
* The `ngAria` module provides support for adding <abbr title="Accessible Rich Internet Applications">ARIA</abbr>
9-
* attributes that convey state or semantic information about the application in order to allow assistive technologies
10-
* to convey appropriate information to persons with disabilities.
8+
* The `ngAria` module provides support for common
9+
* [<abbr title="Accessible Rich Internet Applications">ARIA</abbr>](http://www.w3.org/TR/wai-aria/)
10+
* attributes that convey state or semantic information about the application for users
11+
* of assistive technologies, such as screen readers.
1112
*
1213
* <div doc-module-components="ngAria"></div>
1314
*
14-
* # Usage
15-
* To enable the addition of the ARIA tags, just require the module into your application and the tags will
16-
* hook into your ng-show/ng-hide, input, textarea, button, select and ng-required directives and adds the
17-
* appropriate ARIA attributes.
15+
* ## Usage
1816
*
19-
* Currently, the following ARIA attributes are implemented:
17+
* For ngAria to do its magic, simply include the module as a dependency. The directives supported
18+
* by ngAria are:
19+
* `ngModel`, `ngDisabled`, `ngShow`, `ngHide`, `ngClick`, `ngDblClick`, and `ngMessages`.
2020
*
21-
* + aria-hidden
22-
* + aria-checked
23-
* + aria-disabled
24-
* + aria-required
25-
* + aria-invalid
26-
* + aria-multiline
27-
* + aria-valuenow
28-
* + aria-valuemin
29-
* + aria-valuemax
30-
* + tabindex
21+
* Below is a more detailed breakdown of the attributes handled by ngAria:
3122
*
32-
* You can disable individual ARIA attributes by using the {@link ngAria.$ariaProvider#config config} method.
23+
* | Directive | Supported Attributes |
24+
* |---------------------------------------------|----------------------------------------------------------------------------------------|
25+
* | {@link ng.directive:ngModel ngModel} | aria-checked, aria-valuemin, aria-valuemax, aria-valuenow, aria-invalid, aria-required |
26+
* | {@link ng.directive:ngDisabled ngDisabled} | aria-disabled |
27+
* | {@link ng.directive:ngShow ngShow} | aria-hidden |
28+
* | {@link ng.directive:ngHide ngHide} | aria-hidden |
29+
* | {@link ng.directive:ngClick ngClick} | tabindex |
30+
* | {@link ng.directive:ngDblclick ngDblclick} | tabindex |
31+
* | {@link module:ngMessages ngMessages} | aria-live |
32+
*
33+
* Find out more information about each directive by reading the
34+
* {@link guide/accessibility ngAria Developer Guide}.
35+
*
36+
* ##Example
37+
* Using ngDisabled with ngAria:
38+
* ```html
39+
* <md-checkbox ng-disabled="disabled">
40+
* ```
41+
* Becomes:
42+
* ```html
43+
* <md-checkbox ng-disabled="disabled" aria-disabled="true">
44+
* ```
45+
*
46+
* ##Disabling Attributes
47+
* It's possible to disable individual attributes added by ngAria with the
48+
* {@link ngAria.$ariaProvider#config config} method. For more details, see the
49+
* {@link guide/accessibility Developer Guide}.
3350
*/
34-
3551
/* global -ngAriaModule */
3652
var ngAriaModule = angular.module('ngAria', ['ng']).
3753
provider('$aria', $AriaProvider);
@@ -42,10 +58,20 @@ var ngAriaModule = angular.module('ngAria', ['ng']).
4258
*
4359
* @description
4460
*
45-
* Used for configuring ARIA attributes.
61+
* Used for configuring the ARIA attributes injected and managed by ngAria.
62+
*
63+
* ```js
64+
* angular.module('myApp', ['ngAria'], function config($ariaProvider) {
65+
* $ariaProvider.config({
66+
* ariaValue: true,
67+
* tabindex: false
68+
* });
69+
* });
70+
*```
4671
*
4772
* ## Dependencies
4873
* Requires the {@link ngAria} module to be installed.
74+
*
4975
*/
5076
function $AriaProvider() {
5177
var config = {
@@ -108,7 +134,41 @@ function $AriaProvider() {
108134
*
109135
* @description
110136
*
111-
* Contains helper methods for applying ARIA attributes to HTML
137+
* The $aria service contains helper methods for applying common
138+
* [ARIA](http://www.w3.org/TR/wai-aria/) attributes to HTML directives.
139+
*
140+
* ngAria injects common accessibility attributes that tell assistive technologies when HTML
141+
* elements are enabled, selected, hidden, and more. To see how this is performed with ngAria,
142+
* let's review a code snippet from ngAria itself:
143+
*
144+
*```js
145+
* ngAriaModule.directive('ngDisabled', ['$aria', function($aria) {
146+
* return $aria.$$watchExpr('ngDisabled', 'aria-disabled');
147+
* }])
148+
*```
149+
* Shown above, the ngAria module creates a directive with the same signature as the
150+
* traditional `ng-disabled` directive. But this ngAria version is dedicated to
151+
* solely managing accessibility attributes. The internal `$aria` service is used to watch the
152+
* boolean attribute `ngDisabled`. If it has not been explicitly set by the developer,
153+
* `aria-disabled` is injected as an attribute with its value synchronized to the value in
154+
* `ngDisabled`.
155+
*
156+
* Because ngAria hooks into the `ng-disabled` directive, developers do not have to do
157+
* anything to enable this feature. The `aria-disabled` attribute is automatically managed
158+
* simply as a silent side-effect of using `ng-disabled` with the ngAria module.
159+
*
160+
* The full list of directives that interface with ngAria:
161+
* * **ngModel**
162+
* * **ngShow**
163+
* * **ngHide**
164+
* * **ngClick**
165+
* * **ngDblclick**
166+
* * **ngMessages**
167+
* * **ngDisabled**
168+
*
169+
* Read the {@link guide/accessibility ngAria Developer Guide} for a thorough explanation of each
170+
* directive.
171+
*
112172
*
113173
* ## Dependencies
114174
* Requires the {@link ngAria} module to be installed.

0 commit comments

Comments
 (0)
This repository has been archived.