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

Author: AlmeroSteyn

public/docs/_examples/cb-a11y/ts/a11y.css

@@ -12,6 +12,7 @@ hr {
     color: #fff;
 }
 
+/* #docregion cb-a11y-form-controls-visually-hidden-style*/
 .visually-hidden {
   border: 0;
   clip: rect(0 0 0 0);
@@ -22,25 +23,4 @@ hr {
   position: absolute;
   width: 1px;
 }
-
-/*This is a copy of the .form-control class in bootstrap
-to enable adding it to all form controls without to much
-noise in the examples.*/
-/*div:not(.radio):not(.checkbox) input, textarea, select {*/
-     /*display: block;*/
-     /*width: 100%;*/
-     /*height: 34px;*/
-     /*padding: 6px 12px;*/
-     /*font-size: 14px;*/
-     /*line-height: 1.42857143;*/
-     /*color: #555;*/
-     /*background-color: #fff;*/
-     /*background-image: none;*/
-     /*border: 1px solid #ccc;*/
-     /*border-radius: 4px;*/
-     /*-webkit-box-shadow: inset 0 1px 1px rgba(0,0,0,.075);*/
-     /*box-shadow: inset 0 1px 1px rgba(0,0,0,.075);*/
-     /*-webkit-transition: border-color ease-in-out .15s,-webkit-box-shadow ease-in-out .15s;*/
-     /*-o-transition: border-color ease-in-out .15s,box-shadow ease-in-out .15s;*/
-     /*transition: border-color ease-in-out .15s,box-shadow ease-in-out .15s;*/
- /*}*/
+/* #enddocregion */

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

@@ -174,9 +174,14 @@ code-example(language="html" escape="html").
 :marked
   #### Inputs and textareas
 
-+makeTabs('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html, cb-a11y/ts/app/form-controls/a11y-form-controls.component.html', 
-'cb-a11y-form-controls-input-implicit,cb-a11y-form-controls-textarea-implicit', 
-'Implicitly labelled input,Implicitly labelled textarea')
+  Labelling an input:
+
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-input-implicit')
+  
+:marked
+  Labelling a textarea:
+  
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-textarea-implicit')  
 
 :marked
   #### Checkboxes and radiobuttons
@@ -186,10 +191,16 @@ code-example(language="html" escape="html").
     Because of the many `input` fields making up a `checkbox group` or `radiobutton group`, the usual rule applies 
     for each input but the entire group also needs labelled and this is done by using `fieldset` and `legend`.
 
-+makeTabs('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html, cb-a11y/ts/app/form-controls/a11y-form-controls.component.html',
-'cb-a11y-form-controls-checkboxes-implicit,cb-a11y-form-controls-radiobuttons-implicit',
-'Implicitly labelled Checkboxes,Implicitly labelled Radiobuttons')
+:marked
+  Labelling checkboxes:
+    
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-checkboxes-implicit')
 
+:marked
+  Labelling radiobuttons:
+
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-radiobuttons-implicit')
+  
 :marked
   #### Select lists
 
@@ -206,42 +217,13 @@ code-example(language="html" escape="html").
   the `HTML` form element. This is then connected up up via a `for / id` pairing *[The `for` attribute of the label has to
   match the `id` of the element being labelled]* .
 
-  This is also the reason why `implicit labelling` could be more useful with reusable Angular 2 components.
-  Remember that an `id` should be unique on a page. This means that any component with `explicit labelling` in its
-  template, will need a way ensure that its elements are uniquely labelled, unless it is certain that the component
-  will only be used once per page.
+  Remember, this is why we said that `implicit labelling` is recommended due to the extra code you may required to keep
+  the id's unique per page.
 
-  As an example, we will only look at adding an `explicit label` to an `input`. The examples under the `implicit labelling`
+  As an example, we will only look at adding an `explicit label` to a `text input`. The examples under the `implicit labelling`
   section can then easily be adjusted to use this syntax.
 
-.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.
-
-:marked
-  Component template:
-
-+makeExample('cb-a11y/ts/app/form-controls/a11y-input-explicit.component.html')
-
-:marked
-  User writes:
-
-+makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-input-explicit-usage')
-
-:marked
-  Rendered out:
-
-code-example(language="html" escape="html" format="linenums").
-  <a11y-input-explicit>
-      <div class="form-group">
-          <label for="c90c7f99-330e-4723-bfa8-9ab72a4bd435">
-              Label for input:
-          </label>
-          <input class="form-control"
-                 id="c90c7f99-330e-4723-bfa8-9ab72a4bd435">
-      </div>
-  </a11y-input-explicit>
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html', 'cb-a11y-form-controls-input-explicit')
 
 :marked
   ### Hidden labels
@@ -265,27 +247,32 @@ code-example(language="html" escape="html" format="linenums").
     shrinking it right down to be absolutely minute. We wont see it but screen readers will still find it and read it while
     still linking it to the correct input via the `for / id` linkup. The following example contains such a
     `visually hidden` style.
-
+    
 :marked
-  Let us create a component showing off both, and use the internal component styles to hide the label.
-
-+makeTabs('cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.html, cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.ts, cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.css', null, 'a11y-hidden-labels.component.html,a11y-hidden-labels.component.ts,a11y-hidden-labels.component.css')
-
+  Example of a good visually hidden css style:
+  
++makeExample('cb-a11y/ts/a11y.css', 'cb-a11y-form-controls-visually-hidden-style')
+    
 :marked
-  Which can then be used as:
+ Applying the style to a control to hide the label:
 
-+makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-hidden-labels-usage')
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html', 'cb-a11y-form-controls-hidden-label-explicit')
 
 :marked
-  The way the label is rendered int he final `HTML` is no secret to us anymore, but when you inspect the second input,
-  you will see that an `aria-label` attribute has been added to the input. Simplified:
+  Alternatively labelling a control with `aria-label`:
 
-code-example(language="html" escape="html" format="linenums").
-  <input aria-label="Filter:">
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-hidden-label-aria')
 
 :marked
-  This `aria-label` attribute serves the same purpose as our `LABEL` tags above and will tell screen readers what
+  This `aria-label` attribute serves the same `a11y` purpose as our `label` tags above and will tell screen readers what
   the field is called.
+  
+.l-sub-section
+  :marked
+    So why not simply always use `aria-label`? This is because adding the `label` element not only provides the visual
+    label, but linking a `label` to a `form control` also means that clicking on the `label` will select the 
+    `form control` itself. This touches on another area of `a11y`, as this also assists users with motor disabilites 
+    to more easily select them.  
 
 :marked
   ### Labelling custom form controls
@@ -324,6 +311,11 @@ code-example(language="html" escape="html" format="linenums").
     </div>
   </a11y-custom-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.
+
 
 .l-main-section
 <a id="keyboard-shortcuts"></a>