-
- Name via form.controls = {{showFormControls(heroForm)}}
-
-
-
\ No newline at end of file
+
diff --git a/public/docs/_examples/forms/ts/app/hero-form.component.ts b/public/docs/_examples/forms/ts/app/hero-form.component.ts
index 09bcbeb7b5..54f9c19151 100644
--- a/public/docs/_examples/forms/ts/app/hero-form.component.ts
+++ b/public/docs/_examples/forms/ts/app/hero-form.component.ts
@@ -27,17 +27,37 @@ export class HeroFormComponent {
get diagnostic() { return JSON.stringify(this.model); }
// #enddocregion first
+ // #docregion final
+ // Reset the form with a new hero AND restore 'pristine' class state
+ // by toggling 'active' flag which causes the form
+ // to be removed/re-added in a tick via NgIf
+ // TODO: Workaround until NgForm has a reset method (#6822)
+ // #docregion new-hero
+ active = true;
- //////// DO NOT SHOW IN DOCS ////////
+ // #docregion new-hero-v1
+ newHero() {
+ this.model = new Hero(42, '', '');
+ // #enddocregion new-hero-v1
+ this.active = false;
+ setTimeout(()=> this.active=true, 0);
+ // #docregion new-hero-v1
+ }
+ // #enddocregion new-hero-v1
+ // #enddocregion new-hero
+ // #enddocregion final
+ //////// NOT SHOWN IN DOCS ////////
// Reveal in html:
- // AlterEgo via form.controls = {{showFormControls(hf)}}
+ // Name via form.controls = {{showFormControls(heroForm)}}
showFormControls(form:NgForm){
- return form.controls['alterEgo'] &&
+
+ return form && form.controls['name'] &&
// #docregion form-controls
- form.controls['name'].value; // Dr. IQ
+ form.controls['name'].value; // Dr. IQ
// #enddocregion form-controls
}
+
/////////////////////////////
// #docregion first, final
diff --git a/public/docs/ts/latest/guide/forms.jade b/public/docs/ts/latest/guide/forms.jade
index 7cf3d35098..56baac914e 100644
--- a/public/docs/ts/latest/guide/forms.jade
+++ b/public/docs/ts/latest/guide/forms.jade
@@ -464,11 +464,9 @@ figure.image-display
1. the "*is required*" message in a nearby `
` which we'll display only if the control is invalid.
Here's how we do it for the *name* input box:
--var stylePattern = { otl: /(#name="form")|(.*div.*$)|(Name is required)/gm };
+makeExample('forms/ts/app/hero-form.component.html',
'name-with-error-msg',
- 'app/hero-form.component.html (excerpt)',
- stylePattern)
+ 'app/hero-form.component.html (excerpt)')(format=".")
:marked
When we added the `ngControl` directive, we bound it to the the model's `name` property.
@@ -478,9 +476,22 @@ figure.image-display
In other words, the `name` local template variable becomes a handle on the `ngControl` object
for this input box.
- Now we can control visibility of the "name" error message by binding the message `
` element's `hidden` property
- to the `ngControl` object's `valid` property. The message is hidden while the control is valid;
- the message is revealed when the control becomes invalid.
+ Now we can control visibility of the "name" error message by binding properties of the `name` control to the message `
` element's `hidden` property.
++makeExample('forms/ts/app/hero-form.component.html',
+ 'hidden-error-msg',
+ 'app/hero-form.component.html (excerpt)')
+:marked
+ In this example, we hide the message when the control is valid or pristine;
+ pristine means the user hasn't changed the value since it was displayed in this form.
+
+ This user experience is the developer's choice. Some folks want to see the message at all times.
+ If we ignore the `pristine` state, we would hide the message only when the value is valid.
+ If we arrive in this component with a new (blank) hero or an invalid hero,
+ we'll see the error message immediately, before we've done anything.
+
+ Some folks find that behavior disconcerting. They only want to see the message when the user makes an invalid change.
+ Hiding the message while the control is "pristine" achieves that goal.
+ We'll see the significance of this choice when we [add a new hero](#new-hero) to the form.
.l-sub-section
:marked
@@ -502,7 +513,58 @@ figure.image-display
We can add the same kind of error handling to the `