diff --git a/public/docs/js/latest/api/annotations/component-class.jade b/public/docs/js/latest/api/annotations/component-class.jade deleted file mode 100644 index 45d7ff5492..0000000000 --- a/public/docs/js/latest/api/annotations/component-class.jade +++ /dev/null @@ -1,140 +0,0 @@ - -p.location-badge. - exported from angular2/annotations - defined in angular2/src/core/annotations/annotations.js (line 521) - -:markdown - Declare reusable UI building blocks for an application. - - Each Angular component requires a single `@Component` and at least one `@View` annotation. The `@Component` - annotation specifies when a component is instantiated, and which properties and hostListeners it binds to. - - When a component is instantiated, Angular - - creates a shadow DOM for the component. - - loads the selected template into the shadow DOM. - - creates a child Injector which is configured with the `injectables` for the Component. - - All template expressions and statements are then evaluated against the component instance. - - For details on the `@View` annotation, see View. - - ## Example - - ``` - @Component({ - selector: 'greet' - }) - @View({ - template: 'Hello {{name}}!' - }) - class Greet { - name: string; - - constructor() { - this.name = 'World'; - } - } - ``` - -.l-main-section - h2 Members - .l-sub-section - h3 constructor - - - pre.prettyprint - code. - constructor({ - selector, - properties, - events, - hostListeners, - injectables, - lifecycle, - changeDetection = DEFAULT - }:{ - selector:string, - properties:Object, - events:List, - hostListeners:Object, - injectables:List, - lifecycle:List, - changeDetection:string - }={}) - - :markdown - - - - - - .l-sub-section - h3 changeDetection - - - :markdown - Defines the used change detection strategy. - - When a component is instantiated, Angular creates a change detector, which is responsible for propagating - the component's bindings. - - The `changeDetection` property defines, whether the change detection will be checked every time or only when the component - tells it to do so. - - - - - - .l-sub-section - h3 injectables - - - :markdown - Defines the set of injectable objects that are visible to a Component and its children. - - The `injectables` defined in the Component annotation allow you to configure a set of bindings for the component's - injector. - - When a component is instantiated, Angular creates a new child Injector, which is configured with the bindings in - the Component `injectables` annotation. The injectable objects then become available for injection to the component - itself and any of the directives in the component's template, i.e. they are not available to the directives which - are children in the component's light DOM. - - - The syntax for configuring the `injectables` injectable is identical to Injector injectable configuration. - See Injector for additional detail. - - - ## Simple Example - - Here is an example of a class that can be injected: - - ``` - class Greeter { - greet(name:string) { - return 'Hello ' + name + '!'; - } - } - - @Component({ - selector: 'greet', - injectables: [ - Greeter - ] - }) - @View({ - template: `{{greeter.greet('world')}}!`, - directives: Child - }) - class HelloWorld { - greeter:Greeter; - - constructor(greeter:Greeter) { - this.greeter = greeter; - } - } - ``` - - - - diff --git a/public/docs/js/latest/api/annotations/directive-class.jade b/public/docs/js/latest/api/annotations/directive-class.jade deleted file mode 100644 index 7e6bf6ccce..0000000000 --- a/public/docs/js/latest/api/annotations/directive-class.jade +++ /dev/null @@ -1,518 +0,0 @@ - -p.location-badge. - exported from angular2/annotations - defined in angular2/src/core/annotations/annotations.js (line 240) - -:markdown - Directives allow you to attach behavior to elements in the DOM. - - Directive is an abstract concept, instead use concrete directives: Component, DynamicComponent, Decorator - or Viewport. - - 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 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` has its own Injector, and they follow the same parent-child hierarchy - as the components in the DOM. - - *Element Injectors*: Each component 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 View: - - 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 - - `@Ancestor() directive:DirectiveType`: any directive that matches the type between the current element and the - Shadow DOM root. Current element is not included in the resolution, therefore even if it could resolve it, it will - be ignored. - - `@Parent() directive:DirectiveType`: any directive that matches the type on a direct parent element only. - - `@Children query:Query`: A live collection of direct child directives (will be implemented in later release). - - `@Descendants query:Query`: A live collection of any child directives (will be implemented in later relaese). - - To inject element-specific special objects, declare the constructor parameter as: - - `element: NgElement` to obtain a DOM element (DEPRECATED: replacement coming) - - `viewContainer: ViewContainer` to control child template instantiation, for Viewport 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: - - ``` -
-
-
-
-
-
-
-
-
-
- ``` - - With the following `dependency` decorator and `SomeService` injectable class. - - ``` - @Injectable() - class SomeService { - } - - @Decorator({ - selector: '[dependency]', - properties: { - 'id':'dependency' - } - }) - class Dependency { - id:string; - } - ``` - - Let's step through the different ways in which `MyDirective` could be declared... - - - ### No injection - - Here the constructor is declared with no arguments, therefore nothing is injected into `MyDirective`. - - ``` - @Decorator({ 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. - ``` - @Decorator({ 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. - - ``` - @Decorator({ 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 a direct parent element - - Directives can inject other directives declared on a direct parent element. By definition, a directive with a - `@Parent` annotation does not attempt to resolve dependencies for the current element, even if this would satisfy - the dependency. - - ``` - @Decorator({ selector: '[my-directive]' }) - class MyDirective { - constructor(@Parent() dependency: Dependency) { - expect(dependency.id).toEqual(2); - } - } - ``` - This directive would be instantiated with `Dependency` declared at the parent element, in this case `dependency="2"`. - - - ### 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 - parent element and its parents. By definition, a directive with an `@Ancestor` annotation does not attempt to - resolve dependencies for the current element, even if this would satisfy the dependency. - - ``` - @Decorator({ selector: '[my-directive]' }) - class MyDirective { - constructor(@Ancestor() dependency: Dependency) { - expect(dependency.id).toEqual(2); - } - } - ``` - - Unlike the `@Parent` which only checks the parent, `@Ancestor` checks 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 QueryList, which updates its contents as children are added, removed, or moved by any - Viewport directive such as a `for`, an `if`, or a `switch`. - - ``` - @Decorator({ selector: '[my-directive]' }) - class MyDirective { - constructor(@Query(Marker) dependencies:QueryList) { - } - } - ``` - - This directive would be instantiated with a QueryList which contains `Dependency` 4 and 6. Here, `Dependency` - 5 would not be included, because it is not a direct child. - - ### Injecting a live collection of descendant directives - - Note: This is will be implemented in later release. () - - Similar to `@Children` above, but also includes the children of the child elements. - - ``` - @Decorator({ selector: '[my-directive]' }) - class MyDirective { - constructor(@QueryDescendents(Marker) 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. - - ``` - @Decorator({ 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. - -.l-main-section - h2 Members - .l-sub-section - h3 constructor - - - pre.prettyprint - code. - constructor({ - selector, - properties, - events, - hostListeners, - lifecycle - }:{ - selector:string, - properties:any, - events:List, - hostListeners: any, - lifecycle:List - }={}) - - :markdown - - - - - - .l-sub-section - h3 events - - - :markdown - Enumerates the set of emitted events. - - ## Syntax - - ``` - @Component({ - events: ['statusChange'] - }) - class TaskComponent { - statusChange:EventEmitter; - - constructor() { - this.statusChange = new EventEmitter(); - } - - onComplete() { - this.statusChange.next('completed'); - } - } - ``` - - - - - - .l-sub-section - h3 hasLifecycleHook - - - pre.prettyprint - code. - hasLifecycleHook(hook:string) - - :markdown - Returns true if a directive participates in a given `LifecycleEvent`. - - See onChange, onDestroy, onAllChangesDone for details. - - - - - - .l-sub-section - h3 hostListeners - - - :markdown - Specifies which DOM hostListeners a directive listens to. - - The `hostListeners` property defines 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. - If the evalutation of the statement returns `false`, then `preventDefault`is applied on the DOM event. - - 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) - - - ## Syntax - - ``` - @Directive({ - hostListeners: { - 'event1': 'onMethod1(arguments)', - 'target:event2': 'onMethod2(arguments)', - ... - } - } - ``` - - ## Basic Event Binding: - - Suppose you want to write a directive that triggers on `change` events in the DOM and on `resize` events in window. - You would define the event binding as follows: - - ``` - @Decorator({ - selector: 'input', - hostListeners: { - 'change': 'onChange($event)', - 'window:resize': 'onResize($event)' - } - }) - class InputDecorator { - onChange(event:Event) { - } - onResize(event:Event) { - } - } - ``` - - Here the `onChange` method of `InputDecorator` is invoked whenever the DOM element fires the 'change' event. - - - - - - .l-sub-section - h3 lifecycle - - - :markdown - Specifies a set of lifecycle hostListeners in which the directive participates. - - See onChange, onDestroy, onAllChangesDone for details. - - - - - - .l-sub-section - h3 properties - - - :markdown - Enumerates the set of properties that accept data binding for a directive. - - The `properties` property defines a set of `directiveProperty` to `bindingProperty` - key-value pairs: - - - `directiveProperty` specifies the component property where the value is written. - - `bindingProperty` specifies the DOM property where the value is read from. - - You can include a Pipe when specifying a `bindingProperty` to allow for data transformation and structural - change detection of the value. These pipes will be evaluated in the context of this component. - - - ## Syntax - - ``` - @Directive({ - properties: { - 'directiveProperty1': 'bindingProperty1', - 'directiveProperty2': 'bindingProperty2 | pipe1 | ...', - ... - } - } - ``` - - - ## Basic Property Binding - - We can easily build a simple `Tooltip` directive that exposes a `tooltip` property, which can be used in templates - with standard Angular syntax. For example: - - ``` - @Decorator({ - selector: '[tooltip]', - properties: { - 'text': 'tooltip' - } - }) - class Tooltip { - set text(text) { - // This will get called every time the 'tooltip' binding changes with the new value. - } - } - ``` - - We can then bind to the `tooltip' property as either an expression (`someExpression`) or as a string literal, as - shown in the HTML template below: - - ```html -
...
-
...
- ``` - - Whenever the `someExpression` expression changes, the `properties` declaration instructs - Angular to update the `Tooltip`'s `text` property. - - - - ## Bindings With Pipes - - You can also use pipes when writing binding definitions for a directive. - - For example, we could write a binding that updates the directive on structural changes, rather than on reference - changes, as normally occurs in change detection. - - See Pipe and keyValDiff documentation for more details. - - ``` - @Decorator({ - selector: '[class-set]', - properties: { - 'classChanges': 'classSet | keyValDiff' - } - }) - class ClassSet { - set classChanges(changes:KeyValueChanges) { - // This will get called every time the `class-set` expressions changes its structure. - } - } - ``` - - The template that this directive is used in may also contain its own pipes. For example: - - ```html -
- ``` - - In this case, the two pipes compose as if they were inlined: `someExpression | somePipe | keyValDiff`. - - - - - - .l-sub-section - h3 selector - - - :markdown - The CSS selector that triggers the instantiation of a directive. - - Angular only allows directives to trigger on CSS selectors that do not cross element boundaries. - - `selector` may be declared as one of the following: - - - `element-name`: select by element name. - - `.class`: select by class name. - - `[attribute]`: select by attribute name. - - `[attribute=value]`: select by attribute name and value. - - `:not(sub_selector)`: select only if the element does not match the `sub_selector`. - - `selector1, selector2`: select if either `selector1` or `selector2` matches. - - - - - Suppose we have a directive with an `input[type=text]` selector. - - And the following HTML: - - ```html -
- - - - ``` - - The directive would only be instantiated on the `` element. - - - -