From e9f02e82ba4a12e1064c43bff01bc21fe2b0fb4b Mon Sep 17 00:00:00 2001 From: Uchendu Nwachuku Date: Sat, 7 Jan 2017 00:50:24 -0500 Subject: [PATCH] docs(forms-guide): explain `heroForm` reference better The current forms guide uses the heroForm variable without creating or explaining it first, which could cause confusion. This change modifies that section to add the explanation before the variable is used, --- public/docs/ts/latest/guide/forms.jade | 47 ++++++++++++++------------ 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/public/docs/ts/latest/guide/forms.jade b/public/docs/ts/latest/guide/forms.jade index be16d9ed6c..8522961e6e 100644 --- a/public/docs/ts/latest/guide/forms.jade +++ b/public/docs/ts/latest/guide/forms.jade @@ -557,8 +557,32 @@ figure.image-display The form remembers that we entered a name before clicking *New Hero*. Replacing the hero object *did not restore the pristine state* of the form controls. - We have to clear all of the flags imperatively which we can do - by calling the form's `reset()` method after calling the `newHero()` method. + We have to tell the form to clear all of its flags. But to do that, we need some sort of reference to it: +code-example(language="html"). + <form #heroForm="ngForm"> + +:marked + This defines a template reference variable, **`#heroForm`**, and initializes it with the + value, "ngForm". The variable `heroForm` will become a reference to the `NgForm` directive + that governs the form as a whole. + +:marked + +.l-sub-section + :marked + ### The _NgForm_ directive + What `NgForm` directive? We didn't add an [NgForm](../api/forms/index/NgForm-directive.html) directive! + + Angular did. Angular creates and attaches an `NgForm` directive to the `
` tag automatically. + + The `NgForm` directive supplements the `form` element with additional features. + It holds the controls we created for the elements with `ngModel` directive and `name` attribute + and monitors their properties including their validity. + It also has its own `valid` property which is true only *if every contained + control* is valid. + +:marked + We can use the `heroForm` reference to make the form pristine again: +makeExample('forms/ts/app/hero-form.component.html', 'new-hero-button-form-reset', 'app/hero-form.component.html (Reset the form)') @@ -579,25 +603,6 @@ figure.image-display to the `HeroFormComponent.submit()` method: +makeExample('forms/ts/app/hero-form.component.html', 'ngSubmit')(format=".") -:marked - We slipped in something extra there at the end! We defined a - template reference variable, **`#heroForm`**, and initialized it with the value, "ngForm". - - The variable `heroForm` is now a reference to the `NgForm` directive that governs the form as a whole. - -.l-sub-section - :marked - ### The _NgForm_ directive - What `NgForm` directive? We didn't add an [NgForm](../api/forms/index/NgForm-directive.html) directive! - - Angular did. Angular creates and attaches an `NgForm` directive to the `` tag automatically. - - The `NgForm` directive supplements the `form` element with additional features. - It holds the controls we created for the elements with `ngModel` directive and `name` attribute - and monitors their properties including their validity. - It also has its own `valid` property which is true only *if every contained - control* is valid. - :marked Later in the template we bind the button's `disabled` property to the form's over-all validity via the `heroForm` variable. Here's that bit of markup: