feat(input): Add custom error state matcher

Author: willshowell

src/demo-app/input/input-demo.html

@@ -94,6 +94,17 @@ <h4>Inside a form</h4>
 
       <button color="primary" md-raised-button>Submit</button>
     </form>
+
+    <h4>With a custom error function</h4>
+    <md-input-container>
+      <input mdInput
+        placeholder="example"
+        [(ngModel)]="errorMessageExample4"
+        [errorStateMatcher]="customErrorStateMatcher"
+        required>
+      <md-error>This field is required</md-error>
+    </md-input-container>
+
   </md-card-content>
 </md-card>
 

src/demo-app/input/input-demo.ts

@@ -1,5 +1,5 @@
 import {Component} from '@angular/core';
-import {FormControl, Validators} from '@angular/forms';
+import {FormControl, Validators, NgControl} from '@angular/forms';
 
 
 let max = 5;
@@ -23,6 +23,7 @@ export class InputDemo {
   errorMessageExample1: string;
   errorMessageExample2: string;
   errorMessageExample3: string;
+  errorMessageExample4: string;
   dividerColorExample1: string;
   dividerColorExample2: string;
   dividerColorExample3: string;
@@ -43,4 +44,11 @@ export class InputDemo {
       this.items.push({ value: ++max });
     }
   }
+
+  customErrorStateMatcher(c: NgControl): boolean {
+    const isDirty = c.dirty;
+    const isInvalid = c.invalid;
+
+    return isDirty && isInvalid;
+  }
 }

src/lib/core/core.ts

@@ -118,6 +118,13 @@ export {
   MD_PLACEHOLDER_GLOBAL_OPTIONS
 } from './placeholder/placeholder-options';
 
+// Error
+export {
+  ErrorStateMatcherType,
+  ErrorOptions,
+  MD_ERROR_GLOBAL_OPTIONS
+} from './error/error-options';
+
 @NgModule({
   imports: [
     MdLineModule,

src/lib/core/error/error-options.ts

@@ -0,0 +1,14 @@
+import {InjectionToken} from '@angular/core';
+import {NgControl, FormGroupDirective, NgForm} from '@angular/forms';
+
+/** Injection token that can be used to specify the global error options. */
+export const MD_ERROR_GLOBAL_OPTIONS =
+  new InjectionToken<() => boolean>('md-error-global-options');
+
+export type ErrorStateMatcherType =
+  (control: NgControl, parentFormGroup: FormGroupDirective, parentForm: NgForm) => boolean;
+
+export interface ErrorOptions {
+  errorStateMatcher?: ErrorStateMatcherType;
+  showOnDirty?: boolean;
+}

src/lib/input/input-container.spec.ts

@@ -6,6 +6,7 @@ import {
   FormGroupDirective,
   FormsModule,
   NgForm,
+  NgControl,
   ReactiveFormsModule,
   Validators
 } from '@angular/forms';
@@ -23,6 +24,7 @@ import {
   getMdInputContainerPlaceholderConflictError
 } from './input-container-errors';
 import {MD_PLACEHOLDER_GLOBAL_OPTIONS} from '../core/placeholder/placeholder-options';
+import {MD_ERROR_GLOBAL_OPTIONS} from '../core/error/error-options';
 
 describe('MdInputContainer', function () {
   beforeEach(async(() => {
@@ -56,6 +58,7 @@ describe('MdInputContainer', function () {
         MdInputContainerWithDynamicPlaceholder,
         MdInputContainerWithFormControl,
         MdInputContainerWithFormErrorMessages,
+        MdInputContainerWithCustomErrorStateMatcher,
         MdInputContainerWithFormGroupErrorMessages,
         MdInputContainerWithId,
         MdInputContainerWithPrefixAndSuffix,
@@ -705,6 +708,116 @@ describe('MdInputContainer', function () {
       });
     }));
 
+    it('should display an error message when a custom error matcher returns true', async(() => {
+      fixture.destroy();
+
+      let customFixture = TestBed.createComponent(MdInputContainerWithCustomErrorStateMatcher);
+      let component: MdInputContainerWithCustomErrorStateMatcher;
+
+      customFixture.detectChanges();
+      component = customFixture.componentInstance;
+      containerEl = customFixture.debugElement.query(By.css('md-input-container')).nativeElement;
+
+      expect(component.formControl.invalid).toBe(true, 'Expected form control to be invalid');
+      expect(containerEl.querySelectorAll('md-error').length).toBe(0, 'Expected no error messages');
+
+      component.formControl.markAsTouched();
+      customFixture.detectChanges();
+
+      customFixture.whenStable().then(() => {
+        expect(containerEl.querySelectorAll('md-error').length)
+          .toBe(0, 'Expected no error messages after being touched.');
+
+        component.errorState = true;
+        customFixture.detectChanges();
+
+        customFixture.whenStable().then(() => {
+          expect(containerEl.querySelectorAll('md-error').length)
+            .toBe(1, 'Expected one error messages to have been rendered.');
+        });
+      });
+    }));
+
+    it('should display an error message when global error matcher returns true', () => {
+
+      // Global error state matcher that will always cause errors to show
+      function globalErrorStateMatcher() {
+        return true;
+      }
+
+      TestBed.resetTestingModule();
+      TestBed.configureTestingModule({
+        imports: [
+          FormsModule,
+          MdInputModule,
+          NoopAnimationsModule,
+          ReactiveFormsModule,
+        ],
+        declarations: [
+          MdInputContainerWithFormErrorMessages
+        ],
+        providers: [
+          {
+            provide: MD_ERROR_GLOBAL_OPTIONS,
+            useValue: { errorStateMatcher: globalErrorStateMatcher } }
+        ]
+      });
+
+      let customFixture = TestBed.createComponent(MdInputContainerWithFormErrorMessages);
+      customFixture.detectChanges();
+
+      containerEl = customFixture.debugElement.query(By.css('md-input-container')).nativeElement;
+      testComponent = customFixture.componentInstance;
+
+      // Expect the control to still be untouched but the error to show due to the global setting
+      expect(testComponent.formControl.untouched).toBe(true, 'Expected untouched form control');
+      expect(containerEl.querySelectorAll('md-error').length).toBe(1, 'Expected an error message');
+    });
+
+    it('should display an error message when global setting shows errors on dirty', async() => {
+      TestBed.resetTestingModule();
+      TestBed.configureTestingModule({
+        imports: [
+          FormsModule,
+          MdInputModule,
+          NoopAnimationsModule,
+          ReactiveFormsModule,
+        ],
+        declarations: [
+          MdInputContainerWithFormErrorMessages
+        ],
+        providers: [
+          { provide: MD_ERROR_GLOBAL_OPTIONS, useValue: { showOnDirty: true } }
+        ]
+      });
+
+      let customFixture = TestBed.createComponent(MdInputContainerWithFormErrorMessages);
+      customFixture.detectChanges();
+
+      containerEl = customFixture.debugElement.query(By.css('md-input-container')).nativeElement;
+      testComponent = customFixture.componentInstance;
+
+      expect(testComponent.formControl.invalid).toBe(true, 'Expected form control to be invalid');
+      expect(containerEl.querySelectorAll('md-error').length).toBe(0, 'Expected no error messages');
+
+      testComponent.formControl.markAsTouched();
+      customFixture.detectChanges();
+
+      customFixture.whenStable().then(() => {
+        expect(containerEl.querySelectorAll('md-error').length)
+          .toBe(0, 'Expected no error messages when touched');
+
+        testComponent.formControl.markAsDirty();
+        customFixture.detectChanges();
+
+        customFixture.whenStable().then(() => {
+          expect(containerEl.querySelectorAll('md-error').length)
+            .toBe(1, 'Expected one error message when dirty');
+        });
+      });
+
+    });
+
     it('should hide the errors and show the hints once the input becomes valid', async(() => {
       testComponent.formControl.markAsTouched();
       fixture.detectChanges();
@@ -1018,6 +1131,29 @@ class MdInputContainerWithFormErrorMessages {
   renderError = true;
 }
 
+@Component({
+  template: `
+    <form #form="ngForm" novalidate>
+      <md-input-container>
+        <input mdInput
+          [formControl]="formControl"
+          [errorStateMatcher]="customErrorStateMatcher.bind(this)">
+        <md-hint>Please type something</md-hint>
+        <md-error>This field is required</md-error>
+      </md-input-container>
+    </form>
+  `
+})
+class MdInputContainerWithCustomErrorStateMatcher {
+  @ViewChild('form') form: NgForm;
+  formControl = new FormControl('', Validators.required);
+  errorState = false;
+
+  customErrorStateMatcher(): boolean {
+    return this.errorState;
+  }
+}
+
 @Component({
   template: `
     <form [formGroup]="formGroup" novalidate>

src/lib/input/input-container.ts

@@ -42,6 +42,11 @@ import {
   PlaceholderOptions,
   MD_PLACEHOLDER_GLOBAL_OPTIONS
 } from '../core/placeholder/placeholder-options';
+import {
+  ErrorStateMatcherType,
+  ErrorOptions,
+  MD_ERROR_GLOBAL_OPTIONS
+} from '../core/error/error-options';
 
 // Invalid input type. Using one of these will throw an MdInputContainerUnsupportedTypeError.
 const MD_INPUT_INVALID_TYPES = [
@@ -137,6 +142,7 @@ export class MdInputDirective {
   private _required = false;
   private _id: string;
   private _cachedUid: string;
+  private _errorOptions: ErrorOptions;
 
   /** Whether the element is focused or not. */
   focused = false;
@@ -189,6 +195,9 @@ export class MdInputDirective {
     }
   }
 
+  /** A function used to control when error messages are shown. */
+  @Input() errorStateMatcher: ErrorStateMatcherType;
+
   /** The input element's value. */
   get value() { return this._elementRef.nativeElement.value; }
   set value(value: string) { this._elementRef.nativeElement.value = value; }
@@ -224,10 +233,14 @@ export class MdInputDirective {
               private _platform: Platform,
               @Optional() @Self() public _ngControl: NgControl,
               @Optional() private _parentForm: NgForm,
-              @Optional() private _parentFormGroup: FormGroupDirective) {
+              @Optional() private _parentFormGroup: FormGroupDirective,
+              @Optional() @Inject(MD_ERROR_GLOBAL_OPTIONS) errorOptions: ErrorOptions) {
 
     // Force setter to be called in case id was not specified.
     this.id = this.id;
+
+    this._errorOptions = errorOptions ? errorOptions : {};
+    this.errorStateMatcher = this._errorOptions.errorStateMatcher || undefined;
   }
 
   /** Focuses the input element. */
@@ -250,11 +263,23 @@ export class MdInputDirective {
   /** Whether the input is in an error state. */
   _isErrorState(): boolean {
     const control = this._ngControl;
+    return this.errorStateMatcher
+      ? this.errorStateMatcher(control, this._parentFormGroup, this._parentForm)
+      : this._defaultErrorStateMatcher(control);
+  }
+
+  /** Default error state calculation */
+  private _defaultErrorStateMatcher(control: NgControl): boolean {
     const isInvalid = control && control.invalid;
     const isTouched = control && control.touched;
+    const isDirty = control && control.dirty;
     const isSubmitted = (this._parentFormGroup && this._parentFormGroup.submitted) ||
         (this._parentForm && this._parentForm.submitted);
 
+    if (this._errorOptions.showOnDirty) {
+      return !!(isInvalid && (isDirty || isSubmitted));
+    }
+
     return !!(isInvalid && (isTouched || isSubmitted));
   }
 

src/lib/input/input.md

@@ -107,3 +107,43 @@ The underline (line under the `input` content) color can be changed by using the
 attribute of `md-input-container`. A value of `primary` is the default and will correspond to the
 theme primary color. Alternatively, `accent` or `warn` can be specified to use the theme's accent or
 warn color.
+
+### Custom Error Matcher
+
+By default, error messages are shown when the control is invalid and the user has interacted with
+(touched) the element or the parent form has been submitted. If you wish to customize this
+behavior (e.g. to show the error as soon as the invalid control is dirty), you can use the
+`errorStateMatcher` property of the `mdInput`. To use this property, create a function in
+your component class that returns a boolean. A result of `true` will display the error messages.
+
+```html
+<md-input-container>
+  <input mdInput [(ngModel)]="myInput" required [errorStateMatcher]="myErrorStateMatcher">
+  <md-error>This field is required</md-error>
+</md-input-container>
+```
+
+```ts
+function myErrorStateMatcher(control: NgControl, parentFg: FormGroupDirective, parentForm: NgForm): boolean {
+  return control.invalid && control.dirty;
+}
+```
+
+A global error state matcher can be specified by setting the `MD_ERROR_GLOBAL_OPTIONS` provider. This applies
+to all inputs.
+
+```ts
+@NgModule({
+  providers: [
+    {provide: MD_ERROR_GLOBAL_OPTIONS, useValue: { errorStateMatcher: myErrorStateMatcher }}
+  ]
+})
+```
+
+Here are the available global options:
+
+
+| Name              | Type     | Description |
+| ----------------- | -------- | ----------- |
+| errorStateMatcher | Function | Returns a boolean specifying if the error should be shown |
+| showOnDirty       | boolean  | If true, the error will show when the control is dirty, not touched. |P