doc(cb-a11y): Labelling form controls: content

Author: AlmeroSteyn

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-custom-control.component.css

@@ -1,4 +1,7 @@
+/* #docregion */
 div.edit-box{
   height: auto;
+  min-height: 50px;
   width: 30%;
 }
+/* #enddocregion */

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-custom-control.component.html

@@ -5,11 +5,12 @@
   </label>
   <div #divTextBox
        role="textbox"
-       aria-multiline="false"
+       aria-multiline="true"
        [attr.aria-labelledby]="uniqueId"
        class="form-control edit-box"
        [innerHTML]="outerValue"
        (keypress)="onChange($event, divTextBox.innerHTML)"
+       (blur)="onBlur()"
        contenteditable></div>
 </div>
 <!-- #enddocregion -->

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-custom-control.component.ts

@@ -2,6 +2,7 @@ import {Component, OnInit, Provider, forwardRef,} from "angular2/core";
 import {A11yHelper} from "../services/a11y-helper.service";
 import {NG_VALUE_ACCESSOR, ControlValueAccessor} from "angular2/common";
 
+// #docregion
 const noop = () => {
 };
 
@@ -40,6 +41,10 @@ export class A11yCustomControl implements OnInit, ControlValueAccessor {
     }
   }
 
+  onBlur(){
+    this._onTouchedCallback();
+  }
+
   writeValue(value:any) {
     if (value != this._innerValue) {
       this._innerValue = value;
@@ -60,3 +65,4 @@ export class A11yCustomControl implements OnInit, ControlValueAccessor {
   }
 
 }
+// #enddocregion

public/docs/ts/latest/cookbook/a11y.jade

@@ -36,14 +36,21 @@ include ../_util-fns
 
 .l-sub-section
   :marked
-    Use this method to label your `form controls` as far as possible. As you will see later the other methods of 
-    labelling relies on generating unique id's for your elements. And as we are often building re-usable components
-    in Angular 2, you will need to insure that every id you create is unique on a page, no matter how often your
-    component is used! Save yourself the trouble and label implicitly.
+    `ARIA`, or `Accessible Rich Internet Applications` refers to bringing `a11y` concepts into
+    internet applications like those we are building with Angular 2.
 
 :marked
   You can also see what they say about [ARIA](https://www.w3.org/WAI/intro/aria) at the `W3C`. We will be right here
   waiting for you when you come back.
+  
+.callout.is-important
+    header ARIA terminology confusion alert!
+    :marked
+      In `ARIA` we refer to the `aria-...` attributes as `ARIA States` or `ARIA Properties`. The difference between
+      the two should become clear as you progress through this cookbook. However, `ARIA Properties` are not 
+      actual `HTML` element properties but decorating attributes refering to properties. When we refer to setting an 
+      `ARIA Property` in the code you will **HAVE** to do
+      it with an Angular 2 attribute binding. This is simply a terminology clash.
 
 .l-main-section
 :marked
@@ -107,6 +114,12 @@ include ../_util-fns
 
   [Managing focus](#managin-focus)
 
+.l-sub-section
+  :marked
+    In the example application code when we require unique element id's we will be generating `GUID's`to ensure that they are 
+    unique. You can use your own method to do this, as long as every id on a page is unique. More on this later...
+
+:marked
   **Feel free to follow along in this [live example](/resources/live-examples/cb-a11y/ts/plnkr.html)**.
 
 .l-main-section
@@ -277,46 +290,86 @@ code-example(language="html" escape="html").
 :marked
   ### Labelling custom form controls
 
-  So you have been asked to do something and try as you might you cannot find a native `HTML` element to do the job
-  **OR** you are want to give that legacy application an `a11y` makeover without having the luxury to rewrite the
+  So you have been asked to do something and try as you might you cannot construct this with native `HTML` elements
+  **OR** you are want to give that legacy application an `a11y` makeover without the luxury of rewriting the
   entire codebase.
 
   How would you go about making these custom form controls accessible?
 
-  Fear not, there is a way!
-
-  To avoid writing many lines of code as an example we will create an input field out of a `div`. Rest assured,
-  not using the native `HTML` elements in practise will cost a lot more code than this to make it fully functional.
-  Everytime you bend this rule your codebase will grow and become more complex.
-
-  Component template:
+  Fear not, there is a way! We introduce the next addition to our `ARIA` toolkit, and that is `aria-labeledby`. 
+  
+  Why do we need this? Because the native `a11y` function of the `label` element is only recognised when used with 
+  native `HTML` form control elements such as `input` and `textarea`. To label anything else, like a `div` or a 
+  `custom element` we need to create the the link using `aria-labelledby`. 
+  
+  Lets illustrate this by recreating the native `input` element with a component that makes use of `div's`.
+  
+.l-sub-section
+  :marked
+    Please note that creating an `input` out of `div's` is **NOT** recommended, but only serves as an illustration that
+    it is possible to make any form controll accessible. And as we are focussing on `a11y`, our component will also not 
+    be production ready but only
+    implement the basics of functionality to make it function as an `input` i.e. adding the machinery to make it play nice
+    with `ngModel`. This implementation would need to become
+    even larger and more complex before it can be used in an enterprise application. We hope that this illustrates
+    further why the native `HTML` elements should preferably be used.
+    
+:marked
+  Our component:
 
-+makeExample('cb-a11y/ts/app/form-controls/a11y-custom-control.component.html')
++makeTabs('cb-a11y/ts/app/form-controls/a11y-custom-control.component.html,cb-a11y/ts/app/form-controls/a11y-custom-control.component.ts,cb-a11y/ts/app/form-controls/a11y-custom-control.component.css',
+null, 'a11y-custom-control.component.html,a11y-custom-control.component.ts, a11y-custom-control.component.css')
 
 :marked
-  User writes:
+  This can now be used in our `HTML` as follows:
 
 +makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-custom-control-usage')
 
 :marked
-  Rendered out:
+  Lets have a look at what is rendered out. *For clarity sake, the style attributes added by Angular 2 for the component 
+  style have been omitted.*:
 
 code-example(language="html" escape="html" format="linenums").
-  <a11y-custom-control>
+  <a11y-custom-control class="ng-pristine ng-valid ng-untouched">
     <div class="form-group">
-      <label id="9db87459-2e0d-49ea-a8bf-bb7a3a599858">
+      <label id="60e9545d-8c5c-4c55-f171-e266c50479e9">
         Write in this labelled div:
       </label>
-      <div class="form-control" contenteditable="" role="textbox" aria-labelledby="9db87459-2e0d-49ea-a8bf-bb7a3a599858"></div>
+      <div aria-multiline="true" class="form-control edit-box" contenteditable=""
+           role="textbox" aria-labelledby="60e9545d-8c5c-4c55-f171-e266c50479e9"></div>
     </div>
   </a11y-custom-control>
 
+:marked
+  The first thing that we should note is the `role` attribute. This is also part of `ARIA` and we use these when we need
+  to tell assistive technologies the functional role a component has. We need to specify this when we are not using the
+  native `HTML` elements. For those elements the role is already defined. Here, our custom control needs the role of 
+  `textarea`. We will look at `ARIA Roles` in more detail later.
+  
+  Next we will look at the `aria-labelledby` attribute. As you can see this contains the `id` of the `label` field. This
+  is how we tell screen readers to use that specific `label` element to label our input control.
+
 .l-sub-section
   :marked
-    In the example application code we are generating `GUID's` for id's to ensure that they are unique. You can use your
-    own method to do this, as long as every id on a page is unique.
-
-
+    Aside from having to generate unique `id's`, there is one more caveat to using `aria-labelledby`. Even when using this
+    with an actual `label` element, clicking the label will **NOT** focus the input as it does when used with native 
+    `HTML` form control elements. Therefore this construct will always be slightly inferior to the native approach, as you lose the
+    accessibility gain the `label click` gives you.
+    
+:marked
+  And finally, while you were not looking we snuck in yet another `ARIA` property called `aria-multiline`. Yes folks,
+  someone unable to see what is happening also needs to know if our input accepts single or multiple lines of input. Using
+  `aria-multiline`, we are able to tell the screan reader if it is single or multiline and the screen reader will even
+  read this information back to the user.
+  
+  That was certainly a mouthful! Isn't there a middle way where we can use the power of Angular&nbsp;2 but keep the 
+  built-in `a11y` wins the native `HTML` elements give us?
+  
+  There certainly are. Let's look at one option that uses `Content Projection`.
+  
+  
+  
+  
 .l-main-section
 <a id="keyboard-shortcuts"></a>
 :marked
@@ -336,4 +389,4 @@ code-example(language="html" escape="html" format="linenums").
 :marked
   ## Managing focus
 
-  Content coming soon...r
+  Content coming soon...