From 3aadd7b76b572727a0ac7fae99be9db2b1f03350 Mon Sep 17 00:00:00 2001 From: Alex Wolfe Date: Thu, 23 Apr 2015 08:43:09 -0700 Subject: [PATCH] add files properly --- .../api/annotations/Component-class.jade | 140 +++++ .../api/annotations/Directive-class.jade | 518 ++++++++++++++++++ 2 files changed, 658 insertions(+) create mode 100644 public/docs/js/latest/api/annotations/Component-class.jade create mode 100644 public/docs/js/latest/api/annotations/Directive-class.jade diff --git a/public/docs/js/latest/api/annotations/Component-class.jade b/public/docs/js/latest/api/annotations/Component-class.jade new file mode 100644 index 0000000000..45d7ff5492 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Component-class.jade @@ -0,0 +1,140 @@ + +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 new file mode 100644 index 0000000000..23ded95a76 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Directive-class.jade @@ -0,0 +1,518 @@ + +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. + + + +