docs(reactive-forms): Ward's tweaks on jan 23

Author: wardbell

public/docs/_examples/reactive-forms/ts/app/hero-detail-3.component.ts

@@ -18,11 +18,11 @@ export class HeroDetailComponent3 {
   }
 
   createForm() {
+    // #docregion required
     this.heroForm = this.fb.group({
-      // #docregion required
       name: ['', Validators.required ],
-      // #enddocregion required
     });
+    // #enddocregion required
   }
 }
 // #enddocregion v3

public/docs/_examples/reactive-forms/ts/app/hero-detail-4.component.html

@@ -26,13 +26,14 @@ <h3><i>A FormGroup with multiple FormControls</i></h3>
   </div>
   <div class="form-group">
     <label>Super power:</label>
-      <input type="radio" formControlName="power" value="flight">Flight
-      <input type="radio" formControlName="power" value="x-ray vision">X-ray vision
-      <input type="radio" formControlName="power" value="strength">Strength
+      <label><input type="radio" formControlName="power" value="flight">Flight</label>
+      <label><input type="radio" formControlName="power" value="x-ray vision">X-ray vision</label>
+      <label><input type="radio" formControlName="power" value="strength">Strength</label>
   </div>
   <div class="checkbox">
     <label>
-      <input type="checkbox" formControlName="sidekick">I have a sidekick.</label>
+      <input type="checkbox" formControlName="sidekick">I have a sidekick.
+    </label>
   </div>
 </form>
 

public/docs/ts/latest/guide/reactive-forms.jade

