Getting Started with Template-Driven Forms

In the Superhero application, SuperheroesMaterialDesignModule’s components have Angular Material dependencies. To implement template-driven forms, we use directives and providers that are defined in an Angular module called FormsModule.

Approach to Building Forms

In the sample application, we built a component (named app-create-superhero) to create a superhero. Consider creating a model object that represents the create superhero form. This is a TypeScript object representing a superhero form. We use two-way data binding and the ngModel directive to bind each control in the template file with the TypeScript model object. Figure 9-1 visualizes the model object representing the form.

In the superhero class, add fields that represent controls on the form (see Figure 9-1). The multiselect controls drop-down (for special powers) and chips (for favorite food) use an array in the model. In this form, the remaining fields are strings.

Next, enhance the template. Wrap the text fields and drop-downs in the superhero form with a form element. Angular automatically adds the ngForm directive to every form element. The directive is part of FormsModule, which we imported earlier.

Next, use two-way data binding with model object to the text fields and drop-downs in the template.

The ngModel is a directive available in FormsModule (see Listing 9-4). The module has already been imported. It is ready to use in SuperheroesMaterialDesignModule. Remember, the app-create-superhero component is part of the same module.

To demonstrate two-way data binding, let’s print the model object in the template. For debugging purposes, it is temporary; we will delete it eventually.

Figure 9-2 shows a user entering values into the form fields.

Note the stringified model object at the bottom of the screen. The text is updated as the user enters data in real time. Let’s say that we reset the model object when the cancel button is clicked, and all the text fields are cleared. No additional action needs to be performed on the DOM.

Form Validation and Errors

Consider the following validators in template-driven forms. They are available out of the box to use along with form fields. They ensure the validity and correctness of the form and the data keyed in by the user.

Using the State Field in Form Controls

Angular Material’s mat-form-field component adds behavior when working with forms. It adds a highlighted color border to an invalid form field, which indicates that something is wrong with the field. Figure 9-3 is an email field with an invalid email value.

In the default theme, floating labels, the cursor, and the border are marked red.

The result is shown in Figure 9-4.

State of the Form

Note the first line in Listing 9-11. We created a template reference variable for the entire form element. All the state flags described in the previous section are also available in the form reference. The previous section described state fields in form fields, not the form itself. Listing 9-12 prints a form’s state fields.

<form #superheroForm="ngForm">

 <strong>

   Form Status, Valid- {{superheroForm.valid}}. Pristine- {{superheroForm.pristine}}. Touched- {{superheroForm.touched}}

 </strong>

<!-- removed code for brevity -->

Listing 9-12

Print Form Status

The result is shown in Figure 9-5. The form loads with an invalid status because most form fields do not have data. It is pristine because no form field is edited. The touched status is false because the keyboard focus was not brought onto any form field.

In Figure 9-5 and Listing 9-12, we print the state for demonstration purposes. How do we use these fields in a real-world scenario? In Listing 9-13, we enable the form’s submit buttons if the form is valid (notice the negation). This is part of the validation to ensure that good data makes it into the database from the form.

     <div>

       <button mat-stroked-button> Cancel </button>

       <button mat-stroked-button [disabled]="!superheroForm.valid"> Save </button>

     </div>

Listing 9-13

Submit Disabled Unless the Form Is Valid

Figure 9-6 shows the result.

Note

Listing 9-12 and Listing 9-13 used various Angular Material components and directives, mat-select, mat-button/mat-stroked-button, MatInput, and so forth. So far, we have imported Angular modules, such as MatSelectModule, MatButtonModule, MatInputModule, and so forth. Import respective modules to SuperheroesMaterialDesignModule, if you have not done so already.

Getting Started with Reactive Forms

In the Superhero application, SuperheroesMaterialDesignModule’s components have Angular Material dependencies.

Reactive forms are model driven, which is part of the component class. It is bound to the component template.

Create a Form Control with Form Builder

A form control represents a form field. An instance of a form control is created in the Angular component’s TypeScript file. It could represent a form field like a text field, a drop-down, or a radio button.

