feat(forms): updateValue() for form groups and form arrays (#9901)

Closes #9553

modules/@angular/forms/src/directives/ng_form.ts

@@ -164,6 +164,8 @@ export class NgForm extends ControlContainer implements Form {
     });
   }
 
+  updateValue(value: {[key: string]: any}): void { this.control.updateValue(value); }
+
   onSubmit(): boolean {
     this._submitted = true;
     ObservableWrapper.callEmit(this.ngSubmit, null);

modules/@angular/forms/src/model.ts

@@ -10,8 +10,10 @@ import {composeAsyncValidators, composeValidators} from './directives/shared';
 import {AsyncValidatorFn, ValidatorFn} from './directives/validators';
 import {EventEmitter, Observable, ObservableWrapper} from './facade/async';
 import {ListWrapper, StringMapWrapper} from './facade/collection';
+import {BaseException} from './facade/exceptions';
 import {isBlank, isPresent, isPromise, normalizeBool} from './facade/lang';
 
+
 /**
  * Indicates that a FormControl is valid, i.e. that no errors exist in the input value.
  */
@@ -149,6 +151,8 @@ export abstract class AbstractControl {
 
   setParent(parent: FormGroup|FormArray): void { this._parent = parent; }
 
+  abstract updateValue(value: any, options?: Object): void;
+
   updateValueAndValidity({onlySelf, emitEvent}: {onlySelf?: boolean, emitEvent?: boolean} = {}):
       void {
     onlySelf = normalizeBool(onlySelf);
@@ -433,6 +437,21 @@ export class FormGroup extends AbstractControl {
     return c && this._included(controlName);
   }
 
+  updateValue(value: {[key: string]: any}, {onlySelf}: {onlySelf?: boolean} = {}): void {
+    StringMapWrapper.forEach(value, (newValue: any, name: string) => {
+      this._throwIfControlMissing(name);
+      this.controls[name].updateValue(newValue, {onlySelf: true});
+    });
+    this.updateValueAndValidity({onlySelf: onlySelf});
+  }
+
+  /** @internal */
+  _throwIfControlMissing(name: string): void {
+    if (!this.controls[name]) {
+      throw new BaseException(`Cannot find form control with name: ${name}.`);
+    }
+  }
+
   /** @internal */
   _setParentForControls() {
     StringMapWrapper.forEach(
@@ -548,6 +567,21 @@ export class FormArray extends AbstractControl {
    */
   get length(): number { return this.controls.length; }
 
+  updateValue(value: any[], {onlySelf}: {onlySelf?: boolean} = {}): void {
+    value.forEach((newValue: any, index: number) => {
+      this._throwIfControlMissing(index);
+      this.at(index).updateValue(newValue, {onlySelf: true});
+    });
+    this.updateValueAndValidity({onlySelf: onlySelf});
+  }
+
+  /** @internal */
+  _throwIfControlMissing(index: number): void {
+    if (!this.at(index)) {
+      throw new BaseException(`Cannot find form control at index ${index}`);
+    }
+  }
+
   /** @internal */
   _updateValue(): void { this._value = this.controls.map((control) => control.value); }
 

modules/@angular/forms/test/model_spec.ts

@@ -551,6 +551,89 @@ export function main() {
         });
       });
 
+      describe('updateValue', () => {
+        let c: FormControl, c2: FormControl, g: FormGroup;
+
+        beforeEach(() => {
+          c = new FormControl('');
+          c2 = new FormControl('');
+          g = new FormGroup({'one': c, 'two': c2});
+        });
+
+        it('should update its own value', () => {
+          g.updateValue({'one': 'one', 'two': 'two'});
+          expect(g.value).toEqual({'one': 'one', 'two': 'two'});
+        });
+
+        it('should update child values', () => {
+          g.updateValue({'one': 'one', 'two': 'two'});
+          expect(c.value).toEqual('one');
+          expect(c2.value).toEqual('two');
+        });
+
+        it('should update parent values', () => {
+          const form = new FormGroup({'parent': g});
+          g.updateValue({'one': 'one', 'two': 'two'});
+          expect(form.value).toEqual({'parent': {'one': 'one', 'two': 'two'}});
+        });
+
+        it('should ignore fields that are missing from supplied value', () => {
+          g.updateValue({'one': 'one'});
+          expect(g.value).toEqual({'one': 'one', 'two': ''});
+        });
+
+        it('should not ignore fields that are null', () => {
+          g.updateValue({'one': null});
+          expect(g.value).toEqual({'one': null, 'two': ''});
+        });
+
+        it('should throw if a value is provided for a missing control', () => {
+          expect(() => g.updateValue({
+            'three': 'three'
+          })).toThrowError(new RegExp(`Cannot find form control with name: three`));
+        });
+
+        describe('updateValue() events', () => {
+          let form: FormGroup;
+          let logger: any[];
+
+          beforeEach(() => {
+            form = new FormGroup({'parent': g});
+            logger = [];
+          });
+
+          it('should emit one valueChange event per control', () => {
+            form.valueChanges.subscribe(() => logger.push('form'));
+            g.valueChanges.subscribe(() => logger.push('group'));
+            c.valueChanges.subscribe(() => logger.push('control1'));
+            c2.valueChanges.subscribe(() => logger.push('control2'));
+
+            g.updateValue({'one': 'one', 'two': 'two'});
+            expect(logger).toEqual(['control1', 'control2', 'group', 'form']);
+          });
+
+          it('should not emit valueChange events for skipped controls', () => {
+            form.valueChanges.subscribe(() => logger.push('form'));
+            g.valueChanges.subscribe(() => logger.push('group'));
+            c.valueChanges.subscribe(() => logger.push('control1'));
+            c2.valueChanges.subscribe(() => logger.push('control2'));
+
+            g.updateValue({'one': 'one'});
+            expect(logger).toEqual(['control1', 'group', 'form']);
+          });
+
+          it('should emit one statusChange event per control', () => {
+            form.statusChanges.subscribe(() => logger.push('form'));
+            g.statusChanges.subscribe(() => logger.push('group'));
+            c.statusChanges.subscribe(() => logger.push('control1'));
+            c2.statusChanges.subscribe(() => logger.push('control2'));
+
+            g.updateValue({'one': 'one', 'two': 'two'});
+            expect(logger).toEqual(['control1', 'control2', 'group', 'form']);
+          });
+        });
+      });
+
       describe('optional components', () => {
         describe('contains', () => {
           var group: any /** TODO #9100 */;
@@ -816,6 +899,89 @@ export function main() {
         });
       });
 
+      describe('updateValue', () => {
+        let c: FormControl, c2: FormControl, a: FormArray;
+
+        beforeEach(() => {
+          c = new FormControl('');
+          c2 = new FormControl('');
+          a = new FormArray([c, c2]);
+        });
+
+        it('should update its own value', () => {
+          a.updateValue(['one', 'two']);
+          expect(a.value).toEqual(['one', 'two']);
+        });
+
+        it('should update child values', () => {
+          a.updateValue(['one', 'two']);
+          expect(c.value).toEqual('one');
+          expect(c2.value).toEqual('two');
+        });
+
+        it('should update parent values', () => {
+          const form = new FormGroup({'parent': a});
+          a.updateValue(['one', 'two']);
+          expect(form.value).toEqual({'parent': ['one', 'two']});
+        });
+
+        it('should ignore fields that are missing from supplied value', () => {
+          a.updateValue([, 'two']);
+          expect(a.value).toEqual(['', 'two']);
+        });
+
+        it('should not ignore fields that are null', () => {
+          a.updateValue([null]);
+          expect(a.value).toEqual([null, '']);
+        });
+
+        it('should throw if a value is provided for a missing control', () => {
+          expect(() => a.updateValue([
+            , , 'three'
+          ])).toThrowError(new RegExp(`Cannot find form control at index 2`));
+        });
+
+        describe('updateValue() events', () => {
+          let form: FormGroup;
+          let logger: any[];
+
+          beforeEach(() => {
+            form = new FormGroup({'parent': a});
+            logger = [];
+          });
+
+          it('should emit one valueChange event per control', () => {
+            form.valueChanges.subscribe(() => logger.push('form'));
+            a.valueChanges.subscribe(() => logger.push('array'));
+            c.valueChanges.subscribe(() => logger.push('control1'));
+            c2.valueChanges.subscribe(() => logger.push('control2'));
+
+            a.updateValue(['one', 'two']);
+            expect(logger).toEqual(['control1', 'control2', 'array', 'form']);
+          });
+
+          it('should not emit valueChange events for skipped controls', () => {
+            form.valueChanges.subscribe(() => logger.push('form'));
+            a.valueChanges.subscribe(() => logger.push('array'));
+            c.valueChanges.subscribe(() => logger.push('control1'));
+            c2.valueChanges.subscribe(() => logger.push('control2'));
+
+            a.updateValue(['one']);
+            expect(logger).toEqual(['control1', 'array', 'form']);
+          });
+
+          it('should emit one statusChange event per control', () => {
+            form.statusChanges.subscribe(() => logger.push('form'));
+            a.statusChanges.subscribe(() => logger.push('array'));
+            c.statusChanges.subscribe(() => logger.push('control1'));
+            c2.statusChanges.subscribe(() => logger.push('control2'));
+
+            a.updateValue(['one', 'two']);
+            expect(logger).toEqual(['control1', 'control2', 'array', 'form']);
+          });
+        });
+      });
+
       describe('errors', () => {
         it('should run the validator when the value changes', () => {
           var simpleValidator = (c: any /** TODO #9100 */) =>

tools/public_api_guard/forms/index.d.ts

@@ -39,6 +39,7 @@ export declare abstract class AbstractControl {
     }): void;
     setParent(parent: FormGroup | FormArray): void;
     setValidators(newValidator: ValidatorFn | ValidatorFn[]): void;
+    abstract updateValue(value: any, options?: Object): void;
     updateValueAndValidity({onlySelf, emitEvent}?: {
         onlySelf?: boolean;
         emitEvent?: boolean;
@@ -127,6 +128,9 @@ export declare class FormArray extends AbstractControl {
     insert(index: number, control: AbstractControl): void;
     push(control: AbstractControl): void;
     removeAt(index: number): void;
+    updateValue(value: any[], {onlySelf}?: {
+        onlySelf?: boolean;
+    }): void;
 }
 
 /** @experimental */
@@ -211,6 +215,11 @@ export declare class FormGroup extends AbstractControl {
     include(controlName: string): void;
     registerControl(name: string, control: AbstractControl): AbstractControl;
     removeControl(name: string): void;
+    updateValue(value: {
+        [key: string]: any;
+    }, {onlySelf}?: {
+        onlySelf?: boolean;
+    }): void;
 }
 
 /** @experimental */
@@ -312,6 +321,9 @@ export declare class NgForm extends ControlContainer implements Form {
     removeControl(dir: NgModel): void;
     removeFormGroup(dir: NgModelGroup): void;
     updateModel(dir: NgControl, value: any): void;
+    updateValue(value: {
+        [key: string]: any;
+    }): void;
 }
 
 /** @experimental */