cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(forms): update API reference for common APIs and template-driven directives (#27033)

Browse Source 
PR Close #27033
This commit is contained in:
Brandon Roberts
2018-11-09 14:11:21 -06:00
committed by Igor Minar
parent 2389a68ea3
commit c331fc6f0c
7 changed files with 290 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
packages/forms/src/directives/ng_form.ts
View File

@ -27,34 +27,36 @@ const resolvedPromise = Promise.resolve(null);
/**
* @description
*
* Creates a top-level `FormGroup` instance and binds it to a form
* to track aggregate form value and validation status.
*
* As soon as you import the `FormsModule`, this directive becomes active by default on
* all `<form>` tags. You don't need to add a special selector.
*
* You can export the directive into a local template variable using `ngForm` as the key
* You optionally export the directive into a local template variable using `ngForm` as the key
* (ex: `#myForm="ngForm"`). This is optional, but useful. Many properties from the underlying
* `FormGroup` instance are duplicated on the directive itself, so a reference to it
* will give you access to the aggregate value and validity status of the form, as well as
* gives you access to the aggregate value and validity status of the form, as well as
* user interaction properties like `dirty` and `touched`.
*
* To register child controls with the form, you'll want to use `NgModel` with a
* `name` attribute. You can also use `NgModelGroup` if you'd like to create
* sub-groups within the form.
* To register child controls with the form, use `NgModel` with a `name`
* attribute. You may use `NgModelGroup` to create sub-groups within the form.
*
* You can listen to the directive's `ngSubmit` event to be notified when the user has
* triggered a form submission. The `ngSubmit` event will be emitted with the original form
* If necessary, listen to the directive's `ngSubmit` event to be notified when the user has
* triggered a form submission. The `ngSubmit` event emits the original form
* submission event.
*
* In template driven forms, all `<form>` tags are automatically tagged as `NgForm`.
* If you want to import the `FormsModule` but skip its usage in some forms,
* for example, to use native HTML5 validation, you can add `ngNoForm` and the `<form>`
* To import the `FormsModule` but skip its usage in some forms,
* for example, to use native HTML5 validation, add the `ngNoForm` and the `<form>`
* tags won't create an `NgForm` directive. In reactive forms, using `ngNoForm` is
* unnecessary because the `<form>` tags are inert. In that case, you would
* refrain from using the `formGroup` directive.
*
* @usageNotes
*
* ### Migrating from deprecated ngForm selector
*
* Support for using `ngForm` element selector has been deprecated in Angular v6 and will be removed
* in Angular v9.
*
@ -71,8 +73,23 @@ const resolvedPromise = Promise.resolve(null);
* <ng-form #myForm="ngForm">
* ```
*
* ### Listening for form submission
*
* The following example shows how to capture the form values from the "ngSubmit" event.
*
* {@example forms/ts/simpleForm/simple_form_example.ts region='Component'}
*
* ### Setting the update options
*
* The following example shows you how to change the "updateOn" option from its default using
* ngFormOptions.
*
* ```html
* <form [ngFormOptions]="{updateOn: 'blur'}">
* <input name="one" ngModel> <!-- this ngModel will update on blur -->
* </form>
* ```
*
* @ngModule FormsModule
* @publicApi
*/
@ -85,25 +102,33 @@ const resolvedPromise = Promise.resolve(null);
})
export class NgForm extends ControlContainer implements Form,
AfterViewInit {
/**
* @description
* Returns whether the form submission has been triggered.
*/
public readonly submitted: boolean = false;
private _directives: NgModel[] = [];
/**
* @description
* The `FormGroup` instance created for this form.
*/
form: FormGroup;
/**
* @description
* Event emitter for the "ngSubmit" event
*/
ngSubmit = new EventEmitter();
/**
* Options for the `NgForm` instance. Accepts the following properties:
* @description
* Tracks options for the `NgForm` instance.
*
* **updateOn**: Serves as the default `updateOn` value for all child `NgModels` below it
* (unless a child has explicitly set its own value for this in `ngModelOptions`).
* Potential values: `'change'` | `'blur'` | `'submit'`
*
* ```html
* <form [ngFormOptions]="{updateOn: 'blur'}">
* <input name="one" ngModel> <!-- this ngModel will update on blur -->
* </form>
* ```
* **updateOn**: Sets the default `updateOn` value for all child `NgModels` below it
* unless explicitly set by a child `NgModel` using `ngModelOptions`). Defaults to 'change'.
* Possible values: `'change'` | `'blur'` | `'submit'`.
*
*/
// TODO(issue/24571): remove '!'.
@ -117,16 +142,44 @@ export class NgForm extends ControlContainer implements Form,
new FormGroup({}, composeValidators(validators), composeAsyncValidators(asyncValidators));
}
/**
* @description
* Lifecycle method called after the view is initialized. For internal use only.
*/
ngAfterViewInit() { this._setUpdateStrategy(); }
/**
* @description
* The directive instance.
*/
get formDirective(): Form { return this; }
/**
* @description
* The internal `FormGroup` instance.
*/
get control(): FormGroup { return this.form; }
/**
* @description
* Returns an array representing the path to this group. Because this directive
* always lives at the top level of a form, it is always an empty array.
*/
get path(): string[] { return []; }
/**
* @description
* Returns a map of the controls in this group.
*/
get controls(): {[key: string]: AbstractControl} { return this.form.controls; }
/**
* @description
* Method that sets up the control directive in this group, re-calculates its value
* and validity, and adds the instance to the internal list of directives.
*
* @param dir The `NgModel` directive instance.
*/
addControl(dir: NgModel): void {
resolvedPromise.then(() => {
const container = this._findContainer(dir.path);
@ -138,8 +191,20 @@ export class NgForm extends ControlContainer implements Form,
});
}
/**
* @description
* Retrieves the `FormControl` instance from the provided `NgModel` directive.
*
* @param dir The `NgModel` directive instance.
*/
getControl(dir: NgModel): FormControl { return <FormControl>this.form.get(dir.path); }
/**
* @description
* Removes the `NgModel` instance from the internal list of directives
*
* @param dir The `NgModel` directive instance.
*/
removeControl(dir: NgModel): void {
resolvedPromise.then(() => {
const container = this._findContainer(dir.path);
@ -150,6 +215,12 @@ export class NgForm extends ControlContainer implements Form,
});
}
/**
* @description
* Adds a new `NgModelGroup` directive instance to the form.
*
* @param dir The `NgModelGroup` directive instance.
*/
addFormGroup(dir: NgModelGroup): void {
resolvedPromise.then(() => {
const container = this._findContainer(dir.path);
@ -160,6 +231,12 @@ export class NgForm extends ControlContainer implements Form,
});
}
/**
* @description
* Removes the `NgModelGroup` directive instance from the form.
*
* @param dir The `NgModelGroup` directive instance.
*/
removeFormGroup(dir: NgModelGroup): void {
resolvedPromise.then(() => {
const container = this._findContainer(dir.path);
@ -169,8 +246,20 @@ export class NgForm extends ControlContainer implements Form,
});
}
/**
* @description
* Retrieves the `FormGroup` for a provided `NgModelGroup` directive instance
*
* @param dir The `NgModelGroup` directive instance.
*/
getFormGroup(dir: NgModelGroup): FormGroup { return <FormGroup>this.form.get(dir.path); }
/**
* Sets the new value for the provided `NgControl` directive.
*
* @param dir The `NgControl` directive instance.
* @param value The new value for the directive's control.
*/
updateModel(dir: NgControl, value: any): void {
resolvedPromise.then(() => {
const ctrl = <FormControl>this.form.get(dir.path !);
@ -178,8 +267,21 @@ export class NgForm extends ControlContainer implements Form,
});
}
/**
* @description
* Sets the value for this `FormGroup`.
*
* @param value The new value
*/
setValue(value: {[key: string]: any}): void { this.control.setValue(value); }
/**
* @description
* Method called when the "submit" event is triggered on the form.
* Triggers the `ngSubmit` emitter to emit the "submit" event as its payload.
*
* @param $event The "submit" event object
*/
onSubmit($event: Event): boolean {
(this as{submitted: boolean}).submitted = true;
syncPendingControls(this.form, this._directives);
@ -187,8 +289,18 @@ export class NgForm extends ControlContainer implements Form,
return false;
}
/**
* @description
* Method called when the "reset" event is triggered on the form.
*/
onReset(): void { this.resetForm(); }
/**
* @description
* Resets the form to an initial value and resets its submitted status.
*
* @param value The new value for the form.
*/
resetForm(value: any = undefined): void {
this.form.reset(value);
(this as{submitted: boolean}).submitted = false;