FormBuilder is an Angular service in the @angular/forms Angular monorepo. It simplifies creating form controls in Angular’s reactive forms.

Reactive forms are model driven. We will create a model in the TypeScript class. Let’s create it by adding the name field (Superhero name). The name field is a text field in the HTML template. It is an instance of the FormControl class in the model.

The constructor for FormControl is initialized with a default value, “Chhotta Bheem by default”. The result is shown in Figure 9-7. The form shows the default value.

Capture Changes to the Form Control

Forms are built for users to enter data or select values. Users are expected to make a series of changes in the form controls. When users input data, it is never a one-time activity. User interactions are a stream and a series of changes.

Listing 9-19 subscribes to the observable and prints the result values to the console (see Figure 9-8). It is just a sample to demonstrate the observable. A real-world example might transform the data and send it to a remote service on a server.

Access a Snapshot

The preceding sample accesses an observable; however, it is possible to access a single value. Use the change handler in the text field. The form control provides a snapshot of the value at that point in time. It is different from a stream, as you saw in the previous sample (see line 5 in Listing 9-20).

1.   <mat-form-field appearance="outline">

2.     <mat-label>Superhero Name</mat-label>

3.     <!-- Change handler on the input field below -->

4.     <input type="text" name="name" [formControl]="name" matInput

5.       (change)="changeHandler()"

6.       placeholder="A name to be remembered" />

7.     <mat-hint>Enter name</mat-hint>

8.   </mat-form-field>

Listing 9-20

Template with Change Handler Attached to the Form Field

The changeHandler function is invoked on a change to the text field. The snapshot of the FormControl field is available in the value field. The code sample logs the snapshot to the console.

changeHandler(){

   console.log("Log the snapshot at a point in time, ", this.name.value);

 }

Listing 9-21

Change Handler Function Invoked on Change

Figure 9-9 shows the result.

Set a Value on FormControl

In the prior example, a value set by the user in a form control is read by the Angular TypeScript code component. We initialized the form control with a default value; however, we did not set a value.

Imagine that a value needs to be set on the form control when a server-side API returns a value. To mimic the scenario, and without complicating the sample with a server-side API call, we use setTimeout. This is just for the sample. We set a value on the form control after a stipulated number of milliseconds.

The sample times out after a second (1000 milliseconds). this.name is an instance of FormControl. It sets a sample string, “Value set on timeout”, which is set on the text field in the form.

Create a Form Group with Form Builder

In the prior example, a single FormControl instance was created (superhero name). This approach works well for a small number of form controls. As the form grows larger, to represents a group of controls use Form Group. When using a form group, actions like reset can be performed at the form level. Instead of reading the values on the form from separate variables, they can be read on a form-level object.

Each field name—email, details, and so forth—is initialized with empty an string. We can specify default values to initialize.

Read Form Group Values as a Stream

Before we read the values in the form group, let’s create a model object representing the form. Listing 9-26 is a Superhero form. The model class refers to each control in the form group.

export class Superhero {

   name: string;

   email: string;

   details: string;

   country: string;

   specialPowers: Array<string> = [];

}

Listing 9-26

Model Object Referring to the Form Group

Similar to the form control, we can subscribe to changes to the form group. Angular applications use an observable to stream changes. This observable streams changes made by the user. In the form group, you can access the observable with valueChanges. In Listing 9-27, see lines 11 to 16.

1. ngOnInit() {

2.  // Create FormGroup object

3.   this.superheroFormGroup = this.fb.group({

4.     name:”,

5.     email:”,

6.     details: “,

7.     powers: “,

8.     country: “,

9.     favFood: “

10.   });

11.   // Subscribe to the changes to form group

12.   this.superheroFormGroup

13.   .valueChanges

14.   .subscribe(item =>

15.    console.log("Stream as form changes, ", item as Superhero));

16. }

Listing 9-27

Observable for Changes Made to the Form Group

