Importing the Forms Module

The imports property of the NgModule decorator specifies the dependencies of the application. Adding FormsModule to the list of dependencies enables the form features and makes them available for use throughout the application.

Preparing the Component and Template

Open a new browser window and navigate to http://localhost:4200 to see the table shown in Figure 14-1.

Using Event Data

The previous example used the event binding to connect two pieces of data provided by the component: when the mouseevent is triggered, the binding’s expression sets the selectedProduct property using a data value that was provided to the ngfor directive by the component’s getProducts method.

The event object is assigned to a template variable called $event, and the binding expression in Listing 14-7 uses this variable to access the event object’s target property.

The input event is triggered when the user edits the contents of the input element, so the component’s selectedProduct property is updated with the contents of the input element after each keystroke. As the user types into the input element, the text that has been entered is displayed at the top of the browser window using the string interpolation binding.

The ngClass binding applied to the tr elements sets the background color of the table rows when the selectedProduct property matches the name of the product they represent. And, now that the value of the selectedProduct property is driven by the contents of the input element, typing the name of a product will cause the appropriate row to be highlighted, as shown in Figure 14-5.

Using different bindings to work together is at the heart of effective Angular development and makes it possible to create applications that respond immediately to user interaction and to changes in the data model.

Using Template Reference Variables

The event binding responds to the mouseover event by setting the value property on the HTMLInputElement that has been assigned to the product variable. The result is that moving the mouse over one of the tr elements will update the contents of the input element.

Angular won’t update the data bindings in the template when the user edits the contents of the input element unless there is an event binding on that element. Setting the binding to false gives Angular something to evaluate just so the update process will begin and distribute the current contents of the input element throughout the template. This is a quirk of stretching the role of a template reference variable a little too far and isn’t something you will need to do in most real projects. As you will see in later examples—and later chapters—most data bindings rely on variables defined by the template’s component.

Using the ngModel Directive

Using the ngModel directive requires combining the syntax of the property and event bindings, as illustrated in Figure 14-7.

A combination of square and round brackets is used to denote a two-way data binding, with the round brackets placed inside the square ones: [( and )]. The Angular development team refers to this as the banana-in-a-box binding because that’s what the brackets and parentheses look like when placed like this [()]. Well, sort of.

The target for the binding is the ngModel directive, which is included in Angular to simplify creating two-way data bindings on form elements, such as the input elements used in the example.

The expression for a two-way data binding is the name of a property, which is used to set up the individual bindings behind the scenes. When the contents of the input element change, the new content will be used to update the value of the selectedProduct property. Equally, when the value of the selectedProduct value changes, it will be used to update the contents of the element.

The ngModel directive knows the combination of events and properties that the standard HTML elements define. Behind the scenes, an event binding is applied to the input event, and a property binding is applied to the value property.

Adding a Form to the Example Application

The listing adds a new property called newProduct, which will be used to store the data entered into the form by the user. There is also a jsonProduct property with a getter that returns a JSON representation of the newProduct property and that will be used in the template to show the effect of the two-way bindings. (I can’t create a JSON representation of an object directly in the template because the JSON object is defined in the global namespace, which, as I explained in Chapter 13, cannot be accessed directly from template expressions.)

The final addition is an addProduct method that writes out the value of the jsonProduct method to the console; this will let me demonstrate some basic form-related features before adding support for updating the data model later in the chapter.

Each input element is grouped together with a label and contained in a div element, which is styled using the Bootstrap form-group class. Individual input elements are assigned to the Bootstrap form-control class to manage the layout and style.

The overall result, illustrated in Figure 14-8, is a set of input elements that update the properties of a Product object managed by the component, which are reflected immediately in the JSON data.

Adding Form Data Validation

At the moment, any data can be entered into the input elements in the form. Data validation is essential in web applications because users will enter a surprising range of data values, either in error or because they want to get to the end of the process as quickly as possible and enter garbage values to proceed.

