From e33037a2f101d186dccc64ba13cd7a19a2996a0a Mon Sep 17 00:00:00 2001 From: vsavkin Date: Wed, 14 Sep 2016 14:49:12 -0700 Subject: [PATCH] docs(core): docs for Directive and Component --- modules/@angular/core/src/metadata.ts | 2 +- .../@angular/core/src/metadata/directives.ts | 526 +++--------------- 2 files changed, 82 insertions(+), 446 deletions(-) diff --git a/modules/@angular/core/src/metadata.ts b/modules/@angular/core/src/metadata.ts index 632fb0a970..267f08ad83 100644 --- a/modules/@angular/core/src/metadata.ts +++ b/modules/@angular/core/src/metadata.ts @@ -19,7 +19,7 @@ import {Type} from './type'; import {TypeDecorator, makeParamDecorator, makePropDecorator} from './util/decorators'; export {ANALYZE_FOR_ENTRY_COMPONENTS, Attribute, ContentChild, ContentChildDecorator, ContentChildren, ContentChildrenDecorator, Query, ViewChild, ViewChildDecorator, ViewChildren, ViewChildrenDecorator} from './metadata/di'; -export {Component, Directive, HostBinding, HostListener, Input, Output, Pipe} from './metadata/directives'; +export {Component, Directive, DirectiveDecorator, ComponentDecorator, HostBinding, HostListener, Input, Output, Pipe} from './metadata/directives'; export {AfterContentChecked, AfterContentInit, AfterViewChecked, AfterViewInit, DoCheck, OnChanges, OnDestroy, OnInit} from './metadata/lifecycle_hooks'; export {CUSTOM_ELEMENTS_SCHEMA, ModuleWithProviders, NO_ERRORS_SCHEMA, NgModule, SchemaMetadata} from './metadata/ng_module'; export {ViewEncapsulation} from './metadata/view'; diff --git a/modules/@angular/core/src/metadata/directives.ts b/modules/@angular/core/src/metadata/directives.ts index 79169bbe80..5e7b132f74 100644 --- a/modules/@angular/core/src/metadata/directives.ts +++ b/modules/@angular/core/src/metadata/directives.ts @@ -23,420 +23,50 @@ import {ViewEncapsulation} from './view'; */ export interface DirectiveDecorator { /** - * Directives allow you to attach behavior to elements in the DOM. + * @whatItDoes Marks a class as an Angular directive and collects directive configuration + * metadata. * - * {@link Directive}s with an embedded view are called {@link Component}s. - * - * A directive consists of a single directive annotation and a controller class. When the - * directive's `selector` matches - * elements in the DOM, the following steps occur: - * - * 1. For each directive, the `ElementInjector` attempts to resolve the directive's constructor - * arguments. - * 2. Angular instantiates directives for each matched element using `ElementInjector` in a - * depth-first order, - * as declared in the HTML. - * - * ## Understanding How Injection Works - * - * There are three stages of injection resolution. - * - *Pre-existing Injectors*: - * - The terminal {@link Injector} cannot resolve dependencies. It either throws an error or, if - * the dependency was - * specified as `@Optional`, returns `null`. - * - The platform injector resolves browser singleton resources, such as: cookies, title, - * location, and others. - * - *Component Injectors*: Each component instance has its own {@link Injector}, and they follow - * the same parent-child hierarchy - * as the component instances in the DOM. - * - *Element Injectors*: Each component instance has a Shadow DOM. Within the Shadow DOM each - * element has an `ElementInjector` - * which follow the same parent-child hierarchy as the DOM elements themselves. - * - * When a template is instantiated, it also must instantiate the corresponding directives in a - * depth-first order. The - * current `ElementInjector` resolves the constructor dependencies for each directive. - * - * Angular then resolves dependencies as follows, according to the order in which they appear in - * the - * {@link Component}: - * - * 1. Dependencies on the current element - * 2. Dependencies on element injectors and their parents until it encounters a Shadow DOM - * boundary - * 3. Dependencies on component injectors and their parents until it encounters the root component - * 4. Dependencies on pre-existing injectors - * - * - * The `ElementInjector` can inject other directives, element-specific special objects, or it can - * delegate to the parent - * injector. - * - * To inject other directives, declare the constructor parameter as: - * - `directive:DirectiveType`: a directive on the current element only - * - `@Host() directive:DirectiveType`: any directive that matches the type between the current - * element and the - * Shadow DOM root. - * - `@Query(DirectiveType) query:QueryList`: A live collection of direct child - * directives. - * - `@QueryDescendants(DirectiveType) query:QueryList`: A live collection of any - * child directives. - * - * To inject element-specific special objects, declare the constructor parameter as: - * - `element: ElementRef` to obtain a reference to logical element in the view. - * - `viewContainer: ViewContainerRef` to control child template instantiation, for - * {@link Directive} directives only - * - `bindingPropagation: BindingPropagation` to control change detection in a more granular way. - * - * ### Example - * - * The following example demonstrates how dependency injection resolves constructor arguments in - * practice. - * - * - * Assume this HTML template: + * @howToUse * * ``` - *
- *
- *
- *
- *
- *
- *
- *
- *
- *
- * ``` - * - * With the following `dependency` decorator and `SomeService` injectable class. - * - * ``` - * @Injectable() - * class SomeService { - * } + * import {Directive} from '@angular/core'; * * @Directive({ - * selector: '[dependency]', - * inputs: [ - * 'id: dependency' - * ] + * selector: 'my-directive', * }) - * class Dependency { - * id:string; + * export class MyDirective { * } * ``` * - * Let's step through the different ways in which `MyDirective` could be declared... + * @description * - * - * ### No injection - * - * Here the constructor is declared with no arguments, therefore nothing is injected into - * `MyDirective`. - * - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor() { - * } - * } - * ``` - * - * This directive would be instantiated with no dependencies. - * - * - * ### Component-level injection - * - * Directives can inject any injectable instance from the closest component injector or any of its - * parents. - * - * Here, the constructor declares a parameter, `someService`, and injects the `SomeService` type - * from the parent - * component's injector. - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor(someService: SomeService) { - * } - * } - * ``` - * - * This directive would be instantiated with a dependency on `SomeService`. - * - * - * ### Injecting a directive from the current element - * - * Directives can inject other directives declared on the current element. - * - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor(dependency: Dependency) { - * expect(dependency.id).toEqual(3); - * } - * } - * ``` - * This directive would be instantiated with `Dependency` declared at the same element, in this - * case - * `dependency="3"`. - * - * ### Injecting a directive from any ancestor elements - * - * Directives can inject other directives declared on any ancestor element (in the current Shadow - * DOM), i.e. on the current element, the - * parent element, or its parents. - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor(@Host() dependency: Dependency) { - * expect(dependency.id).toEqual(2); - * } - * } - * ``` - * - * `@Host` checks the current element, the parent, as well as its parents recursively. If - * `dependency="2"` didn't - * exist on the direct parent, this injection would - * have returned - * `dependency="1"`. - * - * - * ### Injecting a live collection of direct child directives - * - * - * A directive can also query for other child directives. Since parent directives are instantiated - * before child directives, a directive can't simply inject the list of child directives. Instead, - * the directive injects a {@link QueryList}, which updates its contents as children are added, - * removed, or moved by a directive that uses a {@link ViewContainerRef} such as a `ngFor`, an - * `ngIf`, or an `ngSwitch`. - * - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor(@Query(Dependency) dependencies:QueryList) { - * } - * } - * ``` - * - * This directive would be instantiated with a {@link QueryList} which contains `Dependency` 4 and - * `Dependency` 6. Here, `Dependency` 5 would not be included, because it is not a direct child. - * - * ### Injecting a live collection of descendant directives - * - * By passing the descendant flag to `@Query` above, we can include the children of the child - * elements. - * - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor(@Query(Dependency, {descendants: true}) dependencies:QueryList) { - * } - * } - * ``` - * - * This directive would be instantiated with a Query which would contain `Dependency` 4, 5 and 6. - * - * ### Optional injection - * - * The normal behavior of directives is to return an error when a specified dependency cannot be - * resolved. If you - * would like to inject `null` on unresolved dependency instead, you can annotate that dependency - * with `@Optional()`. - * This explicitly permits the author of a template to treat some of the surrounding directives as - * optional. - * - * ``` - * @Directive({ selector: '[my-directive]' }) - * class MyDirective { - * constructor(@Optional() dependency:Dependency) { - * } - * } - * ``` - * - * This directive would be instantiated with a `Dependency` directive found on the current - * element. - * If none can be - * found, the injector supplies `null` instead of throwing an error. - * - * ### Example - * - * Here we use a decorator directive to simply define basic tool-tip behavior. - * - * ``` - * @Directive({ - * selector: '[tooltip]', - * inputs: [ - * 'text: tooltip' - * ], - * host: { - * '(mouseenter)': 'onMouseEnter()', - * '(mouseleave)': 'onMouseLeave()' - * } - * }) - * class Tooltip{ - * text:string; - * overlay:Overlay; // NOT YET IMPLEMENTED - * overlayManager:OverlayManager; // NOT YET IMPLEMENTED - * - * constructor(overlayManager:OverlayManager) { - * this.overlay = overlay; - * } - * - * onMouseEnter() { - * // exact signature to be determined - * this.overlay = this.overlayManager.open(text, ...); - * } - * - * onMouseLeave() { - * this.overlay.close(); - * this.overlay = null; - * } - * } - * ``` - * In our HTML template, we can then add this behavior to a `
` or any other element with the - * `tooltip` selector, - * like so: - * - * ``` - *
- * ``` - * - * Directives can also control the instantiation, destruction, and positioning of inline template - * elements: - * - * A directive uses a {@link ViewContainerRef} to instantiate, insert, move, and destroy views at + * Directive decorator allows you to mark a class as an Angular directive and provide additional + * metadata that determines how the directive should be processed, instantiated and used at * runtime. - * The {@link ViewContainerRef} is created as a result of `