From 617acf4cd6403951fcac13025bc7d6f68785fb29 Mon Sep 17 00:00:00 2001 From: vsavkin Date: Thu, 1 Oct 2015 15:47:51 -0700 Subject: [PATCH] docs(core): add docs to HostBinding and HostListener --- modules/angular2/src/core/metadata.ts | 27 +-- .../angular2/src/core/metadata/directives.ts | 209 ++++++++++-------- 2 files changed, 116 insertions(+), 120 deletions(-) diff --git a/modules/angular2/src/core/metadata.ts b/modules/angular2/src/core/metadata.ts index 40cc6c814b..6650a8afb8 100644 --- a/modules/angular2/src/core/metadata.ts +++ b/modules/angular2/src/core/metadata.ts @@ -472,19 +472,7 @@ export interface OutputFactory { } /** - * {@link HostBindingMetadata} factory for creating decorators. - * - * ## Example as TypeScript Decorator - * - * ``` - * @Directive({ - * selector: 'sample-dir' - * }) - * class SampleDir { - * @HostBinding() prop1; // Same as @HostBinding('prop1') prop1; - * @HostBinding("el-prop") prop1; - * } - * ``` + * {@link HostBindingMetadata} factory function. */ export interface HostBindingFactory { (hostPropertyName?: string): any; @@ -492,18 +480,7 @@ export interface HostBindingFactory { } /** - * {@link HostListenerMetadata} factory for creating decorators. - * - * ## Example as TypeScript Decorator - * - * ``` - * @Directive({ - * selector: 'sample-dir' - * }) - * class SampleDir { - * @HostListener("change", ['$event.target.value']) onChange(value){} - * } - * ``` + * {@link HostListenerMetadata} factory function. */ export interface HostListenerFactory { (eventName: string, args?: string[]): any; diff --git a/modules/angular2/src/core/metadata/directives.ts b/modules/angular2/src/core/metadata/directives.ts index 2505c35016..41ffec1683 100644 --- a/modules/angular2/src/core/metadata/directives.ts +++ b/modules/angular2/src/core/metadata/directives.ts @@ -517,9 +517,9 @@ export class DirectiveMetadata extends InjectableMetadata { /** * Specify the events, actions, properties and attributes related to the host element. * - * ## Events + * ## Host Listeners * - * Specifies which DOM hostListeners a directive listens to via a set of `(event)` to `method` + * Specifies which DOM events a directive listens to via a set of `(event)` to `method` * key-value pairs: * * - `event1`: the DOM event that the directive listens to. @@ -530,76 +530,86 @@ export class DirectiveMetadata extends InjectableMetadata { * To listen to global events, a target must be added to the event name. * The target can be `window`, `document` or `body`. * - * When writing a directive event binding, you can also refer to the following local variables: - * - `$event`: Current event object which triggered the event. - * - `$target`: The source of the event. This will be either a DOM element or an Angular - * directive. (will be implemented in later release) + * When writing a directive event binding, you can also refer to the $event local variable. * - * ## Syntax + * ### Example ([live demo](http://plnkr.co/edit/DlA5KU?p=preview)) * - * ``` + * The following example declares a directive that attaches a click listener to the button and + * counts clicks. + * + * ```typescript * @Directive({ + * selector: 'button[counting]', * host: { - * '(event1)': 'onMethod1(arguments)', - * '(target:event2)': 'onMethod2(arguments)', - * ... - * } - * } - * ``` - * - * ## Basic Event Binding: - * - * Suppose you want to write a directive that reacts to `change` events in the DOM and on - * `resize` events in window. - * You would define the event binding as follows: - * - * ``` - * @Directive({ - * selector: 'input', - * host: { - * '(change)': 'onChange($event)', - * '(window:resize)': 'onResize($event)' + * '(click)': 'onClick($event.target)' * } * }) - * class InputDirective { - * onChange(event:Event) { - * // invoked when the input element fires the 'change' event - * } - * onResize(event:Event) { - * // invoked when the window fires the 'resize' event + * class CountClicks { + * numberOfClicks = 0; + * + * onClick(btn) { + * console.log("button", btn, "number of clicks:", this.numberOfClicks++); * } * } + * + * @Component({selector: 'app'}) + * @View({ + * template: ``, + * directives: [CountClicks] + * }) + * class App {} + * + * bootstrap(App); * ``` * - * ## Properties + * ## Host Property Bindings * - * Specifies which DOM properties a directives updates. + * Specifies which DOM properties a directive updates. * - * ## Syntax + * Angular automatically checks host property bindings during change detection. + * If a binding changes, it will update the host element of the directive. * - * ``` + * ### Example ([live demo](http://plnkr.co/edit/gNg0ED?p=preview)) + * + * The following example creates a directive that sets the `valid` and `invalid` classes + * on the DOM element that has ng-model directive on it. + * + * ```typescript * @Directive({ - * selector: 'input', + * selector: '[ng-model]', * host: { - * '[prop]': 'expression' + * '[class.valid]': 'valid', + * '[class.invalid]': 'invalid' * } * }) - * class InputDirective { - * value:string; + * class NgModelStatus { + * constructor(public control:NgModel) {} + * get valid { return this.control.valid; } + * get invalid { return this.control.invalid; } * } - * ``` * - * In this example the `prop` property of the host element is updated with the expression value - * every time it changes. + * @Component({selector: 'app'}) + * @View({ + * template: ``, + * directives: [FORM_DIRECTIVES, NgModelStatus] + * }) + * class App { + * prop; + * } + * + * bootstrap(App); + * ``` * * ## Attributes * - * Specifies static attributes that should be propagated to a host element. Attributes specified - * in `hostAttributes` are propagated only if a given attribute is not present on a host element. + * Specifies static attributes that should be propagated to a host element. * - * ## Syntax + * ### Example * - * ``` + * In this example using `my-button` directive (ex.: `
`) on a host element + * (here: `
` ) will ensure that this element will get the "button" role. + * + * ```typescript * @Directive({ * selector: '[my-button]', * host: { @@ -609,10 +619,6 @@ export class DirectiveMetadata extends InjectableMetadata { * class MyButton { * } * ``` - * - * In this example using `my-button` directive (ex.: `
`) on a host element - * (here: `
` ) will ensure that this element will get the "button" role. - * */ host: StringMap; @@ -926,9 +932,9 @@ export class PipeMetadata extends InjectableMetadata { * * Angular automatically updates data-bound properties during change detection. * - * `InputMetadata` takes an optional parameters that specifies that name + * `InputMetadata` takes an optional parameter that specifies the name * used when instantiating a component in the template. When not provided, - * the class property name is used. + * the name of the decorated property is used. * * ### Example * @@ -977,9 +983,9 @@ export class InputMetadata { * When an output property emits an event, an event handler attached to that event * the template is invoked. * - * `OutputMetadata` takes an optional parameters that specifies that name + * `OutputMetadata` takes an optional parameter that specifies the name * used when instantiating a component in the template. When not provided, - * the class property name is used. + * the name of the decorated property is used. * * ### Example * @@ -1018,33 +1024,38 @@ export class OutputMetadata { } /** - * Declares a host binding property. + * Declares a host property binding. * - * Angular automatically updates data-bound properties during change detection. + * Angular automatically checks host property bindings during change detection. + * If a binding changes, it will update the host element of the directive. + * + * `HostBindingMetadata` takes an optional parameter that specifies the property + * name of the host element that will be updated. When not provided, + * the class property name is used. * * ### Example * - * ``` - * @Directive({ - * selector: 'sample-dir' - * }) - * class SampleDir { - * @HostBinding() prop1; // Same as @HostBinding('prop1') prop1; - * @HostBinding("el-prop") prop2; - * } - * ``` + * The following example creates a directive that sets the `valid` and `invalid` classes + * on the DOM element that has ng-model directive on it. * - * This is equivalent to - * - * ``` - * @Directive({ - * selector: 'sample-dir', - * host: {'[prop1]': 'prop1', '[el-prop]': 'prop2'} - * }) - * class SampleDir { - * prop1; - * prop2; + * ```typescript + * @Directive({selector: '[ng-model]'}) + * class NgModelStatus { + * constructor(public control:NgModel) {} + * @HostBinding('[class.valid]') get valid { return this.control.valid; } + * @HostBinding('[class.invalid]') get invalid { return this.control.invalid; } * } + * + * @Component({selector: 'app'}) + * @View({ + * template: ``, + * directives: [FORM_DIRECTIVES, NgModelStatus] + * }) + * class App { + * prop; + * } + * + * bootstrap(App); * ``` */ @CONST() @@ -1053,29 +1064,37 @@ export class HostBindingMetadata { } /** - * Declare a host listener. + * Declares a host listener. * - * ## Example + * Angular will invoke the decorated method when the host element emits the specified event. * - * ``` - * @Directive({ - * selector: 'sample-dir' - * }) - * class SampleDir { - * @HostListener("change", ['$event.target.value']) onChange(value){} + * If the decorated method returns `false`, then `preventDefault` is applied on the DOM + * event. + * + * ### Example + * + * The following example declares a directive that attaches a click listener to the button and + * counts clicks. + * + * ```typescript + * @Directive({selector: 'button[counting]'}) + * class CountClicks { + * numberOfClicks = 0; + * + * @HostListener('click', ['$event.target']) + * onClick(btn) { + * console.log("button", btn, "number of clicks:", this.numberOfClicks++); + * } * } - * ``` * - * This is equivalent to - * - * ``` - * @Directive({ - * selector: 'sample-dir', - * host: {'(change)': 'onChange($event.target.value)'} + * @Component({selector: 'app'}) + * @View({ + * template: ``, + * directives: [CountClicks] * }) - * class SampleDir { - * onChange(value){} - * } + * class App {} + * + * bootstrap(App); * ``` */ @CONST()