Angular 2 gets a brand new Forms API. It's fresh out of the compiler and since there's not much documentation around yet, @angular_zone powered by Gerard Sans and Wassim Chegham organized a Google Hangout with Kara Erickson, core contributor to the Forms Api. Here I'm basically summarizing the main points and created a runnable Plunker for you to play with.
Two different approaches to Forms
There are basically two different approaches to Angular 2 forms:
- Template driven, Angular 1 style forms
- Reactive, or model-driven forms
Both of them are feature equivalent, so you're fine to go either way. It's however not suggested to mix them. Also, both share the same underlying concepts:
Model, which has properties for validation like
It's important to note that this is not the domain model you bind through
ngModel or similar. It's a dedicated form model holding the validation and form control state properties.
So, the view part is what is called value accessor because we may have different kind of views with different ways of getting hold of their respective value:
The value accessor knows how to interact with the underlying DOM element to get and set the according value. All of them implement the
The model part is an instance of
Every form control has one view (
ControlValueAccessor) and a model instance (
So to summarize:
- Template driven
- Elements like
- implicitly created
- asynchronous, lots of stuff going on behind the scenes for wiring up the
- Elements like
- Reactive (model-driven)
- Elements like
- explicitly/programmatically created
- synchronous and more predictive as they're created programmatically and there's not template rendering in the middle
- Elements like
Let's take a look.
Enabling the Form Api
Before starting straight into form coding, we need to disable the deprecated form support (
disableDeprecatedForms()) and enable the brand new Forms API (
provideForms()) on our Angular 2 app. Open your main file where you bootstrap the app.
Now we should be good to go. Here's a runnable Plunker which you can use to test out the various concepts as we quickly go over them.
Template driven approach
So assume we're having this plain simple HTML form:
To hook it to Angular 2's Forms API, you first need to declare a
As a next step we need to add the
ngModel attribute to our form controls:
This way we use the template driven approach, meaning by adding the
ngModel attribute, behind the scenes the
FormControl instance is created for use which we need for getting access to the underlying DOM element value. To see this two-way binding works, let's print out the state of our form value:
By typing into the text fields you can now see how we established a proper binding. Check it out yourself in the linked Plunker.
Grouping form controls
Often it is necessary to group a number of form controls together, like the concept of an address, having properties such as street, city, state and zipcode. All of these are represented as separate form controls, but can be bound together as a form group.
So what's the effect of that? Well, these form groups get all of the same properties as the individual form controls have (like value, validity, touched/untouched etc), but they are derived by the value of their children. Like if one child is invalid, the whole group gets invalid.
Moreover, the fields of a
FormGroup get serialized into a dedicated object (we'll explore soon how that looks like). A variant of that is the
FormArray. The key difference is that its data gets serialized as an array. This might be especially useful when you don't know how many controls will be present within the group, like dynamic forms.
Ok so far? Good, consider the concept of an address. We can simply add more fields to our form as follows:
This would get serialized like
But given that the address is already logically grouped on our UI, we want it to be serialized into a separate object
address. As we just learned, this is as simple as adding a
The resulting serialized object in turn now looks like this:
We've seen the template-based approach. Let's take a look at the reactive or model-based way of writing Forms. Again, here's a Plunker to play with:
Note how we construct our controls and groups programmatically using the
FormGroup classes. Next we need to hook this
form to our template:
We do this by using the
[formGroup] binding. Also note, that for doing so we need to add the
REACTIVE_FORM_DIRECTIVES to the
directives array of our component.
And finally, we need to map the group and form controls using
Great, so I hope I was able to give you a first overview of what the Forms API looks like in Angular 2. Obviously there's much more to explore!