docs(reactive-forms): Add Validators section, update screenshots and examples

Author: kapunahelewong

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

@@ -11,4 +11,5 @@ <h3><i>A FormGroup with a single FormControl using FormBuilder</i></h3>
 
 <!-- #docregion form-value-json -->
 <p>Form value: {{ heroForm.value | json }}</p>
+<p>Form status: {{ heroForm.status | json }}</p>
 <!-- #enddocregion form-value-json  -->

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

@@ -19,7 +19,9 @@ export class HeroDetailComponent3 {
 
   createForm() {
     this.heroForm = this.fb.group({
-      name: ['', Validators.required ], // <--- the FormControl called "name"
+      // #docregion required
+      name: ['', Validators.required ],
+      // #enddocregion required
     });
   }
 }

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

@@ -0,0 +1,26 @@
+/* tslint:disable:component-class-suffix */
+// #docregion imports
+import { Component }              from '@angular/core';
+import { FormBuilder, FormGroup } from '@angular/forms';
+// #enddocregion imports
+
+@Component({
+  moduleId: module.id,
+  selector: 'hero-detail-3',
+  templateUrl: './hero-detail-3.component.html'
+})
+// #docregion v3a
+export class HeroDetailComponent3 {
+  heroForm: FormGroup; // <--- heroForm is of type FormGroup
+
+  constructor(private fb: FormBuilder) { // <--- inject FormBuilder
+    this.createForm();
+  }
+
+  createForm() {
+    this.heroForm = this.fb.group({
+      name: '', // <--- the FormControl called "name"
+    });
+  }
+}
+// #enddocregion v3a

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

@@ -14,8 +14,11 @@ a#toc
   - [Create a _reactive forms_ component](#create-component)
   - [Create its template file](#create-template)
   - [Import the _ReactiveFormsModule_](#import)
-  - [Update the app to use the form component](#update)
+  - [Display the _HeroDetailComponent_](#update)
+  - [Add a FormGroup](#formgroup)
+  - [Taking a look at the form model](#json)
   - [Introduction to _FormBuilder_](#formbuilder)
+  - [Validators.required](#validators)
   - [Nested FormGroups](#grouping)
   - [Inspect _FormControl_ properties](#properties)
   - [Set form model data using _setValue_ and _patchValue_](#set-data)
@@ -175,9 +178,6 @@ a#create-template
 
 +makeExample('reactive-forms/ts/app/hero-detail-1.component.html', 'simple-control','app/hero-detail.component.html')(format=".")
 
-
-//- +makeExample('reactive-forms/ts/app/hero-detail-2.component.html', 'basic-form','app/hero-detail.component.html')(format=".")
-
 .l-sub-section
   :marked
     Disregard the `form-control` _CSS_ class. It belongs to the 
@@ -328,7 +328,7 @@ a#formbuilder
   clutter by handling details of control creation for you. 
 
   To use `FormBuilder`, you need to import it into `hero-detail.component.ts`:
-+makeExample('reactive-forms/ts/app/hero-detail-3.component.ts', 'imports','app/hero-detail.component.ts (excerpt)')(format=".")
++makeExample('reactive-forms/ts/app/hero-detail-3a.component.ts', 'imports','app/hero-detail.component.ts (excerpt)')(format=".")
 
 :marked
   Use it now to refactor the `HeroDetailComponent` into something that's a little easier to read and write,
@@ -340,7 +340,7 @@ a#formbuilder
   * Call `createForm` in the constructor.
 
   The revised `HeroDetailComponent` looks like this:
-+makeExample('reactive-forms/ts/app/hero-detail-3.component.ts', 'v3','app/hero-detail.component.ts (excerpt)')(format=".")
++makeExample('reactive-forms/ts/app/hero-detail-3a.component.ts', 'v3a','app/hero-detail.component.ts (excerpt)')(format=".")
 
 :marked
   `FormBuilder.group` is a factory method that creates a `FormGroup`.  
@@ -350,6 +350,45 @@ a#formbuilder
   Defining a group of controls in a single object makes for a compact, readable style.
   It beats writing an equivalent series of `new FormControl(...)` statements.
 
+a#validators
+:marked
+ ### Validators.required
+ 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:
++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`.  
+
++makeExample('reactive-forms/ts/app/hero-detail-3.component.ts', 'required','app/hero-detail.component.ts (excerpt)')(format=".")
+
+: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:
+
++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`:
+
+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`. 
+  
+  Using `Validators.required` is optional for the rest of the guide. 
+  You may remove it as what follows does not use it.
+
+  For more on validating Angular forms, see the
+  [Form Validation](../cookbook/form-validation.html) guide. 
+
 :marked
   ### More FormControls
   A hero has more than a name. A hero has an address too. You already have address data 
@@ -480,7 +519,7 @@ table(width="100%")
 
   One common reason for inspecting `FormControl` properties is to 
   make sure the user entered valid values. 
-  Read about validating Angular forms in the 
+  Read more about validating Angular forms in the 
   [Form Validation](../cookbook/form-validation.html) guide. 
 
 .l-main-section