From 6e9015f5e981886adc7674c4751e1e6767a5a27c Mon Sep 17 00:00:00 2001 From: Felix Zapata Date: Wed, 15 Jun 2016 10:52:34 +0200 Subject: [PATCH 1/6] docs(step_15): create new step about accessibility --- docs/app/src/tutorials.js | 2 +- docs/content/tutorial/step_14.ngdoc | 4 +- docs/content/tutorial/step_15.ngdoc | 327 ++++++++++++++++++++++++++++ 3 files changed, 330 insertions(+), 3 deletions(-) create mode 100644 docs/content/tutorial/step_15.ngdoc diff --git a/docs/app/src/tutorials.js b/docs/app/src/tutorials.js index 09df4138fc96..855c76b24198 100644 --- a/docs/app/src/tutorials.js +++ b/docs/app/src/tutorials.js @@ -6,7 +6,7 @@ angular.module('tutorials', []) 'step_00', 'step_01', 'step_02', 'step_03', 'step_04', 'step_05', 'step_06', 'step_07', 'step_08', 'step_09', 'step_10', 'step_11', 'step_12', 'step_13', 'step_14', - 'the_end' + 'step_15', 'the_end' ]; return { scope: {}, diff --git a/docs/content/tutorial/step_14.ngdoc b/docs/content/tutorial/step_14.ngdoc index 378b6f0ffbfe..115a754b5684 100644 --- a/docs/content/tutorial/step_14.ngdoc +++ b/docs/content/tutorial/step_14.ngdoc @@ -549,8 +549,8 @@ if the animation was canceled or not. Use this function to do any necessary clea Our application is now much more pleasant to use, thanks to the smooth transitions between pages and UI states. -There you have it! We have created a web application in a relatively short amount of time. In the -{@link the_end closing notes} we will cover where to go from here. +We are ready for +{@link step_15 step 15} to learn how to fix the accessibility (_a11y_) issues of the application. diff --git a/docs/content/tutorial/step_15.ngdoc b/docs/content/tutorial/step_15.ngdoc new file mode 100644 index 000000000000..a0398cd28bbf --- /dev/null +++ b/docs/content/tutorial/step_15.ngdoc @@ -0,0 +1,327 @@ +@ngdoc tutorial +@name 15 - Accessibility +@step 15 +@description + + + +In this step, we will learn how to fix the accessibility issues in our application. + +* We will use the {@link ngAria ngAria} module to enable WAI-ARIA. +* We will fix some issues in the templates. +* We will use the [protractor-accessibility-plugin](protractor-a11y-plugin) to review the accessibility of our application when we run our e2e tests. + +
+ +## Why accessibility matters + +* [Creating an accessible web - Access iQ](https://www.youtube.com/watch?v=47n0wEcm6JU) +* [Web Accessibility](https://www.youtube.com/watch?v=bEM9Fn9aOG8) +* [Google Accessibility course](https://webaccessibility.withgoogle.com/course) +* [Accessibility in AngularJS and Beyond](http://marcysutton.com/slides/fluent2015/) +* [Apps For All: Coding Accessible Web Applications](https://shop.smashingmagazine.com/products/apps-for-all) + +## Main accessibility issues in the application + +If you make a review of the accessibility of the application you will find some issues: + +* Lack of information about the current results when the user interacts with the filters. +* Lack of labels elements in the search and order filters in the Phone list. +* Lack of headers elements to help the user to navigate throw the content of the page. +* In the Phone detail, the user can't access via keyboard over the thumbnails images. + +In the next sections we are going to show you, how to fix some of these issues to make the application accessible. + +To help us, we will use the {@link ngAria ngAria} module, and we will install the [protractor-a11y-plugin] plugin too. + +## Dependencies + +The `ngAria` module, is distributed separately from the core Angular framework. + +Since we are using [Bower][bower] to install client-side dependencies, this step updates the +`bower.json` configuration file to include the new dependencies: + +
+**`bower.json`:** + +``` +{ + "name": "angular-phonecat", + "description": "A starter project for AngularJS", + "version": "0.0.0", + "homepage": "https://github.com/angular/angular-phonecat", + "license": "MIT", + "private": true, + "dependencies": { + "angular": "1.5.x", + "angular-animate": "1.5.x", + "angular-aria": "1.5.x", + "angular-mocks": "1.5.x", + "angular-resource": "1.5.x", + "angular-route": "1.5.x", + "bootstrap": "3.3.x", + "jquery": "2.2.x" + } +} +``` + +* `"angular-aria": "1.5.x"` tells bower to install a version of the angular-aria module that + is compatible with version 1.5.x of Angular. + +To install the [protractor-a11y-plugin], we can add the plugin into the `devDependencies` section in the `package.json` file, + +
+**`package.json`:** + +``` +{ + "devDependencies": { + "bower": "^1.7.7", + "http-server": "^0.9.0", + "jasmine-core": "^2.4.1", + "karma": "^0.13.22", + "karma-chrome-launcher": "^0.2.3", + "karma-firefox-launcher": "^0.1.7", + "karma-jasmine": "^0.3.8", + "protractor": "^3.2.2", + "protractor-accessibility-plugin": "^0.1.1", + "shelljs": "^0.6.0" + } +} +``` + +Now, we must tell bower to download and install these dependencies. + +``` +npm install +``` + +
+ **Note:** If you have bower installed globally, you can run `bower install`, but for this project + we have preconfigured `npm install` to run bower for us. +
+ +
+ **Warning:** If a new version of Angular has been released since you last ran `npm install`, then + you may have a problem with the `bower install` due to a conflict between the versions of + angular.js that need to be installed. If you run into this issue, simply delete your + `app/bower_components` directory and then run `npm install`. +
+ + +## How to use the `ngAria` module + +The `ngAria` module provides support for common ARIA attributes that convey state or semantic information about the application for users of assistive technologies, such as screen readers. + +### Template + +In order to enable the module, we need to update `index.html`, loading the necessary dependencies +(**angular-aria.js**) that contain JavaScript code. + +The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help you to add WAI-ARIA attributes in your application. + +
+**`app/index.html`:** + +```html + ... + + + ... +``` + +### Dependencies + +We need to add a dependency on `ngAria` to our main module first: + +
+**`app/app.module.js`:** + +```js + angular. + module('phonecatApp', [ + ... + 'ngAria', + ... + ]); +``` + +## How to inform the user that _something_ is happening + +Today, is very common to find applications or webpages where the user make some interaction with an element and obtains and inmediate reply to the action. + +The problem is that in most of the cases this action is only reported in a way that you need to see it in your screen but if a user is navigating with a screenreader like [JAWS](http://www.freedomscientific.com/Products/Blindness/JAWS), [NVDA](http://www.nvaccess.org/) or [ChromeVox](http://www.chromevox.com/), this information never won't be accessible. + +When the user is searching or filtering mobiles in the application, the list updates automatically. It is mandatory that user knows, in some way, the result after the search or order action. + +To fix this, we add two directives to inform the user how many items are know in the list after search or order them. This directive will fill an element in our page to tell the user how many elements are after the action. + +
+**`app/phone-list/phone-list-template.html`:** + +```html +
+ + +
+ +
+ + ... + +
+ +``` + +The new element is a _region live_. It means that every time this region is updated, it will inform the user about its content. + +In order to update the information correctly, it is neccesary to add a _`debounce`_ option to the model. + +Please note that now the inputs are associated with theirs labels using `label` elements. + +The directives are based on an idea of [Marcy Sutton](http://marcysutton.com/slides/fluent2015/) about how to add accessibility in the AngularJS applications. + + +### How to use the directives + +
+**`app/phone-list/phone-list-template.html`:** + +```html + + ... + +
+ + +
+ + ... + + + +``` + +
+**`app/index.html`:** + +```html + ... + + ... +``` + + +
+**`app/phone-list/phone-list.directive.js`:** + +```js + +'use strict'; + +/* Directives */ + +angular. + module('phoneList'). + directive('resultList', [function () { + var ariaStatus = document.querySelector('.aria-status'); + return { + restrict: 'A', + link: function ($scope) { + $scope.$watch('filtered.length', function (length) { + if(length === 1) { + ariaStatus.innerHTML = length + ' item found'; + } else if(length > 1) { + ariaStatus.innerHTML = length + ' items found'; + } else { + ariaStatus.innerHTML = 'No items found'; + } + }); + } + } +} +]). + directive('informOrder', [function () { + var ariaStatusSort = document.querySelector('.aria-status-sort'); + return { + restrict: 'A', + link: function ($scope) { + $scope.$watch('$ctrl.orderProp', function (order) { + if(order === 'age') { + ariaStatusSort.innerHTML = 'Items filter by newest' + } else { + ariaStatusSort.innerHTML = 'Items filter by alphabetical order' + } + + }); + } + } + } +]); + +``` + +## Using the keyboard + +The current detail of a phone prevents a user to use a keyboard to navigate for over each thumbnail image. It is very important due to accessibility that all the actions and information are available via keyboard too. For example, lightboxes, carousels, slides, etc. + +_Tip_: Try to navigate over the application using only the _TAB_ key. You will discover that some actions can't be accessed nor the focus on some elements. + +
+**`app/phone-detail/phone-detail.template.html`:** + +```html + ... + + ... +``` + +## How to run the e2e tests using the Protractor accessibility plugin + +Once the plugin is installed, we have to modify the `protractor.conf.js` file to inform Protractor to use this plugin too. + +
+**`protractor.conf.js`:** + +``` + plugins: [{ + chromeA11YDevTools: { + treatWarningsAsFailures: true + }, + package: 'protractor-accessibility-plugin' + }] +``` + +After that, every time we run the e2e tests, Protractor will review the accessibility of your application using the [Accessibility Developer Tools](https://github.com/GoogleChrome/accessibility-developer-tools). + + + +# Summary + +Our application is now accessible, thanks to these small changes. + +There you have it! We have created a web application in a relatively short amount of time. In the +{@link the_end closing notes} we will cover where to go from here. + + + + + +[bower]: http://bower.io/ +[protractor-a11y-plugin]: https://github.com/angular/protractor-accessibility-plugin From 7103297135aa2ab689abb3d8bc33f7ef1a71658f Mon Sep 17 00:00:00 2001 From: Felix Zapata Date: Tue, 21 Jun 2016 10:07:16 +0200 Subject: [PATCH 2/6] docs(step_15.ngdoc): update the step 15 add definitions about accessibility and WAI-ARIA ngAria module now is not neccesary, so the section has been moved to explain how to use it if you need it explain how to fix the problem with the keyboard in the detail page. --- docs/content/tutorial/step_15.ngdoc | 244 +++++++++++++++------------- 1 file changed, 127 insertions(+), 117 deletions(-) diff --git a/docs/content/tutorial/step_15.ngdoc b/docs/content/tutorial/step_15.ngdoc index a0398cd28bbf..edd53e681af6 100644 --- a/docs/content/tutorial/step_15.ngdoc +++ b/docs/content/tutorial/step_15.ngdoc @@ -7,20 +7,31 @@ In this step, we will learn how to fix the accessibility issues in our application. -* We will use the {@link ngAria ngAria} module to enable WAI-ARIA. * We will fix some issues in the templates. * We will use the [protractor-accessibility-plugin](protractor-a11y-plugin) to review the accessibility of our application when we run our e2e tests. +* We will explain how to add the {@link ngAria ngAria} module to use WAI-ARIA easily if you need it in your project.
## Why accessibility matters +A website or application accessible allows the users with different preferences and abilitities, to consume the content in a way that suits their needs. + * [Creating an accessible web - Access iQ](https://www.youtube.com/watch?v=47n0wEcm6JU) * [Web Accessibility](https://www.youtube.com/watch?v=bEM9Fn9aOG8) * [Google Accessibility course](https://webaccessibility.withgoogle.com/course) * [Accessibility in AngularJS and Beyond](http://marcysutton.com/slides/fluent2015/) +* [Introduction to Web Accessibility](https://www.w3.org/WAI/intro/accessibility.php) * [Apps For All: Coding Accessible Web Applications](https://shop.smashingmagazine.com/products/apps-for-all) +## WAI-ARIA + +WAI-ARIA (_the Accessible Rich Internet Applications Suite_) gives you the ability to reclassify and otherwise augment the perceived meaning (or semantics) of your HTML. + + Currently certain functionality used in Web sites is not available to some users with disabilities, especially people who rely on screen readers and people who cannot use a mouse. WAI-ARIA addresses these accessibility challenges, for example, by defining new ways for functionality to be provided to assistive technology. With WAI-ARIA, developers can make advanced Web applications accessible and usable to people with disabilities. + +AngularJS has a module called {@link ngAria ngAria} to help developers to add some WAI-ARIA attributes easily in your application. + ## Main accessibility issues in the application If you make a review of the accessibility of the application you will find some issues: @@ -32,119 +43,7 @@ If you make a review of the accessibility of the application you will find some In the next sections we are going to show you, how to fix some of these issues to make the application accessible. -To help us, we will use the {@link ngAria ngAria} module, and we will install the [protractor-a11y-plugin] plugin too. - -## Dependencies - -The `ngAria` module, is distributed separately from the core Angular framework. - -Since we are using [Bower][bower] to install client-side dependencies, this step updates the -`bower.json` configuration file to include the new dependencies: - -
-**`bower.json`:** - -``` -{ - "name": "angular-phonecat", - "description": "A starter project for AngularJS", - "version": "0.0.0", - "homepage": "https://github.com/angular/angular-phonecat", - "license": "MIT", - "private": true, - "dependencies": { - "angular": "1.5.x", - "angular-animate": "1.5.x", - "angular-aria": "1.5.x", - "angular-mocks": "1.5.x", - "angular-resource": "1.5.x", - "angular-route": "1.5.x", - "bootstrap": "3.3.x", - "jquery": "2.2.x" - } -} -``` - -* `"angular-aria": "1.5.x"` tells bower to install a version of the angular-aria module that - is compatible with version 1.5.x of Angular. - -To install the [protractor-a11y-plugin], we can add the plugin into the `devDependencies` section in the `package.json` file, - -
-**`package.json`:** - -``` -{ - "devDependencies": { - "bower": "^1.7.7", - "http-server": "^0.9.0", - "jasmine-core": "^2.4.1", - "karma": "^0.13.22", - "karma-chrome-launcher": "^0.2.3", - "karma-firefox-launcher": "^0.1.7", - "karma-jasmine": "^0.3.8", - "protractor": "^3.2.2", - "protractor-accessibility-plugin": "^0.1.1", - "shelljs": "^0.6.0" - } -} -``` - -Now, we must tell bower to download and install these dependencies. - -``` -npm install -``` - -
- **Note:** If you have bower installed globally, you can run `bower install`, but for this project - we have preconfigured `npm install` to run bower for us. -
- -
- **Warning:** If a new version of Angular has been released since you last ran `npm install`, then - you may have a problem with the `bower install` due to a conflict between the versions of - angular.js that need to be installed. If you run into this issue, simply delete your - `app/bower_components` directory and then run `npm install`. -
- - -## How to use the `ngAria` module - -The `ngAria` module provides support for common ARIA attributes that convey state or semantic information about the application for users of assistive technologies, such as screen readers. - -### Template - -In order to enable the module, we need to update `index.html`, loading the necessary dependencies -(**angular-aria.js**) that contain JavaScript code. - -The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help you to add WAI-ARIA attributes in your application. - -
-**`app/index.html`:** - -```html - ... - - - ... -``` - -### Dependencies - -We need to add a dependency on `ngAria` to our main module first: - -
-**`app/app.module.js`:** - -```js - angular. - module('phonecatApp', [ - ... - 'ngAria', - ... - ]); -``` +To help us, we will install the [protractor-a11y-plugin] plugin to check potential issues in the application. ## How to inform the user that _something_ is happening @@ -162,7 +61,7 @@ To fix this, we add two directives to inform the user how many items are know in ```html
- +
@@ -292,11 +191,123 @@ _Tip_: Try to navigate over the application using only the _TAB_ key. You will d ... ``` +To fix this issue, we add a `button` element, wrapping the image to allow the user to access the content via keyboard. + +Why we are using a `button` element instead of an `a` element? It is more correct to use buttons elements to call actions like show content, hidden content or similar. + + +## How to use the `ngAria` module + +The `ngAria` module provides support for common WAI-ARIA attributes that convey state or semantic information about the application for users of assistive technologies, such as screen readers. + +### Dependencies + +The `ngAria` module, is distributed separately from the core Angular framework. + +Since we are using [Bower][bower] to install client-side dependencies, this step updates the +`bower.json` configuration file to include the new dependencies: + +
+**`bower.json`:** + +``` +{ + "name": "angular-phonecat", + "description": "A starter project for AngularJS", + "version": "0.0.0", + "homepage": "https://github.com/angular/angular-phonecat", + "license": "MIT", + "private": true, + "dependencies": { + "angular": "1.5.x", + "angular-animate": "1.5.x", + "angular-aria": "1.5.x", + "angular-mocks": "1.5.x", + "angular-resource": "1.5.x", + "angular-route": "1.5.x", + "bootstrap": "3.3.x", + "jquery": "2.2.x" + } +} +``` + +* `"angular-aria": "1.5.x"` tells bower to install a version of the angular-aria module that + is compatible with version 1.5.x of Angular. + +We need to add a dependency on `ngAria` to our main module first: + +
+**`app/app.module.js`:** + +```js + angular. + module('phonecatApp', [ + ... + 'ngAria', + ... + ]); +``` + +In order to enable the module, we need to update `index.html`, loading the necessary dependencies +(**angular-aria.js**) that contain JavaScript code. + +The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help you to add WAI-ARIA attributes in your application. + +
+**`app/index.html`:** + +```html + ... + + + ... +``` + ## How to run the e2e tests using the Protractor accessibility plugin +### Dependencies + +To install the [protractor-a11y-plugin], we can add the plugin into the `devDependencies` section in the `package.json` file, + +**`package.json`:** + +``` +{ + "devDependencies": { + "bower": "^1.7.7", + "http-server": "^0.9.0", + "jasmine-core": "^2.4.1", + "karma": "^0.13.22", + "karma-chrome-launcher": "^0.2.3", + "karma-firefox-launcher": "^0.1.7", + "karma-jasmine": "^0.3.8", + "protractor": "^3.2.2", + "protractor-accessibility-plugin": "^0.1.1", + "shelljs": "^0.6.0" + } +} +``` + +Now, we must tell bower to download and install these dependencies. + +``` +npm install +``` + +
+ **Note:** If you have bower installed globally, you can run `bower install`, but for this project + we have preconfigured `npm install` to run bower for us. +
+ +
+ **Warning:** If a new version of Angular has been released since you last ran `npm install`, then + you may have a problem with the `bower install` due to a conflict between the versions of + angular.js that need to be installed. If you run into this issue, simply delete your + `app/bower_components` directory and then run `npm install`. +
+ Once the plugin is installed, we have to modify the `protractor.conf.js` file to inform Protractor to use this plugin too. -
**`protractor.conf.js`:** ``` @@ -311,7 +322,6 @@ Once the plugin is installed, we have to modify the `protractor.conf.js` file to After that, every time we run the e2e tests, Protractor will review the accessibility of your application using the [Accessibility Developer Tools](https://github.com/GoogleChrome/accessibility-developer-tools). - # Summary Our application is now accessible, thanks to these small changes. From 62c5f59832f7cb37fb2868579ab31fbdbb3a6e8a Mon Sep 17 00:00:00 2001 From: Felix Zapata Date: Wed, 22 Jun 2016 09:13:02 +0200 Subject: [PATCH 3/6] docs(step_15): update document following marcysutton comments --- docs/content/tutorial/step_15.ngdoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/content/tutorial/step_15.ngdoc b/docs/content/tutorial/step_15.ngdoc index edd53e681af6..a45aaef9a779 100644 --- a/docs/content/tutorial/step_15.ngdoc +++ b/docs/content/tutorial/step_15.ngdoc @@ -22,13 +22,12 @@ A website or application accessible allows the users with different preferences * [Google Accessibility course](https://webaccessibility.withgoogle.com/course) * [Accessibility in AngularJS and Beyond](http://marcysutton.com/slides/fluent2015/) * [Introduction to Web Accessibility](https://www.w3.org/WAI/intro/accessibility.php) +* [Notes On Client-Rendered Accessibility](https://www.smashingmagazine.com/2015/05/client-rendered-accessibility/) * [Apps For All: Coding Accessible Web Applications](https://shop.smashingmagazine.com/products/apps-for-all) ## WAI-ARIA -WAI-ARIA (_the Accessible Rich Internet Applications Suite_) gives you the ability to reclassify and otherwise augment the perceived meaning (or semantics) of your HTML. - - Currently certain functionality used in Web sites is not available to some users with disabilities, especially people who rely on screen readers and people who cannot use a mouse. WAI-ARIA addresses these accessibility challenges, for example, by defining new ways for functionality to be provided to assistive technology. With WAI-ARIA, developers can make advanced Web applications accessible and usable to people with disabilities. +WAI-ARIA (_the Accessible Rich Internet Applications Suite_) is a standard set of attributes used to fill accessibility support gaps in custom HTML elements and SVG. AngularJS has a module called {@link ngAria ngAria} to help developers to add some WAI-ARIA attributes easily in your application. @@ -72,7 +71,7 @@ To fix this, we add two directives to inform the user how many items are know in ``` -The new element is a _region live_. It means that every time this region is updated, it will inform the user about its content. +The new element is a _live region_. It means that every time this region is updated, it will inform the user about its content. In order to update the information correctly, it is neccesary to add a _`debounce`_ option to the model. @@ -193,7 +192,7 @@ _Tip_: Try to navigate over the application using only the _TAB_ key. You will d To fix this issue, we add a `button` element, wrapping the image to allow the user to access the content via keyboard. -Why we are using a `button` element instead of an `a` element? It is more correct to use buttons elements to call actions like show content, hidden content or similar. +Why we are using a `button` element instead of an `a` element? Because it does not navigate to a new page or resource. ## How to use the `ngAria` module From 1300f8049226c03b9f8808975902a6172ddcb522 Mon Sep 17 00:00:00 2001 From: Felix Zapata Date: Wed, 22 Jun 2016 09:34:06 +0200 Subject: [PATCH 4/6] docs(step_15): add more information about the protractor plugin --- docs/content/tutorial/step_15.ngdoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/content/tutorial/step_15.ngdoc b/docs/content/tutorial/step_15.ngdoc index a45aaef9a779..874e6634c4bb 100644 --- a/docs/content/tutorial/step_15.ngdoc +++ b/docs/content/tutorial/step_15.ngdoc @@ -42,7 +42,9 @@ If you make a review of the accessibility of the application you will find some In the next sections we are going to show you, how to fix some of these issues to make the application accessible. -To help us, we will install the [protractor-a11y-plugin] plugin to check potential issues in the application. +To help us, we can use the [protractor-a11y-plugin] plugin to check potential issues in the application. + +This plugin [runs an audit](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules) locally by injecting the Dev Tools script into WebDriver pages, and it can diagnose issues including missing labels, incorrect ARIA attributes and color contrast. This is a great starting point if you can't send source code over the wire through an API. ## How to inform the user that _something_ is happening From c8c2dfdd3daa5d9a2ad71936b96f009159f5f236 Mon Sep 17 00:00:00 2001 From: Felix Zapata Date: Mon, 27 Jun 2016 09:08:35 +0200 Subject: [PATCH 5/6] docs(step_15): update document --- docs/content/tutorial/step_15.ngdoc | 72 +++++++++++++++++++---------- 1 file changed, 47 insertions(+), 25 deletions(-) diff --git a/docs/content/tutorial/step_15.ngdoc b/docs/content/tutorial/step_15.ngdoc index 874e6634c4bb..820110027a14 100644 --- a/docs/content/tutorial/step_15.ngdoc +++ b/docs/content/tutorial/step_15.ngdoc @@ -9,13 +9,15 @@ In this step, we will learn how to fix the accessibility issues in our applicati * We will fix some issues in the templates. * We will use the [protractor-accessibility-plugin](protractor-a11y-plugin) to review the accessibility of our application when we run our e2e tests. -* We will explain how to add the {@link ngAria ngAria} module to use WAI-ARIA easily if you need it in your project. +* We will explain how to add the {@link ngAria ngAria} module to use WAI-ARIA easily +if you need it in your project.
## Why accessibility matters -A website or application accessible allows the users with different preferences and abilitities, to consume the content in a way that suits their needs. +A website or application accessible allows the users with different preferences and abilitities, +to consume the content in a way that suits their needs. * [Creating an accessible web - Access iQ](https://www.youtube.com/watch?v=47n0wEcm6JU) * [Web Accessibility](https://www.youtube.com/watch?v=bEM9Fn9aOG8) @@ -27,7 +29,8 @@ A website or application accessible allows the users with different preferences ## WAI-ARIA -WAI-ARIA (_the Accessible Rich Internet Applications Suite_) is a standard set of attributes used to fill accessibility support gaps in custom HTML elements and SVG. +WAI-ARIA (_the Accessible Rich Internet Applications Suite_) is a standard set of attributes used +to fill accessibility support gaps in custom HTML elements and SVG. AngularJS has a module called {@link ngAria ngAria} to help developers to add some WAI-ARIA attributes easily in your application. @@ -40,21 +43,27 @@ If you make a review of the accessibility of the application you will find some * Lack of headers elements to help the user to navigate throw the content of the page. * In the Phone detail, the user can't access via keyboard over the thumbnails images. -In the next sections we are going to show you, how to fix some of these issues to make the application accessible. +In the next sections we are going to show you, how to fix some of these issues +to make the application accessible. -To help us, we can use the [protractor-a11y-plugin] plugin to check potential issues in the application. +To help us, we can use the [protractor-a11y-plugin] plugin to check +potential issues in the application. This plugin [runs an audit](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules) locally by injecting the Dev Tools script into WebDriver pages, and it can diagnose issues including missing labels, incorrect ARIA attributes and color contrast. This is a great starting point if you can't send source code over the wire through an API. ## How to inform the user that _something_ is happening -Today, is very common to find applications or webpages where the user make some interaction with an element and obtains and inmediate reply to the action. +Today, is very common to find applications or webpages where the user make some interaction +with an element and obtains and inmediate reply to the action. The problem is that in most of the cases this action is only reported in a way that you need to see it in your screen but if a user is navigating with a screenreader like [JAWS](http://www.freedomscientific.com/Products/Blindness/JAWS), [NVDA](http://www.nvaccess.org/) or [ChromeVox](http://www.chromevox.com/), this information never won't be accessible. -When the user is searching or filtering mobiles in the application, the list updates automatically. It is mandatory that user knows, in some way, the result after the search or order action. +When the user is searching or filtering mobiles in the application, the list updates automatically. +It is mandatory that user knows, in some way, the result after the search or order action. -To fix this, we add two directives to inform the user how many items are know in the list after search or order them. This directive will fill an element in our page to tell the user how many elements are after the action. +To fix this, we add two directives to inform the user how many items are now in the list +after search or order them. This directive will fill an element in our page +to tell the user how many elements are after the action.
**`app/phone-list/phone-list-template.html`:** @@ -73,9 +82,11 @@ To fix this, we add two directives to inform the user how many items are know in ``` -The new element is a _live region_. It means that every time this region is updated, it will inform the user about its content. +The new element is a _live region_. It means that every time this region is updated, +it will inform the user about its content. -In order to update the information correctly, it is neccesary to add a _`debounce`_ option to the model. +In order to update the information correctly, it is neccesary to add a _`debounce`_ option +to the model. Please note that now the inputs are associated with theirs labels using `label` elements. @@ -175,9 +186,12 @@ angular. ## Using the keyboard -The current detail of a phone prevents a user to use a keyboard to navigate for over each thumbnail image. It is very important due to accessibility that all the actions and information are available via keyboard too. For example, lightboxes, carousels, slides, etc. +The current detail of a phone prevents a user to use a keyboard to navigate for over each thumbnail +image. It is very important due to accessibility that all the actions and information +are available via keyboard too. For example, lightboxes, carousels, slides, etc. -_Tip_: Try to navigate over the application using only the _TAB_ key. You will discover that some actions can't be accessed nor the focus on some elements. +_Tip_: Try to navigate over the application using only the _TAB_ key. +You will discover that some actions can't be accessed nor the focus on some elements.
**`app/phone-detail/phone-detail.template.html`:** @@ -192,21 +206,25 @@ _Tip_: Try to navigate over the application using only the _TAB_ key. You will d ... ``` -To fix this issue, we add a `button` element, wrapping the image to allow the user to access the content via keyboard. +To fix this issue, we add a `button` element, wrapping the image to allow +the user to access the content via keyboard. -Why we are using a `button` element instead of an `a` element? Because it does not navigate to a new page or resource. +Why we are using a `button` element instead of an `a` element? +Because it does not navigate to a new page or resource. ## How to use the `ngAria` module -The `ngAria` module provides support for common WAI-ARIA attributes that convey state or semantic information about the application for users of assistive technologies, such as screen readers. +The `ngAria` module provides support for common WAI-ARIA attributes that convey state +or semantic information about the application for users of assistive technologies, +such as screen readers. ### Dependencies The `ngAria` module, is distributed separately from the core Angular framework. -Since we are using [Bower][bower] to install client-side dependencies, this step updates the -`bower.json` configuration file to include the new dependencies: +Since we are using [Bower][bower] to install client-side dependencies, +this step updates the `bower.json` configuration file to include the new dependencies:
**`bower.json`:** @@ -232,8 +250,8 @@ Since we are using [Bower][bower] to install client-side dependencies, this step } ``` -* `"angular-aria": "1.5.x"` tells bower to install a version of the angular-aria module that - is compatible with version 1.5.x of Angular. +* `"angular-aria": "1.5.x"` tells bower to install a version of the angular-aria module + that is compatible with version 1.5.x of Angular. We need to add a dependency on `ngAria` to our main module first: @@ -252,7 +270,8 @@ We need to add a dependency on `ngAria` to our main module first: In order to enable the module, we need to update `index.html`, loading the necessary dependencies (**angular-aria.js**) that contain JavaScript code. -The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help you to add WAI-ARIA attributes in your application. +The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help you +to add WAI-ARIA attributes in your application.
**`app/index.html`:** @@ -266,9 +285,14 @@ The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help ## How to run the e2e tests using the Protractor accessibility plugin + +Once we install the plugin, every time we run the e2e tests, +Protractor will review the accessibility of your application. + ### Dependencies -To install the [protractor-a11y-plugin], we can add the plugin into the `devDependencies` section in the `package.json` file, +To install the [protractor-a11y-plugin], we can add the plugin into the `devDependencies` section +in the `package.json` file, **`package.json`:** @@ -307,7 +331,8 @@ npm install `app/bower_components` directory and then run `npm install`. -Once the plugin is installed, we have to modify the `protractor.conf.js` file to inform Protractor to use this plugin too. +Once the plugin is installed, we have to modify the `protractor.conf.js` file to inform Protractor +to use this plugin too. **`protractor.conf.js`:** @@ -320,9 +345,6 @@ Once the plugin is installed, we have to modify the `protractor.conf.js` file to }] ``` -After that, every time we run the e2e tests, Protractor will review the accessibility of your application using the [Accessibility Developer Tools](https://github.com/GoogleChrome/accessibility-developer-tools). - - # Summary Our application is now accessible, thanks to these small changes. From 6a7b77f1b05770f4e38e590eafb6cdde4ad06140 Mon Sep 17 00:00:00 2001 From: Felix Zapata Date: Fri, 1 Jul 2016 09:05:47 +0200 Subject: [PATCH 6/6] docs(step_15): update the doc remove information about directives. Now the tutorial links to the guide. remove information about how to install ngAria because is not used in this step. --- docs/content/tutorial/step_15.ngdoc | 171 +--------------------------- 1 file changed, 4 insertions(+), 167 deletions(-) diff --git a/docs/content/tutorial/step_15.ngdoc b/docs/content/tutorial/step_15.ngdoc index 820110027a14..bd26ad48e123 100644 --- a/docs/content/tutorial/step_15.ngdoc +++ b/docs/content/tutorial/step_15.ngdoc @@ -5,12 +5,10 @@
    -In this step, we will learn how to fix the accessibility issues in our application. +In this step, we will learn how to fix the accessibility issues in the application. * We will fix some issues in the templates. * We will use the [protractor-accessibility-plugin](protractor-a11y-plugin) to review the accessibility of our application when we run our e2e tests. -* We will explain how to add the {@link ngAria ngAria} module to use WAI-ARIA easily -if you need it in your project.
    @@ -27,7 +25,7 @@ to consume the content in a way that suits their needs. * [Notes On Client-Rendered Accessibility](https://www.smashingmagazine.com/2015/05/client-rendered-accessibility/) * [Apps For All: Coding Accessible Web Applications](https://shop.smashingmagazine.com/products/apps-for-all) -## WAI-ARIA +## About WAI-ARIA WAI-ARIA (_the Accessible Rich Internet Applications Suite_) is a standard set of attributes used to fill accessibility support gaps in custom HTML elements and SVG. @@ -85,104 +83,15 @@ to tell the user how many elements are after the action. The new element is a _live region_. It means that every time this region is updated, it will inform the user about its content. -In order to update the information correctly, it is neccesary to add a _`debounce`_ option +In order to update the information correctly, it is neccesary to add a [_`debounce`_](https://docs.angularjs.org/api/ng/directive/ngModelOptions) option to the model. Please note that now the inputs are associated with theirs labels using `label` elements. The directives are based on an idea of [Marcy Sutton](http://marcysutton.com/slides/fluent2015/) about how to add accessibility in the AngularJS applications. +[You can learn more about directives, following the AngularJS guide](https://docs.angularjs.org/guide/directive). -### How to use the directives - -
    -**`app/phone-list/phone-list-template.html`:** - -```html - - ... - -
    - - -
    - - ... - - - -``` - -
    -**`app/index.html`:** - -```html - ... - - ... -``` - - -
    -**`app/phone-list/phone-list.directive.js`:** - -```js - -'use strict'; - -/* Directives */ - -angular. - module('phoneList'). - directive('resultList', [function () { - var ariaStatus = document.querySelector('.aria-status'); - return { - restrict: 'A', - link: function ($scope) { - $scope.$watch('filtered.length', function (length) { - if(length === 1) { - ariaStatus.innerHTML = length + ' item found'; - } else if(length > 1) { - ariaStatus.innerHTML = length + ' items found'; - } else { - ariaStatus.innerHTML = 'No items found'; - } - }); - } - } -} -]). - directive('informOrder', [function () { - var ariaStatusSort = document.querySelector('.aria-status-sort'); - return { - restrict: 'A', - link: function ($scope) { - $scope.$watch('$ctrl.orderProp', function (order) { - if(order === 'age') { - ariaStatusSort.innerHTML = 'Items filter by newest' - } else { - ariaStatusSort.innerHTML = 'Items filter by alphabetical order' - } - - }); - } - } - } -]); - -``` ## Using the keyboard @@ -212,80 +121,8 @@ the user to access the content via keyboard. Why we are using a `button` element instead of an `a` element? Because it does not navigate to a new page or resource. - -## How to use the `ngAria` module - -The `ngAria` module provides support for common WAI-ARIA attributes that convey state -or semantic information about the application for users of assistive technologies, -such as screen readers. - -### Dependencies - -The `ngAria` module, is distributed separately from the core Angular framework. - -Since we are using [Bower][bower] to install client-side dependencies, -this step updates the `bower.json` configuration file to include the new dependencies: - -
    -**`bower.json`:** - -``` -{ - "name": "angular-phonecat", - "description": "A starter project for AngularJS", - "version": "0.0.0", - "homepage": "https://github.com/angular/angular-phonecat", - "license": "MIT", - "private": true, - "dependencies": { - "angular": "1.5.x", - "angular-animate": "1.5.x", - "angular-aria": "1.5.x", - "angular-mocks": "1.5.x", - "angular-resource": "1.5.x", - "angular-route": "1.5.x", - "bootstrap": "3.3.x", - "jquery": "2.2.x" - } -} -``` - -* `"angular-aria": "1.5.x"` tells bower to install a version of the angular-aria module - that is compatible with version 1.5.x of Angular. - -We need to add a dependency on `ngAria` to our main module first: - -
    -**`app/app.module.js`:** - -```js - angular. - module('phonecatApp', [ - ... - 'ngAria', - ... - ]); -``` - -In order to enable the module, we need to update `index.html`, loading the necessary dependencies -(**angular-aria.js**) that contain JavaScript code. - -The WAI-ARIA module, {@link ngAria ngAria}, contains the code necessary to help you -to add WAI-ARIA attributes in your application. - -
    -**`app/index.html`:** - -```html - ... - - - ... -``` - ## How to run the e2e tests using the Protractor accessibility plugin - Once we install the plugin, every time we run the e2e tests, Protractor will review the accessibility of your application.