From 20953ed4928432ffabe34462466cdb7f067fd2a2 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Tue, 9 Jun 2015 12:46:21 +0200 Subject: [PATCH] doc(Directive): update docs for Directive.host --- modules/angular2/docs/core/02_directives.md | 4 +- .../src/core/annotations_impl/annotations.ts | 75 +++++++++---------- 2 files changed, 37 insertions(+), 42 deletions(-) diff --git a/modules/angular2/docs/core/02_directives.md b/modules/angular2/docs/core/02_directives.md index 9210f3c3e0..1b3ab96303 100644 --- a/modules/angular2/docs/core/02_directives.md +++ b/modules/angular2/docs/core/02_directives.md @@ -66,8 +66,8 @@ Here is a trivial example of a tooltip decorator. The directive will log a toolt properties: [ | List which properties need to be bound 'text: tooltip' | - DOM element tooltip property should be ], | mapped to the directive text property. - hostListeners: { | List which events need to be mapped. - mouseover: 'show' | - Invoke the show() method every time + host: { | List which events need to be mapped. + (mouseover): 'show()' | - Invoke the show() method every time } | the mouseover event is fired. }) | class Form { | Directive controller class, instantiated diff --git a/modules/angular2/src/core/annotations_impl/annotations.ts b/modules/angular2/src/core/annotations_impl/annotations.ts index 7b0257d0da..de1cb96891 100644 --- a/modules/angular2/src/core/annotations_impl/annotations.ts +++ b/modules/angular2/src/core/annotations_impl/annotations.ts @@ -585,12 +585,13 @@ export class Directive extends Injectable { */ events: List; - // TODO(vicb): doc - /** - * Specifies which DOM hostListeners a directive listens to. + * Specifiy the events, actions, properties and attributes related to the host element. * - * The `hostListeners` property defines a set of `event` to `method` key-value pairs: + * ## Events + * + * Specifies which DOM hostListeners a directive listens to via a set of `(event)` to `method` + * key-value pairs: * * - `event1`: the DOM event that the directive listens to. * - `statement`: the statement to execute when the event occurs. @@ -603,17 +604,15 @@ export class Directive extends Injectable { * 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) - * + * directive. (will be implemented in later release) * * ## Syntax * * ``` * @Directive({ - * hostListeners: { - * 'event1': 'onMethod1(arguments)', - * 'target:event2': 'onMethod2(arguments)', + * host: { + * '(event1)': 'onMethod1(arguments)', + * '(target:event2)': 'onMethod2(arguments)', * ... * } * } @@ -621,31 +620,30 @@ export class Directive extends Injectable { * * ## Basic Event Binding: * - * Suppose you want to write a directive that triggers on `change` events in the DOM and on + * 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', - * hostListeners: { - * 'change': 'onChange($event)', - * 'window:resize': 'onResize($event)' + * host: { + * '(change)': 'onChange($event)', + * '(window:resize)': 'onResize($event)' * } * }) * 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 * } * } * ``` * - * Here the `onChange` method of `InputDirective` is invoked whenever the DOM element fires the - * 'change' event. + * ## Properties * - */ - /** * Specifies which DOM properties a directives updates. * * ## Syntax @@ -653,42 +651,41 @@ export class Directive extends Injectable { * ``` * @Directive({ * selector: 'input', - * hostProperties: { - * 'value': 'value' + * host: { + * '[prop]': 'expression' * } * }) * class InputDirective { * value:string; * } - * - * In this example every time the value property of the decorator changes, Angular will update the - * value property of - * the host element. * ``` - */ - /** + * + * In this example the prop property of the host element is updated with the expression value + * every time it changes. + * + * ## 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. + * in `hostAttributes` are propagated only if a given attribute is not present on a host element. * * ## Syntax * * ``` * @Directive({ * selector: '[my-button]', - * hostAttributes: { + * host: { * 'role': 'button' * } * }) * 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. - * ``` - */ - /** + * (here: `
` ) will ensure that this element will get the "button" role. + * + * ## Actions + * * Specifies which DOM methods a directive can invoke. * * ## Syntax @@ -696,8 +693,8 @@ export class Directive extends Injectable { * ``` * @Directive({ * selector: 'input', - * hostActions: { - * 'emitFocus': 'focus()' + * host: { + * '@emitFocus': 'focus()' * } * }) * class InputDirective { @@ -709,12 +706,10 @@ export class Directive extends Injectable { * this.emitFocus.next(); * } * } - * - * In this example calling focus on InputDirective will result in calling focus on the DOM - * element. * ``` + * + * In this example calling focus on InputDirective will result in calling focus on the input. */ - host: StringMap; /**