docs(reactive-forms): re-write save for simplicity; delete much pedantry

Author: wardbell

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

@@ -17,7 +17,9 @@ import { Hero, states } from './data-model';
 })
 // #docregion v5
 export class HeroDetailComponent5 implements OnChanges {
+  // #docregion hero
   @Input() hero: Hero;
+  // #enddocregion hero
 
   heroForm: FormGroup;
   states = states;

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

@@ -1,4 +1,5 @@
 /* tslint:disable:component-class-suffix */
+// #docplaster
 // #docregion imports
 import { Component, Input, OnChanges } from '@angular/core';
 import { FormBuilder, FormGroup }      from '@angular/forms';
@@ -31,9 +32,25 @@ export class HeroDetailComponent6 implements OnChanges {
     // #enddocregion address-form-group
   }
 
-  // #docregion set-value-on-changes
+  // #docregion ngOnChanges
   ngOnChanges() {
+    this.heroForm.reset({
+      name: this.hero.name,
+      address: this.hero.addresses[0] || new Address()
+    });
+  }
+  // #enddocregion ngOnChanges
+
+  /* First version of ngOnChanges
+  // #docregion ngOnChanges-1
+  ngOnChanges()
+  // #enddocregion ngOnChanges-1
+  */
+  ngOnChanges1() {
+    // #docregion reset
     this.heroForm.reset();
+    // #enddocregion reset
+    // #docregion ngOnChanges-1
     // #docregion set-value
     this.heroForm.setValue({
       name:    this.hero.name,
@@ -43,7 +60,6 @@ export class HeroDetailComponent6 implements OnChanges {
     });
     // #enddocregion set-value
   }
-  // #enddocregion set-value-on-changes
-
+  // #enddocregion ngOnChanges-1
 }
 

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

@@ -38,11 +38,9 @@ export class HeroDetailComponent7 implements OnChanges {
 
   // #docregion onchanges
   ngOnChanges() {
-    // #docregion reset-refactor
     this.heroForm.reset({
       name: this.hero.name
     });
-    // #enddocregion reset-refactor
     this.setAddresses(this.hero.addresses);
   }
   // #enddocregion onchanges

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

@@ -1,11 +1,12 @@
-// tslint:disable:no-unused-variable
 // #docplaster
 // #docregion
-// #docregion imports
-import { Component, EventEmitter, Input, Output, OnChanges } from '@angular/core';
-import { FormArray, FormBuilder, FormControl, FormGroup } from '@angular/forms';
+import { Component, Input, OnChanges }       from '@angular/core';
+import { FormArray, FormBuilder, FormGroup } from '@angular/forms';
+
 import { Address, Hero, states } from './data-model';
-// #enddocregion imports
+// #docregion import-service
+import { HeroService }           from './hero.service';
+// #enddocregion import-service
 
 // #docregion metadata
 @Component({
@@ -16,9 +17,6 @@ import { Address, Hero, states } from './data-model';
 // #enddocregion metadata
 export class HeroDetailComponent implements OnChanges {
   @Input() hero: Hero;
-  // #docregion save-emitter
-  @Output() save = new EventEmitter<Hero>();
-  // #enddocregion save-emitter
 
   heroForm: FormGroup;
   // #docregion log-name-change
@@ -27,7 +25,10 @@ export class HeroDetailComponent implements OnChanges {
   states = states;
 
   // #docregion ctor
-  constructor(private fb: FormBuilder) {
+  constructor(
+    private fb: FormBuilder,
+    private heroService: HeroService) {
+
     this.createForm();
     this.logNameChange();
   }
@@ -41,8 +42,7 @@ export class HeroDetailComponent implements OnChanges {
   }
 
   ngOnChanges() {
-    this.heroForm.reset();
-    this.heroForm.patchValue({
+    this.heroForm.reset({
       name: this.hero.name
     });
     this.setAddresses(this.hero.addresses);
@@ -64,23 +64,23 @@ export class HeroDetailComponent implements OnChanges {
 
   // #docregion on-submit
   onSubmit() {
-    const saveHero: Hero = this.prepareSaveHero();
-    this.save.emit(saveHero); // let parent decide what to do
-    console.log(saveHero);    // diagnostic
+    this.hero = this.prepareSaveHero();
+    this.heroService.updateHero(this.hero);
+    this.ngOnChanges();
   }
   // #enddocregion on-submit
 
   // #docregion prepare-save-hero
-  prepareSaveHero() {
+  prepareSaveHero(): Hero {
     const formModel = this.heroForm.value;
 
     // deep copy of form model lairs
     const secretLairsDeepCopy: Address[] = formModel.secretLairs.map(
       (address: Address) => Object.assign({}, address)
     );
 
-    // `saveHero` contains only original hero value(s) or
-    // deep copies of changed form model values
+    // return new `Hero` object containing a combination of original hero value(s)
+    // and deep copies of changed form model values
     const saveHero: Hero = {
       id: this.hero.id,
       name: formModel.name as string,
@@ -97,7 +97,7 @@ export class HeroDetailComponent implements OnChanges {
 
   // #docregion log-name-change
   logNameChange() {
-    const nameControl = this.heroForm.get('name') as FormControl;
+    const nameControl = this.heroForm.get('name');
     nameControl.valueChanges.forEach(
       (value: string) => this.nameChangeLog.push(value)
     );

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

@@ -12,6 +12,6 @@ <h3 *ngIf="heroes">Select a hero:</h3>
   <h2>Hero Detail</h2>
   <h3>Editing: {{selectedHero.name}}</h3>
   <!-- #docregion hero-binding -->
-  <hero-detail [hero]="selectedHero" (save)="onSave($event)"></hero-detail>
+  <hero-detail [hero]="selectedHero"></hero-detail>
   <!-- #enddocregion hero-binding -->
 </div>

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

@@ -25,13 +25,4 @@ export class HeroListComponent implements OnInit {
   }
 
   select(hero: Hero) { this.selectedHero = hero; }
-
-  onSave(hero: Hero) {
-    this.heroService.updateHero(hero)
-        .then(() => this.getHeroes())
-        .then(() => {
-          const newHero = this.heroes.find(h => h === hero);
-          this.select(newHero);
-        });
-  }
 }

public/docs/_examples/reactive-forms/ts/app/hero.service.ts

@@ -19,7 +19,8 @@ export class HeroService {
       // simulate server latency with delay
       const ix = heroes.findIndex(h => h.id === hero.id);
       setTimeout(() => {
-        heroes[ix] = hero;
+        // Demo: mutate cached hero
+        Object.assign(heroes[ix], hero);
         resolve(hero);
       }, 500);
     });

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

@@ -56,16 +56,9 @@ a#intro
   the form controls and pull user-changed values back out. The component can 
   observe changes in form control state and react to those changes.
 
-  In keeping with the reactive paradigm, the component  
-  preserves the immutability of the _data model_,
-  treating it as a pure source of original values.
-  Rather than update the data model directly, 
-  the component extracts user changes and forwards them to an external component or service,
-  which does something with them (such as saving them) 
-  and returns a new _data model_ to the component that reflects the updated model state.
-
-  Using reactive form directives does not require you to follow all reactive priniciples,
-  but it does facilitate the reactive programming approach should you choose to use it.
+  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.
 
   ### _Template-driven_ forms
 
@@ -542,55 +535,48 @@ a#set-data
 
   Now you know _how_ to set the _form model_ values. But _when_ do you set them?
   The answer depends upon when the component gets the _data model_ values.
-  
-  If the `HeroDetailComponent` is editing a _new_ hero, the data model consists entirely of default values
-  that you could copy to the `FormControls` when you create them in the component's constructor.
-  That's effectively what you did when you set each control to the empty string.
-
-  If the `HeroDetailComponent` is editing an _existing_ hero, you have to wait for that hero to arrive.
-  The component _might_ have the ability to retrieve the hero from the server (via an injected data service)
-  in which case you could set the form model in the [ngOnInit](lifecyle-hooks.html#oninit) lifecycle hook.
-  The final version of the `HeroDetailComponent` in the [Tour of Heroes](../tutorial/toh-pt6.html) does it this way.
 
-  The `HeroDetailComponent` in this reactive forms sample works a little differently.
-  It's the _detail_ view nested within a _master/detail_ `HeroListComponent` ([discussed below](#hero-list)).
-  
+  The `HeroDetailComponent` in this reactive forms sample is nested within a _master/detail_ `HeroListComponent` ([discussed below](#hero-list)).
   The `HeroListComponent` displays hero names to the user.
   When the user clicks on a hero, the list component passes the selected hero into the `HeroDetailComponent`
-  by **binding to the latter's `hero` input property**.
+  by binding to its `hero` input property.
 
 +makeExample('reactive-forms/ts/app/hero-list.component.1.html', '','hero-list.component.html (simplified)')(format=".")
 
 :marked
   In this approach, the value of `hero` in the `HeroDetailComponent` changes 
   every time the user selects a new hero.
-  You can't call _setValue_ in `ngOnInit` or you'll miss the user's selections.
-  Put the _setValue_ logic in the [ngOnChanges](lifecyle-hooks.html#onchanges)
-  hook, which Angular calls whenever the input `hero` property changes.
+  You should call  _setValue_ in the [ngOnChanges](lifecyle-hooks.html#onchanges)
+  hook, which Angular calls whenever the input `hero` property changes
+  as the following steps demonstrate.
 
-  You should also _reset the form_ when the hero changes so that 
-  control values from the previous hero are cleared and 
-  status flags are restored to the _pristine_ state.
+  First, import the `ngOnChanges` and `import` symbol in `hero-detail.component.ts`.
 
-  In order to use `ngOnChanges`, add it to the `hero-detail.component.ts` 
-  imports.
++makeExample('reactive-forms/ts/app/hero-detail-5.component.ts', 'import-input','app/hero-detail.component.ts (core imports)')(format=".")
 
-+makeExample('reactive-forms/ts/app/hero-detail-5.component.ts', 'imports','app/hero-detail.component.ts (excerpt)')(format=".")
+:marked
+  Add the `hero` input property.
++makeExample('reactive-forms/ts/app/hero-detail-5.component.ts', 'hero')(format=".")
 
 :marked
-  Here's what `ngOnChanges` should look like:
+  Add the `ngOnChanges` method to the class as follows:
 
-+makeExample('reactive-forms/ts/app/hero-detail-6.component.ts', 'set-value-on-changes','app/hero-detail.component.ts (excerpt)')(format=".")
++makeExample('reactive-forms/ts/app/hero-detail-6.component.ts', 'ngOnChanges-1','app/hero-detail.component.ts (ngOnchanges)')(format=".")
 
 :marked
-  You could, however, reset the value of the *formControls* in the `reset()` 
-  method by refactoring. 
-  ## Ward, are the benefits that now you can dispense with `setValue` (so less code 
-  ## and you don't have to set everything)? In `hero-detail-7.component.ts`, we also have 
-  ## `this.setAddresses(this.hero.addresses);` in `ngOnChanges`. 
-  ## Do I need to include it and talk about it? 
+  ### _reset_ the form flags
+
+  You should  reset the form when the hero changes so that 
+  control values from the previous hero are cleared and 
+  status flags are restored to the _pristine_ state.
+  You could call `reset` at the top of `ngOnChanges` like this.
++makeExample('reactive-forms/ts/app/hero-detail-6.component.ts', 'reset')(format=".")
 
-+makeExample('reactive-forms/ts/app/hero-detail-7.component.ts', 'reset-refactor','app/hero-detail.component.ts (excerpt)')(format=".")
+:marked
+  The `reset` method has an optional `state` value so you can reset the flags _and_ the control values at the same. 
+  Internally, `reset` passes the argument to `setValue`. 
+  A little refactoring and `ngOnChanges` becomes this:
++makeExample('reactive-forms/ts/app/hero-detail-6.component.ts', 'ngOnChanges', 'app/hero-detail.component.ts (ngOnchanges - revised)')(format=".")
 
 a#hero-list
 :marked
@@ -611,12 +597,11 @@ figure.image-display
 
   When the user clicks on a hero,
   the component sets its `selectedHero` property which
-  is **bound to the `hero` input property** of the `HeroDetailComponent`.
+  is bound to the `hero` input property of the `HeroDetailComponent`.
   The `HeroDetailComponent` detects the changed hero and re-sets its form
   with that hero's data values.
 
   A "Refresh" button clears the hero list and the current selected hero before refetching the heroes.
-  The `HeroListComponent` also has an `onSave` method that you'll wire up later in this guide.
 
   The remaining `HeroListComponent` and `HeroService` implementation details are not relevant to understanding reactive forms.
   The techniques involved are covered elsewhere in the documentation, including the _Tour of Heroes_
@@ -684,7 +669,7 @@ a#form-array
   You need a method to populate (or repopulate) the _secretLairs_ with actual hero addresses whenever
   the parent `HeroListComponent` sets the `HeroListComponent.hero` input property to a new `Hero`.
 
-  The following method replaces the _secretLairs_ `FormArray` with a new `FormArray`,
+  The following `setAddresses` method replaces the _secretLairs_ `FormArray` with a new `FormArray`,
   initialized by an array of hero address `FormGroups`.
 +makeExample('reactive-forms/ts/app/hero-detail-7.component.ts', 'set-addresses')(format=".")
 
@@ -780,9 +765,9 @@ a#observe-control
   that raises a change event.
 
   These are properties, such as `valueChanges`, that return an RxJS `Observable`.
-  You don't need to know much about RxJS `Observable` to watch for a form control value change.
+  You don't need to know much about RxJS `Observable` to monitor form control values.
 
-  Add the following method to watch for changes to the value of the _name_ `FormControl`.
+  Add the following method to log changes to the value of the _name_ `FormControl`.
 +makeExample('reactive-forms/ts/app/hero-detail.component.ts', 'log-name-change','app/hero-detail.component.ts (logNameChange)')(format=".")
 
 :marked
@@ -819,53 +804,33 @@ figure.image-display
 
 :marked
   ### Save
-  In this sample application, the `HeroDetailComponent` cannot perform the save operation. 
-  The component delegates that chore to its parent `HeroListComponent`.
-  
-  When the user clicks the _Save_ button, the `HeroDetailComponent` raises a save event on its `save` output property.
-  The parent `HeroListComponent`, which binds to that property, responds to the event and processes the event payload.
-+makeExample('reactive-forms/ts/app/hero-list.component.html', 'hero-binding','app/hero-list.component.html (save event binding)')(format=".")
-:marked
-  The save event payload _could_ have any shape but often it's in the shape of the data model and that is the case in this example.
-+makeExample('reactive-forms/ts/app/hero-detail.component.ts', 'save-emitter')(format=".")
-
-:marked
-  The `HeroDetailComponent` save method (`onSubmit`) constructs a `saveHero`
-  and emits a save message, with `saveHero` as the payload, for the `HeroListComponent` to process.
-
+  In this sample application, when the user submits the form,
+  the `HeroDetailComponent` will pass an instance of the hero _data model_
+  to a save method on the injected `HeroService`.
 +makeExample('reactive-forms/ts/app/hero-detail.component.ts', 'on-submit','app/hero-detail.component.ts (onSubmit)')(format=".")
 :marked
-  In the reactive paradigm, the _data model_ is immutable so the save method can't update the component's `hero`
-  and send that as the save event payload.
-
-  Instead, it must prepare `saveHero` whose values derive from a combination of original hero values (the `hero.id`)
-  and deep copies of the potentially-changed form model values. 
-  
-  ## Ward, stop lecturing :D
+  This original `hero` had the pre-save values. The user's changes are still in the _form model_.
+  So you create a new `hero` from a combination of original hero values (the `hero.id`)
+  and deep copies of the changed form model values, using the `prepareSaveHero` helper. 
 
 +makeExample('reactive-forms/ts/app/hero-detail.component.ts', 'prepare-save-hero','app/hero-detail.component.ts (prepareSaveHero)')(format=".")
 
-:marked
-  In the reactive paradigm, the form model and its object contents must not leak out of the component.
-  The `saveHero` in the event payload must be completely disconnected from the form model.
-  Ideally, it is as immutable as the component's source `hero`.
-
-  If you assign the `formModel.secretLairs` to `saveHero.addresses` (see line commented out),
-  the addresses in the `saveHero.addresses` array will be the same objects 
-  as the lairs in the `formModel.secretLairs`.
-  A user's subsequent changes to a lair street will mutate an address street in the `saveHero`.
-  The `prepareSaveHero` method makes copies of the form model's `secretLairs` objects so that can't happen.
+.l-sub-section
+  :marked
+    **Address deep copy**
 
-  Keeping data immutable takes effort and vigilance.
-  Consider using an immutable helper library such as 
-  <a href="https://facebook.github.io/immutable-js/" target="_blank" title="Immutable">Immutable.js</a>.
+    Had you assigned the `formModel.secretLairs` to `saveHero.addresses` (see line commented out),
+    the addresses in `saveHero.addresses` array would be the same objects 
+    as the lairs in the `formModel.secretLairs`.
+    A user's subsequent changes to a lair street would mutate an address street in the `saveHero`.
+    
+    The `prepareSaveHero` method makes copies of the form model's `secretLairs` objects so that can't happen.
 
 :marked
   ### Revert (cancel changes)
   The user cancels changes and reverts the form to the original state by pressing the _Revert_ button.
 
-  Reverting is easy. Simply re-execute the `ngOnChanges` method that built the _form model_ from the current `hero` _data model_.
-  The immutability rule guarantees that the `hero` hasn't changed.
+  Reverting is easy. Simply re-execute the `ngOnChanges` method that built the _form model_ from the original, unchanged `hero` _data model_.
 +makeExample('reactive-forms/ts/app/hero-detail.component.ts', 'revert','app/hero-detail.component.ts (revert)')(format=".")
 
 :marked
@@ -894,7 +859,7 @@ figure.image-display
   - Inspecting `FormControl` properties.
   - Setting data with `patchValue` and `setValue`.
   - Adding groups dynamically with `FormArray`.
-  - Watching for changes to the value of a `FormControl`.
+  - Observing changes to the value of a `FormControl`.
   - Saving form changes.
 
 a#source-code