Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

docs(forms-guide): explain heroForm reference better #3082

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions public/docs/ts/latest/guide/forms.jade
Original file line number Diff line number Diff line change
Expand Up @@ -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
<a id="ngForm"></a>
.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 `<form>` 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)')
Expand All @@ -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.
<a id="ngForm"></a>
.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 `<form>` 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:
Expand Down