Angular requires elements being validated to define the name attribute, which is used to identify the element in the validation system. Since this input element is being used to capture the value of the Product.name property, the name attribute on the element has been set to name.

This listing adds three of the four validation attributes to the input element. The required attribute specifies that the user must provide a value, the minlength attribute specifies that there should be at least three characters, and the pattern attribute specifies that only alphabetic characters and spaces are allowed.

The validation attributes that Angular uses are the same ones used by the HTML 5 specification, so I have added the novalidate attribute to the form element, which tells the browser not to use its native validation features, which are inconsistently implemented by different browsers and generally get in the way. Since Angular will be providing the validation, the browser’s own implementation of these features is not required.

Finally, notice that a form element has been added to the template. Although you can use input elements independently, the Angular validation features work only when there is a form element present, and Angular will report an error if you add the ngControl directive to an element that is not contained in a form.

The ngSubmit binding handles the form element’s submit event. You can achieve the same effect binding to the click event on individual button elements within the form if you prefer.

Styling Elements Using Validation Classes

Once you have saved the template changes in Listing 14-13 and the browser has reloaded the HTML, right-click the input element in the browser window and select Inspect or Inspect Element from the pop-up window. The browser will display the HTML representation of the element in the Developer Tools window, and you will see that the input element has been added to three classes, like this:

...

<input class="form-control ng-pristine ng-invalid ng-touched" minlength="5"

    name="name" pattern="^[A-Za-z ]+$" required="" ng-reflect-name="name">

...

The classes to which an input element is assigned provide details of its validation state. There are three pairs of validation classes, which are described in Table 14-5. Elements will always be members of one class from each pair, for a total of three classes. The same classes are applied to the form element to show the overall validation status of all the elements it contains. As the status of the input element changes, the ngControl directive switches the classes automatically for both the individual elements and the form element.

Table 14-5.

The Angular Form Validation Classes

Name	Description
ng-untouchedng-touched	An element is assigned to the ng-untouched class if it has not been visited by the user, which is typically done by tabbing through the form fields. Once the user has visited an element, it is added to the ng-touched class.
ng-pristineng-dirty	An element is assigned to the ng-pristine class if its contents have not been changed by the user and to the ng-dirty class otherwise. Once the contents have been edited, an element remains in the ng-dirty class, even if the user then returns to the previous contents.
ng-validng-invalid	An element is assigned to the ng-valid class if its contents meet the criteria defined by the validation rules that have been applied to it and to the ng-invalid class otherwise.

These classes can be used to style form elements to provide the user with validation feedback. Listing 14-14 adds a style element to the template and defines styles that indicate when the user has entered invalid or valid data.

Tip

In real applications, styles should be defined in separate stylesheets and included in the application through the index.html file or using a component’s decorator settings (which I describe in Chapter 17). I have included the styles directly in the template for simplicity, but this makes real applications harder to maintain because it makes it difficult to figure out where styles are coming from when there are multiple templates in use.