@@ -25,7 +25,6 @@ a#toc
   - [Use _FormArray_ to present an array of _FormGroups_](#form-array)
   - [Observe control changes](#observe-control)
   - [Save form data](#save)
-  - [Appendix: Async vs. sync in Angular forms](a#appendix)
 
   Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker">Reactive Forms live-example</live-example>.
 
@@ -62,8 +61,9 @@ a#intro
   observe changes in form control state and react to those changes.
 
   One advantage of working with form control objects directly is that value and validity updates 
-  are always synchronous and under your control. 
-  You won't encounter the timing issues that sometimes plague a template-driven form.
+  are [always synchronous and under your control](#async-vs-sync "Async vs sync"). 
+  You won't encounter the timing issues that sometimes plague a template-driven form
+  and reactive forms can be easier to unit test.
 
   In keeping with the reactive paradigm, the component 
   preserves the immutability of the _data model_,
@@ -90,19 +90,52 @@ a#intro
   Angular updates the mutable _data model_ with user changes as they happen.
 
   For this reason, the `ngModel` directive is not part of the ReactiveFormsModule.
+
+  While this means less code in the component class, 
+  [template-driven forms are asynchronous](#async-vs-sync "Async vs sync")
+  which may complicate development in more advanced scenarios. 
+
+a#async-vs-sync
+:marked
+  ### Async vs. sync
+
+  Reactive forms are synchronous. Template-driven forms are asynchronous. It's a difference that matters.
+
+  In reactive forms, you create the entire form control tree in code. 
+  You can immediately update a value or drill down through the descendents of the parent form 
+  because all controls are always available.
+
+  Template-driven forms delegate creation of their form controls to directives.
+  To avoid "_changed after checked_" errors, 
+  these directives take more than one cycle to build the entire control tree.
+  That means you must wait a tick before manipulating any of the controls
+  from within the component class.
 
-  These differences reflect two architectural paradigms, 
-  with their own strengths and weaknesses,
-  and you are free to choose between them.
+  For example, if you inject the form control with a `@ViewChild(NgForm)` query and examine it in the 
+  [`ngAfterViewInit` lifecycle hook](lifecycle-hooks.html#afterview "Lifecycle hooks guide: AfterView"),
+  you'll discover that it has no children.
+  You must wait a tick, using `setTimeout`, before you can
+  extract a value from a control, test its validity, or set it to a new value.
+  
+  The asynchrony of template-driven forms also complicates unit testing. 
+  You must wrap your test block in `async()` or `fakeAsync()` to 
+  avoid looking for values in the form that aren't there yet. 
+  With reactive forms, everything is available when you expect it to be.
+
+  ### Which is better, reactive or template-driven? 
 
-  The balance of this _reactive forms_ guide assumes the _reactive_ paradigm and 
-  concentrates exclusively on the reactive forms techniques. For 
-  information on _template driven forms_, see the [Template Guide](forms.html).
+  Neither is "better".
+  They're two different architectural paradigms, 
+  with their own strengths and weaknesses.
+  Choose the approach that works best for you.
+  You may decide to use both in the same application.
 
-  For a further comparison see [Appendix: Async vs. sync in Angular forms](#appendix).
+  The balance of this _reactive forms_ guide explores the _reactive_ paradigm and 
+  concentrates exclusively on reactive forms techniques. 
+  For information on _template-driven forms_, see the [_Forms_](forms.html) guide.
 
   In the next section, you'll set up your project for the reactive form demo.
-  Then you'll [learn about the Angular form classes](#essentials) and how to use them in a reactive form.
+  Then you'll learn about the [Angular form classes](#essentials) and how to use them in a reactive form.
 
 .l-main-section
 a#setup
@@ -361,35 +394,42 @@ a#validators
  Though this guide doesn't go deeply into validations, here is one example that 
  demonstrates the simplicity of using `Validators.required` in reactive forms. 
 
- First, be sure to import it:
+ First, import the `Validators` symbol.
 +makeExample('reactive-forms/ts/app/hero-detail-3.component.ts', 'imports','app/hero-detail.component.ts (excerpt)')(format=".")
 
 :marked
- Then, you can easily make the `name` `FormControl` required by supplying the `name` 
- property in the class with an array that holds two arguments, 
- the initial value for `name` and `Validators.required`. By contrast, 
- in template driven forms, you must wrap validators in a directive. 
- Reactive validators are simple, composable functions.
+ To make the `name` `FormControl` required, replace the `name` 
+ property in the `FormGroup` with an array. 
+ The first item is the initial value for `name`;
+ the second is the required validator, `Validators.required`.
 
 +makeExample('reactive-forms/ts/app/hero-detail-3.component.ts', 'required','app/hero-detail.component.ts (excerpt)')(format=".")
-
+.l-sub-section
+  :marked
+    Reactive validators are simple, composable functions.
+    Configuring validation is harder in template-driven forms where you must wrap validators in a directive. 
 :marked
-  Now, by outputting the form's status in the template, you can see 
-  whether the form is `VALID` or `INVALID`. Add the following to the template:
+  Update the diagnostic message at the bottom of the template to display the form's validity status.
 
 +makeExample('reactive-forms/ts/app/hero-detail-3.component.html', 'form-value-json','app/hero-detail.component.html (excerpt)')(format=".")
 
 :marked
-  The browser displays the form's status according to `Validators.required`:
+  The browser displays the following:
 
 figure.image-display
   img(src="/resources/images/devguide/reactive-forms/validators-json-output.png" width="400px" alt="Single FormControl")
 
 :marked
-  `Validators.required` defaults 
-  to `INVALID` when the input has no value. Type into the input 
-  to watch the status change from `INVALID` to `VALID`. 
+  `Validators.required` is working. The status is `INVALID` because the input box has no value.
+  Type into the input box to see the status change from `INVALID` to `VALID`. 
+
+  In a real app, you'd replace the diagnosic message with a user-friendly experience.
 
+.alert.is-critical
+  :marked
+    Kapunahele: Why not keep it throughout? I know it's a bit of work but it will be useful to see 
+    how you preserve `Validators.required` as you evolve the control tree.
+:marked
   Using `Validators.required` is optional for the rest of the guide. 
   You may remove it as what follows does not use it.
 
@@ -398,16 +438,15 @@ figure.image-display
 
 :marked
   ### More FormControls
-  A hero has more than a name. A hero has an address, a super 
-  power and sometimes a sidekick too. You already have address data 
-  in `data-model.ts`, so add it to the imports so you can use it:
-
+  A hero has more than a name. 
+  A hero has an address, a super power and sometimes a sidekick too. 
+  
+  The address has a state property. The user will select a state with a `<select>` box and you'll populate 
+  the `<option>` elements with states. So import `states` from `data-model.ts`.
 +makeExample('reactive-forms/ts/app/hero-detail-4.component.ts', 'imports','app/hero-detail.component.ts (excerpt)')(format=".")
 
 :marked
-  Add some address `FormControls` to the `heroForm` as follows, being sure to 
-  also declare `states`. This allows you to populate the state select with 
-  the states in `data-model.ts`.
+  Declare the `states` property and add some address `FormControls` to the `heroForm` as follows. 
 
 +makeExample('reactive-forms/ts/app/hero-detail-4.component.ts', 'v4','app/hero-detail.component.ts (excerpt)')(format=".")
 
@@ -427,15 +466,18 @@ figure.image-display
     Angular `FormGroup` and `FormControl` properties in the component class.
 
 :marked
-  These new `FormControls` include text inputs, a select for the state, 
-  radio buttons, and a checkbox. In the class 
-  they are instantiated in the same way and in the template, 
-  each one is tied to the form control tree by specifiying 
-  the `FormControl` name using the `formControlName` directive. 
-  For more information about radio buttons, selects, and checkboxes, 
-  see the API reference for [RadioControlValueAccessor](api/forms/index/RadioControlValueAccessor-directive.html), 
-  [SelectControlValueAccessor](api/forms/index/SelectControlValueAccessor-directive.html), 
-  and [CheckboxControlValueAccessor](api/forms/index/CheckboxControlValueAccessor-directive.html).
+  The revised template includes more text inputs, a select box for the `state`, radio buttons for the `power`, 
+  and a checkbox for the `sidekick`. 
+  
+  The component _class_ defines control properties without regard for their representation in the template.
+  You define the `state`, `power`, and `sidekick` controls the same way you defined the `name` control.
+  You tie these controls to the template HTML elements in the same way, 
+  specifiying the `FormControl` name with the `formControlName` directive. 
+
+  See the API reference for more information about 
+  [radio buttons](api/forms/index/RadioControlValueAccessor-directive.html "API: RadioControlValueAccessor"), 
+  [selects](api/forms/index/SelectControlValueAccessor-directive.html "API: SelectControlValueAccessor"), and
+  [checkboxes](api/forms/index/CheckboxControlValueAccessor-directive.html "API: CheckboxControlValueAccessor").
 
 .l-main-section
 a#grouping
@@ -958,35 +1000,6 @@ figure.image-display
   This is the final step in the demo.
   Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker"></live-example>.
 
-a#appendix
-.l-main-section
-:marked
-  ## Appendix: Async vs. sync in Angular forms
-
-  In a reactive form you create the form control tree, also known as 
-  the form model. Because you aren't delegating the creation of the 
-  form controls to a directive, reactive forms can be synchronous. 
-  This makes the controls easier to work with. You have access to 
-  everything - when you update any  value, or need to access a 
-  children registered on the parent form, they are available immediately.
-
-  To see why this synchronicity matters, a comparison with template 
-  driven forms is helpful. Template driven forms have to be async 
-  because they delegate to directives in the template and must 
-  avoid "changed after checked" errors.  As a result, if you have 
-  a template driven form, and you want to  manipulate it from 
-  within the component class (for example, make a `ViewChild` 
-  query for `NgForm`), you'll see that on init it has 
-  _no children yet_. They're registered asynchronously, so 
-  you'd have to remember have to check on the next tick. 
-  The same goes for updating the value. 
-
-  This also affects testing of template-driven forms. You always 
-  have to wrap your test block in `async()` or `fakeAsync()` to 
-  avoid looking for values in the form that aren't available yet. 
-  With reactive forms, everything is available 
-  when you expect it to be.
-
 
 .l-main-section
 :marked