Listing 9-27 subscribes to the observable and prints the result values to the console (see the result in Figure 9-10). Considering it is a stream, a series of values are printed on the console for each change. It is just a sample to demonstrate the observable. A real-world example might transform the data and send it to a remote service on a server.

Also notice that the subscribe success function handler receives each change. The data is available on a variable named item. The received form group value instance is type cast to the Superhero class (see line 15 in Listing 9-27).

Read Form Group Values as a Snapshot

Similar to form control, form group values can also be read as a snapshot. You can use the submit event on the form. It provides a snapshot of the form and all of the controls’ values when the user clicks submit.

See the changes to the template file to add a handler in the form submit (see Listing 9-28 and Listing 9-29).

<form #superheroForm="ngForm" [formGroup]="superheroFormGroup" (submit)="submitHandler()">

</form>

Listing 9-28

Form Submit Handler Added

Refer to the contents of the handler function. It prints a snapshot of the form group. The snapshot is available on value variable. As in the previous section, we type cast snapshot to the Superhero model object.

 submitHandler(){

   let superhero = this.superheroFormGroup.value as Superhero;

   console.log("Superhero model object ", superhero);

 }

Listing 9-29

Print Snapshot of the Form Group to the Console

The result is shown in Figure 9-11. It prints a snapshot of the form group to the browser console.

Form Validation

Consider the validators in reactive forms (see Listing 9-30). They are available out of the box to use along with form fields. They ensure the validity and correctness of the form and the data entered by the user.

Show Form Status and Errors

Angular Material components indicate an error when the validation fails. The components use validators to show the error status. Consider the form in Figure 9-12. The name, email, and details fields show an error because their respective validators—required field validation, email format validation, and minimum character length validation—failed. The error is indicated by a red border around the form field.

As you have seen with template-driven forms, a field can be in one of the following states.

Valid/Invalid

If a form field validator condition is met, it is valid. Consider an example with an email validator. If the user provided a valid email in the [email protected] format, it is valid; otherwise, it is invalid.

Remember, email is part of a form group. Access the form field using the get function in the form group. Writing a getter function at the component level makes the code clean and easier to access the form field.

The template checks if the form field is invalid before showing the error message. Note that this code shows the error message the moment the form loads, which is not ideal. We will fix this in the next section.

Figure 9-13 shows the result.

touched/untouched

If the user brought keyboard focus onto the form field, it is touched; otherwise, it is untouched. Use the touched and untouched fields in the form field.

Typically, when showing form validation status messages, just checking the valid/invalid status in a form field is not effective. After the user attempts to enter a value, it is logical to show or hide an error message. When the form loads, most fields are blank or preloaded with the current data. The form code and the user do not yet have control.

pristine/dirty

If the user attempted to edit a field, it is marked as dirty; otherwise, it is pristine (either blank or with the default data). A common use case for these flags is to enforce users to save the form data if any field is dirty. You may show an alert that indicates the data might be lost if the user navigates away without saving. When all fields are pristine, such an error does not need to be shown in listing 9-39 and Figure 9-14.

     <strong>

       Pristine: {{ email.pristine }}. Dirty: {{ email.dirty }}

     </strong>

Listing 9-39

Print Pristine or Dirty Status

Validator Error Flags

We have used valid/invalid, touched/untouched, pristine/dirty flags to get a form field status at a point in time. For each validator, Angular adds error flags as well.

Remember the email flag in Listing 9-39. The form control was created with two validators: required and email.

     email:[", Validators.required, Validators.email],

If either of these validators return false, an error flag is added. It is added to the errors object in the form control.

In Listing 9-40, separate error flags provide the ability to show specific error messages. If the required field is empty, specify that it is a required field. If the email format failure occurs, show that the email needs to follow the provided format. See Figure 9-15.

   <div *ngIf="email.errors.required" >

     *Email is a required field

   </div>

   <div *ngIf="email.errors.email" >

     *Invalid email. Use [email protected]

   </div>

Listing 9-40

Show Error Message Based on the Error Flag