<style>

    input.ng-dirty.ng-invalid { border: 2px solid #ff0000 }

    input.ng-dirty.ng-valid { border: 2px solid #6bc502 }

</style>

<div class="m-2">

  <div class="bg-info p-2 mb-2">Model Data: {{jsonProduct}}</div>

  <form novalidate (ngSubmit)="addProduct(newProduct)">

    <div class="form-group">

      <label>Name</label>

      <input class="form-control"

             name="name"

             [(ngModel)]="newProduct.name"

             required

             minlength="5"

             pattern="^[A-Za-z ]+$" />

    </div>

    <button class="btn btn-primary" type="submit">

      Create

    </button>

  </form>

</div>

Listing 14-14.

Providing Validation Feedback in the template.html File in the src/app Folder

These styles set green and red borders for input elements whose content has been edited and is valid (and so belong to both the ng-dirty and ng-valid classes) and whose content is invalid (and so belong to the ng-dirty and ng-invalid classes). Using the ng-dirty class means that the appearance of the elements won’t be changed until after the user has entered some content.

Angular validates the contents and changes the class memberships of the input elements after each keystroke or focus change. The browser detects the changes to the elements and applies the styles dynamically, which provides users with validation feedback as they enter data into the form, as shown in Figure 14-9.

As I start to type, the input element is shown as invalid because there are not enough characters to satisfy the minlength attribute. Once there are five characters, the border is green, indicating that the data is valid. When I type the character 2, the border turns red again because the pattern attribute is set to allow only letters and spaces.

Tip

If you look at the JSON data at the top of the page in Figure 14-9, you will see that the data bindings are still being updated, even when the data values are not valid. Validation runs alongside data bindings, and you should not act on form data without checking that the overall form is valid, as described in the “Validating the Entire Form” section.

Displaying Field-Level Validation Messages

Using colors to provide validation feedback tells the user that something is wrong but doesn’t provide any indication of what the user should do about it. The ngModel directive provides access to the validation status of the elements it is applied to, which can be used to display guidance to the user. Listing 14-15 adds validation messages for each of the attributes applied to the input element using the support provided by the ngModel directive.

<style>

    input.ng-dirty.ng-invalid { border: 2px solid #ff0000 }

    input.ng-dirty.ng-valid { border: 2px solid #6bc502 }

</style>

<div class="m-2">

  <div class="bg-info p-2 mb-2">Model Data: {{jsonProduct}}</div>

  <form novalidate (ngSubmit)="addProduct(newProduct)">

    <div class="form-group">

      <label>Name</label>

      <input class="form-control"

             name="name"

             [(ngModel)]="newProduct.name"

             #name="ngModel"

             required

             minlength="5"

             pattern="^[A-Za-z ]+$" />

      <ul class="text-danger list-unstyled" *ngIf="name.dirty && name.invalid">

        <li *ngIf="name.errors.required">

          You must enter a product name

        </li>

        <li *ngIf="name.errors.pattern">

          Product names can only contain letters and spaces

        </li>

        <li *ngIf="name.errors.minlength">

          Product names must be at least

          {{name.errors.minlength.requiredLength}} characters

        </li>

      </ul>

    </div>

    <button class="btn btn-primary" type="submit">

      Create

    </button>

  </form>

</div>

Listing 14-15.

Adding Validation Messages in the template.html File in the src/app Folder

To get validation working, I have to create a template reference variable to access the validation state in expressions, which I do like this:

...

<input class="form-control" name="name" [(ngModel)]="newProduct.name"

    #name="ngModel" required minlength="5" pattern="^[A-Za-z ]+$"/>

...

I create a template reference variable called name and set its value to ngModel. This use of an ngModel value is a little confusing: it is a feature provided by the ngModel directive to give access to the validation status. This will make more sense once you have read Chapters 15 and 16, in which I explain how to create custom directives and you see how they provide access to their features. For this chapter, it is enough to know that in order to display validation messages, you need to create a template reference variable and assign it ngModel to access the validation data for the input element. The object that is assigned to the template reference variable defines the properties that are described in Table 14-6.

Table 14-6.

The Validation Object Properties

Name	Description
path	This property returns the name of the element.
valid	This property returns true if the element’s contents are valid and false otherwise.
invalid	This property returns true if the element’s contents are invalid and false otherwise.
pristine	This property returns true if the element’s contents have not been changed.
dirty	This property returns true if the element’s contents have been changed.
touched	This property returns true if the user has visited the element.
untouched	This property returns true if the user has not visited the element.
errors	This property returns an object whose properties correspond to each attribute for which there is a validation error.
value	This property returns the value of the element, which is used when defining custom validation rules, as described in the “Creating Custom Form Validators” section.

Listing 14-15 displays the validation messages in a list. The list should be shown only if there is at least one validation error, so I applied the ngIf directive to the ul element, with an expression that uses the dirty and invalid properties, like this:

...

<ul class="text-danger list-unstyled" *ngIf="name.dirty && name.invalid">

...

Within the ul element, there is an li element that corresponds to each validation error that can occur. Each li element has an ngIf directive that uses the errors property described in Table 14-6, like this:

...

<li *ngIf="name.errors.required">You must enter a product name</li>

...

The errors.required property will be defined only if the element’s contents have failed the required validation check, which ties the visibility of the li element to the outcome of that validation check.

Using the Safe Navigation Property With Forms

The errors property is created only when there are validation errors, which is why I check the value of the invalid property in the expression on the ul element. An alternative approach is to use the safe navigation property, which is used in templates to navigate through a series of properties without generating an error if one of them returns null. Here is an alternative approach to defining the template in Listing 14-15 that doesn’t check the valid property and relies on the safe navigation property instead:

...

<ul class="text-danger list-unstyled" *ngIf="name.dirty">

    <li *ngIf="name.errors?.required">

        You must enter a product name

    </li>

    <li *ngIf="name.errors?.pattern">

        Product names can only contain letters and spaces

    </li>

    <li *ngIf="name.errors?.minlength">

        Product names must be at least

        {{name.errors.minlength.requiredLength}} characters

    </li>

</ul>

...

Appending a ? character after a property name tells Angular not to try to access any subsequent properties or methods if the property is null or undefined. In this example, I have applied the ? character after the errors property, which means Angular won’t try to read the required, pattern, or minlength properties if the error property hasn’t been defined.

Each property defined by the errors object returns an object whose properties provide details of why the content has failed the validation check for its attribute, which can be used to make the validation messages more helpful to the user. Table 14-7 describes the error properties provided for each attribute.

Table 14-7.

The Angular Form Validation Error Description Properties

Name	Description
required	This property returns true if the required attribute has been applied to the input element. This is not especially useful because this can be deduced from the fact that the required property exists.
minlength.requiredLength	This property returns the number of characters required to satisfy the minlength attribute.
minlength.actualLength	This property returns the number of characters entered by the user.
pattern.requiredPattern	This property returns the regular expression that has been specified using the pattern attribute.
pattern.actualValue	This property returns the contents of the element.

These properties are not displayed directly to the user, who is unlikely to understand an error message that includes a regular expression, although they can be useful during development to figure out validation problems. The exception is the minlength.requiredLength property, which can be useful for avoiding the duplication of the value assigned to the minlength attribute on the element, like this:

...

<li *ngIf="name.errors.minlength">

  Product names must be at least {{name.errors.minlength.requiredLength}} characters

</li>

...

The overall result is a set of validation messages that are shown as soon as the user starts editing the input element and that change to reflect each new keystroke, as illustrated in Figure 14-10.

Validating the Entire Form

The formSubmitted property will be used to indicate whether the form has been submitted and will be used to prevent validation of the entire form until the user has tried to submit.

The submitForm method will be invoked when the user submits the form and receives an NgForm object as its argument. This object represents the form and defines the set of validation properties; these properties are used to describe the overall validation status of the form so that, for example, the invalid property will be true if there are validation errors on any of the elements contained by the form. In addition to the validation property, NgForm provides the reset method, which resets the validation status of the form and returns it to its original and pristine state.

The form element now defines a reference variable called form, which has been assigned to ngForm. This is how the ngForm directive provides access to its functionality, through a process that I describe in Chapter 15. For now, however, it is important to know that the validation information for the entire form can be accessed through the form reference variable.

It is this object that is received as the argument of the submitForm method and that is used to check the validation status of the form and to reset the form so that it can be used again.

Listing 14-19 also adds a div element that uses the formSubmitted property from the component along with the valid property (provided by the form template variable) to show a warning message when the form contains invalid data, but only after the form has been submitted.

In addition, the ngIf binding has been updated to display the field-level validation messages so that they will be shown when the form has been submitted, even if the element itself hasn’t been edited. The result is a validation summary that is shown only when the user submits the form with invalid data, as illustrated by Figure 14-11.

Displaying Summary Validation Messages

In a complex form, it can be helpful to provide the user with a summary of all the validation errors that have to be resolved. The NgForm object assigned to the form template reference variable provides access to the individual elements through a property named controls. This property returns an object that has properties for each of the individual elements in the form. For example, there is a name property that represents the input element in the example, which is assigned an object that represents that element and defines the same validation properties that are available for individual elements. In Listing 14-20, I have added a method to the component that receives the object assigned to the form element’s template reference variables and uses its controls property to generate a list of error messages for the entire form.

import { ApplicationRef, Component } from "@angular/core";

import { NgForm } from "@angular/forms";

import { Model } from "./repository.model";

import { Product } from "./product.model";

@Component({

    selector: "app",

    templateUrl: "template.html"

})

export class ProductComponent {

    model: Model = new Model();

    // ...other methods omitted for brevity...

    getFormValidationMessages(form: NgForm): string[] {

        let messages: string[] = [];

        Object.keys(form.controls).forEach(k => {

            this.getValidationMessages(form.controls[k], k)

                .forEach(m => messages.push(m));

        });

        return messages;

    }

}

Listing 14-20.

Generating Form-Wide Validation Messages in the component.ts File in the src/app Folder

The getFormValidationMessages method builds its list of messages by calling the getValidationMessages method defined in Listing 14-16 for each control in the form. The Object.keys method creates an array from the properties defined by the object returned by the controls property, which is enumerated using the forEach method.

In Listing 14-21, I have used this method to include the individual messages at the top of the form, which will be visible once the user clicks the Create button.

<style>

    input.ng-dirty.ng-invalid { border: 2px solid #ff0000 }

    input.ng-dirty.ng-valid { border: 2px solid #6bc502 }

</style>

<div class="m-2">

  <form novalidate #form="ngForm" (ngSubmit)="submitForm(form)">

    <div class="bg-danger text-white p-2 mb-2"

         *ngIf="formSubmitted && form.invalid">

      There are problems with the form

      <ul>

        <li *ngFor="let error of getFormValidationMessages(form)">

          {{error}}

        </li>

      </ul>

    </div>

    <div class="form-group">

      <label>Name</label>

      <input class="form-control"

             name="name"

             [(ngModel)]="newProduct.name"

             #name="ngModel"

             required

             minlength="5"

             pattern="^[A-Za-z ]+$" />

      <ul class="text-danger list-unstyled"

          *ngIf="(formSubmitted || name.dirty) && name.invalid">

          <li *ngFor="let error of getValidationMessages(name)">

            {{error}}

          </li>

        </ul>

    </div>

    <button class="btn btn-primary" type="submit">

      Create

    </button>

  </form>

</div>

Listing 14-21.

Displaying Form-Wide Validation Messages in the template.html File in the src/app Folder

The result is that validation messages are displayed alongside the input element and collected at the top of the form once it has been submitted, as shown in Figure 14-12.

Disabling the Submit Button

The final adjustment in this section is to disable the button once the user has submitted the form, preventing the user from clicking it again until all the validation errors have been resolved. This is a commonly used technique even though it has little bearing on the application, which won’t accept the data from the form while it contains invalid values but provides useful reinforcement to the user that they cannot proceed until the validation problems have been resolved.

In Listing 14-22, I have used the property binding on the button element and added an input element for the price property to show how the approach scales up with multiple elements in the form.

<style>

    input.ng-dirty.ng-invalid { border: 2px solid #ff0000 }

    input.ng-dirty.ng-valid { border: 2px solid #6bc502 }

</style>

<div class="m-2">

    <form novalidate #form="ngForm" (ngSubmit)="submitForm(form)">

        <div class="bg-danger text-white p-2 mb-2"

                 *ngIf="formSubmitted && form.invalid">

            There are problems with the form

            <ul>

                <li *ngFor="let error of getFormValidationMessages(form)">

                    {{error}}

                </li>

            </ul>

        </div>

        <div class="form-group">

            <label>Name</label>

            <input class="form-control"

                   name="name"

                   [(ngModel)]="newProduct.name"

                   #name="ngModel"

                   required

                   minlength="5"

                   pattern="^[A-Za-z ]+$" />

            <ul class="text-danger list-unstyled"

                *ngIf="(formSubmitted || name.dirty) && name.invalid">

                <li *ngFor="let error of getValidationMessages(name)">

                    {{error}}

                </li>

            </ul>

        </div>

        <div class="form-group">

            <label>Price</label>

            <input class="form-control" name="price" [(ngModel)]="newProduct.price"

                   #price="ngModel" required pattern="^[0-9.]+$" />

            <ul class="text-danger list-unstyled"

                *ngIf="(formSubmitted || price.dirty) && price.invalid">

                <li *ngFor="let error of getValidationMessages(price)">

                    {{error}}

                </li>

            </ul>

        </div>

        <button class="btn btn-primary" type="submit"

                [disabled]="formSubmitted && form.invalid"

                [class.btn-secondary]="formSubmitted && form.invalid">

            Create

        </button>

    </form>

</div>

Listing 14-22.

Disabling the Button and Adding an Input Element in the template.html File in the src/app Folder

For extra emphasis, I used the class binding to add the button element to the btn-secondary class when the form has been submitted and has invalid data. This class applies a Bootstrap CSS style, as shown in Figure 14-13.

Enabling Model-Based Forms Feature

The model-based forms feature is defined in a module called ReactiveFormsModule, which is defined in the @angular/forms JavaScript module, which was added to the project at the start of the chapter.

Defining the Form Model Classes

The two classes defined in the listing extend the ones that Angular uses to manage forms and their contents behind the scenes. The FormControl class is used to represent a single element in a form, such as input element, and the FormGroup class is used to manage a form element and its contents.

The new subclasses add features that will make it easier to generate the HTML form programmatically. The ProductFormControl class extends the FormControl class with properties that specify the text for the label element associated with an input element and with the name of the Product class property that the input element will represent.

The Validators.compose method accepts an array of validators. The constructor arguments defined by the pattern, minLength, and maxLength validators correspond to the attribute values. The overall effect for this element is that values are required, must contain only alphabet characters and spaces, and must be between three and ten characters.

The validation messages are generated in the same way as they were previously, with minor adjustments to reflect the fact that the code is now part of the form model rather than the component.

Using the Model for Validation

The listing imports the ProductFormGroup class from the form.model module and uses it to define a property called form, which makes the custom form model class available for use in the template.

The value assigned to the formGroup directive is the component’s form property, which returns the ProductFormGroup object, which is the source of validation information about the form.

The FormGroup class provides a controls property that returns a collection of the FormControl objects that it is managing, indexed by name. Individual FormControl objects can be retrieved from the collection and either inspected to get the validation state or used to generate validation messages.

As part of the changed in Listing 14-27, I have added all three input elements required to get the data to create new Product objects, each of which is checked using the validation model, as shown in Figure 14-14.

Generating the Elements from the Model

There is a lot of duplication in Listing 14-27. The validation attributes have been moved into the code, but each input element still requires a supporting framework of content to handle its layout and to display its validation messages to the user.

This listing uses the ngFor directive to create form elements using the description provided by the ProductFormControl and ProductFormGroup model classes. Each element is configured with the same attributes as in Listing 14-27, but their values are taken from the model descriptions, which allows the template to be simplified and rely on the model for both the definition of the form elements and their validation.

Once you have a basic form model in place, you can expand it and extend it to reflect the needs of the application. For example, you can add new elements, extend the FormControl subclass to contain additional information (such as values for the type attribute of the input element), generate select elements for fields, and provide placeholder values to help guide the user.

Applying a Custom Validator

The result is that the value entered into the Price field has a limit of 100, and larger values display the validation error message shown in Figure 14-15.