From 6622826587b50175373978950b6c186e4a494ce3 Mon Sep 17 00:00:00 2001 From: vsavkin Date: Thu, 11 Jun 2015 09:58:53 -0700 Subject: [PATCH] docs(forms): updated forms docs to cover new apis --- .../directives/checkbox_value_accessor.ts | 1 - .../src/forms/directives/control_container.ts | 2 +- .../directives/control_value_accessor.ts | 5 ++ .../directives/default_value_accessor.ts | 8 +-- .../src/forms/directives/form_interface.ts | 5 ++ .../src/forms/directives/ng_control.ts | 4 +- .../src/forms/directives/ng_control_group.ts | 52 +++++++------- .../src/forms/directives/ng_control_name.ts | 67 ++++++++++++------- .../angular2/src/forms/directives/ng_form.ts | 34 ++++++++++ .../src/forms/directives/ng_form_control.ts | 23 +++++-- .../src/forms/directives/ng_form_model.ts | 35 ++++++++-- .../angular2/src/forms/directives/ng_model.ts | 18 +++++ .../select_control_value_accessor.ts | 10 +-- 13 files changed, 184 insertions(+), 80 deletions(-) diff --git a/modules/angular2/src/forms/directives/checkbox_value_accessor.ts b/modules/angular2/src/forms/directives/checkbox_value_accessor.ts index 3f7a4287ee..b4c8cb1b6b 100644 --- a/modules/angular2/src/forms/directives/checkbox_value_accessor.ts +++ b/modules/angular2/src/forms/directives/checkbox_value_accessor.ts @@ -5,7 +5,6 @@ import {ControlValueAccessor} from './control_value_accessor'; /** * The accessor for writing a value and listening to changes on a checkbox input element. * - * * # Example * ``` * diff --git a/modules/angular2/src/forms/directives/control_container.ts b/modules/angular2/src/forms/directives/control_container.ts index 23f7fbf059..d5ff40b4ba 100644 --- a/modules/angular2/src/forms/directives/control_container.ts +++ b/modules/angular2/src/forms/directives/control_container.ts @@ -4,7 +4,7 @@ import {List} from 'angular2/src/facade/collection'; /** * A directive that contains a group of [NgControl]. * - * @exportedAs angular2/forms + * Only used by the forms module. */ export class ControlContainer { name: string; diff --git a/modules/angular2/src/forms/directives/control_value_accessor.ts b/modules/angular2/src/forms/directives/control_value_accessor.ts index c28cdec221..df953dfc72 100644 --- a/modules/angular2/src/forms/directives/control_value_accessor.ts +++ b/modules/angular2/src/forms/directives/control_value_accessor.ts @@ -1,3 +1,8 @@ +/** + * A bridge between a control and a native element. + * + * Please see {@link DefaultValueAccessor} for more information. + */ export interface ControlValueAccessor { writeValue(obj: any): void; registerOnChange(fn: any): void; diff --git a/modules/angular2/src/forms/directives/default_value_accessor.ts b/modules/angular2/src/forms/directives/default_value_accessor.ts index 3cde8304e2..cf1169fa58 100644 --- a/modules/angular2/src/forms/directives/default_value_accessor.ts +++ b/modules/angular2/src/forms/directives/default_value_accessor.ts @@ -4,14 +4,12 @@ import {ControlValueAccessor} from './control_value_accessor'; import {isBlank} from 'angular2/src/facade/lang'; /** - * The default accessor for writing a value and listening to changes that is used by a - * {@link Control} directive. - * - * This is the default strategy that Angular uses when no other accessor is applied. + * The default accessor for writing a value and listening to changes that is used by the + * {@link NgModel}, {@link NgFormControl}, and {@link NgControlName} directives. * * # Example * ``` - * + * * ``` * * @exportedAs angular2/forms diff --git a/modules/angular2/src/forms/directives/form_interface.ts b/modules/angular2/src/forms/directives/form_interface.ts index d2aadcd3f0..6452d095e2 100644 --- a/modules/angular2/src/forms/directives/form_interface.ts +++ b/modules/angular2/src/forms/directives/form_interface.ts @@ -2,6 +2,11 @@ import {NgControl} from './ng_control'; import {NgControlGroup} from './ng_control_group'; import {Control} from '../model'; +/** + * An interface that {@link NgFormModel} and {@link NgForm} implement. + * + * Only used by the forms module. + */ export interface Form { addControl(dir: NgControl): void; removeControl(dir: NgControl): void; diff --git a/modules/angular2/src/forms/directives/ng_control.ts b/modules/angular2/src/forms/directives/ng_control.ts index 46a0f5ccd4..0b7fb2cfac 100644 --- a/modules/angular2/src/forms/directives/ng_control.ts +++ b/modules/angular2/src/forms/directives/ng_control.ts @@ -3,7 +3,9 @@ import {Validators} from '../validators'; import {Control} from '../model'; /** - * A directive that bind a [ng-control] object to a DOM element. + * An abstract class that all control directive extend. + * + * It binds a {@link Control} object to a DOM element. * * @exportedAs angular2/forms */ diff --git a/modules/angular2/src/forms/directives/ng_control_group.ts b/modules/angular2/src/forms/directives/ng_control_group.ts index 0fcb4c76a2..d67fcbc33d 100644 --- a/modules/angular2/src/forms/directives/ng_control_group.ts +++ b/modules/angular2/src/forms/directives/ng_control_group.ts @@ -10,43 +10,37 @@ const controlGroupBinding = CONST_EXPR(new Binding(ControlContainer, {toAlias: FORWARD_REF(() => NgControlGroup)})); /** - * Binds a ng-control group to a DOM element. + * Creates and binds a control group to a DOM element. + * + * This directive can only be used as a child of {@link NgForm} or {@link NgFormModel}. * * # Example * - * In this example, we create a ng-control group, and we bind the login and - * password controls to the login and password elements. - * - * Here we use {@link formDirectives}, rather than importing each form directive individually, e.g. - * `NgControl`, `ControlGroupDirective`. This is just a shorthand for the same end result. + * In this example, we create the credentials and personal control groups. + * We can work with each group separately: check its validity, get its value, listen to its changes. * * ``` - * @Component({selector: "login-comp"}) + * @Component({selector: "signup-comp"}) * @View({ * directives: [formDirectives], - * template: - * "
" + - * "
- * "Login " + - * "Password " + - * "" + - * "
" - * "
" - * }) - * class LoginComp { - * loginForm:ControlGroup; + * template: ` + *
+ *
+ * Login + * Password + *
+ *
Credentials are invalid
* - * constructor() { - * this.loginForm = new ControlGroup({ - * credentials: new ControlGroup({ - * login: new Cntrol(""), - * password: new Control("") - * }) - * }); - * } - * - * onLogin() { - * // this.loginForm.value + *
+ * Name + *
+ * + *
+ * `}) + * class SignupComp { + * onSignUp(value) { + * // value === {personal: {name: 'some name'}, + * // credentials: {login: 'some login', password: 'some password'}} * } * } * diff --git a/modules/angular2/src/forms/directives/ng_control_name.ts b/modules/angular2/src/forms/directives/ng_control_name.ts index f3cd699e65..c0a5188f71 100644 --- a/modules/angular2/src/forms/directives/ng_control_name.ts +++ b/modules/angular2/src/forms/directives/ng_control_name.ts @@ -13,44 +13,59 @@ const controlNameBinding = CONST_EXPR(new Binding(NgControl, {toAlias: FORWARD_REF(() => NgControlName)})); /** - * Binds a control with the specified name to a DOM element. + * Creates and binds a control with a specified name to a DOM element. * + * This directive can only be used as a child of {@link NgForm} or {@link NgFormModel}. + * # Example * - * In this example, we bind the login control to an input element. When the value of the input - * element - * changes, the value of - * the control will reflect that change. Likewise, if the value of the control changes, the input - * element reflects that - * change. - * - * Here we use {@link formDirectives}, rather than importing each form directive individually, e.g. - * `NgControl`, `ControlGroupDirective`. This is just a shorthand for the same end result. + * In this example, we create the login and password controls. + * We can work with each control separately: check its validity, get its value, listen to its + changes. * * ``` * @Component({selector: "login-comp"}) * @View({ * directives: [formDirectives], - * template: - * "
" + - * "Login " + - * "" + - * "
" - * }) + * template: ` + *
+ * Login + *
Login is invalid
+ * + * Password + + * + *
+ * `}) * class LoginComp { - * loginForm:ControlGroup; - * - * constructor() { - * this.loginForm = new ControlGroup({ - * login: new Control(""), - * }); - * } - * - * onLogin() { - * // this.loginForm.value + * onLogIn(value) { + * // value === {login: 'some login', password: 'some password'} * } * } + * ``` * + * We can also use ng-model to bind a domain model to the form. + * + * ``` + * @Component({selector: "login-comp"}) + * @View({ + * directives: [formDirectives], + * template: ` + *
+ * Login + * Password + * + *
+ * `}) + * class LoginComp { + * credentials: {login:string, password:string}; + * + * onLogIn() { + * // this.credentials.login === "some login" + * // this.credentials.password === "some password" + * } + * } * ``` * * @exportedAs angular2/forms diff --git a/modules/angular2/src/forms/directives/ng_form.ts b/modules/angular2/src/forms/directives/ng_form.ts index 2f208a43c4..421e315fcf 100644 --- a/modules/angular2/src/forms/directives/ng_form.ts +++ b/modules/angular2/src/forms/directives/ng_form.ts @@ -13,6 +13,40 @@ import {setUpControl} from './shared'; const formDirectiveBinding = CONST_EXPR(new Binding(ControlContainer, {toAlias: FORWARD_REF(() => NgForm)})); +/** + * Creates and binds a form object to a DOM element. + * + * # Example + * + * ``` + * @Component({selector: "signup-comp"}) + * @View({ + * directives: [formDirectives], + * template: ` + *
+ *
+ * Login + * Password + *
+ *
Credentials are invalid
+ * + *
+ * Name + *
+ * + *
+ * `}) + * class SignupComp { + * onSignUp(value) { + * // value === {personal: {name: 'some name'}, + * // credentials: {login: 'some login', password: 'some password'}} + * } + * } + * + * ``` + * + * @exportedAs angular2/forms + */ @Directive({ selector: 'form:not([ng-no-form]):not([ng-form-model]),ng-form,[ng-form]', hostInjector: [formDirectiveBinding], diff --git a/modules/angular2/src/forms/directives/ng_form_control.ts b/modules/angular2/src/forms/directives/ng_form_control.ts index 965d81a0a9..edd458b5a5 100644 --- a/modules/angular2/src/forms/directives/ng_form_control.ts +++ b/modules/angular2/src/forms/directives/ng_form_control.ts @@ -13,7 +13,7 @@ const formControlBinding = CONST_EXPR(new Binding(NgControl, {toAlias: FORWARD_REF(() => NgFormControl)})); /** - * Binds a control to a DOM element. + * Binds an existing control to a DOM element. * * # Example * @@ -23,9 +23,6 @@ const formControlBinding = * element reflects that * change. * - * Here we use {@link formDirectives}, rather than importing each form directive individually, e.g. - * `NgControl`, `ControlGroupDirective`. This is just a shorthand for the same end result. - * * ``` * @Component({selector: "login-comp"}) * @View({ @@ -42,6 +39,24 @@ const formControlBinding = * * ``` * + * We can also use ng-model to bind a domain model to the form. + * + * ``` + * @Component({selector: "login-comp"}) + * @View({ + * directives: [formDirectives], + * template: "" + * }) + * class LoginComp { + * loginControl:Control; + * login:string; + * + * constructor() { + * this.loginControl = new Control(''); + * } + * } + * ``` + * * @exportedAs angular2/forms */ @Directive({ diff --git a/modules/angular2/src/forms/directives/ng_form_model.ts b/modules/angular2/src/forms/directives/ng_form_model.ts index 8ab7596213..3c6a2e508a 100644 --- a/modules/angular2/src/forms/directives/ng_form_model.ts +++ b/modules/angular2/src/forms/directives/ng_form_model.ts @@ -15,7 +15,7 @@ const formDirectiveBinding = CONST_EXPR(new Binding(ControlContainer, {toAlias: FORWARD_REF(() => NgFormModel)})); /** - * Binds a control group to a DOM element. + * Binds an existing control group to a DOM element. * * # Example * @@ -23,9 +23,6 @@ const formDirectiveBinding = * password controls to the * login and password elements. * - * Here we use {@link formDirectives}, rather than importing each form directive individually, e.g. - * `NgControl`, `NgControlGroup`. This is just a shorthand for the same end result. - * * ``` * @Component({selector: "login-comp"}) * @View({ @@ -53,6 +50,36 @@ const formDirectiveBinding = * * ``` * + * We can also use ng-model to bind a domain model to the form. + * + * ``` + * @Component({selector: "login-comp"}) + * @View({ + * directives: [formDirectives], + * template: "
" + + * "Login " + + * "Password " + + * "" + + * "
" + * }) + * class LoginComp { + * credentials:{login:string, password:string} + * loginForm:ControlGroup; + * + * constructor() { + * this.loginForm = new ControlGroup({ + * login: new Control(""), + * password: new Control("") + * }); + * } + * + * onLogin() { + * // this.credentials.login === 'some login' + * // this.credentials.password === 'some password' + * } + * } + * ``` + * * @exportedAs angular2/forms */ @Directive({ diff --git a/modules/angular2/src/forms/directives/ng_model.ts b/modules/angular2/src/forms/directives/ng_model.ts index dba5144f5b..d52741833d 100644 --- a/modules/angular2/src/forms/directives/ng_model.ts +++ b/modules/angular2/src/forms/directives/ng_model.ts @@ -12,6 +12,24 @@ import {setUpControl} from './shared'; const formControlBinding = CONST_EXPR(new Binding(NgControl, {toAlias: FORWARD_REF(() => NgModel)})); +/** + * Binds a domain model to the form. + * + * # Example + * ``` + * @Component({selector: "search-comp"}) + * @View({ + * directives: [formDirectives], + * template: ` + + * `}) + * class SearchComp { + * searchQuery: string; + * } + * ``` + * + * @exportedAs angular2/forms + */ @Directive({ selector: '[ng-model]:not([ng-control]):not([ng-form-control])', hostInjector: [formControlBinding], diff --git a/modules/angular2/src/forms/directives/select_control_value_accessor.ts b/modules/angular2/src/forms/directives/select_control_value_accessor.ts index 72f181944c..c0f48c58ba 100644 --- a/modules/angular2/src/forms/directives/select_control_value_accessor.ts +++ b/modules/angular2/src/forms/directives/select_control_value_accessor.ts @@ -3,15 +3,7 @@ import {NgControl} from './ng_control'; import {ControlValueAccessor} from './control_value_accessor'; /** - * The accessor for writing a value and listening to changes that is used by a - * {@link Control} directive. - * - * This is the default strategy that Angular uses when no other accessor is applied. - * - * # Example - * ``` - * - * ``` + * The accessor for writing a value and listening to changes on a select element. * * @exportedAs angular2/forms */