diff --git a/public/docs/js/latest/api/annotations/Ancestor-var.jade b/public/docs/js/latest/api/annotations/Ancestor-var.jade new file mode 100644 index 0000000000..d1728743d2 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Ancestor-var.jade @@ -0,0 +1,10 @@ + +.l-main-section + h2 Ancestor variable + p.location-badge. + exported from angular2/annotations + + :markdown + + + diff --git a/public/docs/js/latest/api/annotations/Attribute-var.jade b/public/docs/js/latest/api/annotations/Attribute-var.jade new file mode 100644 index 0000000000..4b6462f6a3 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Attribute-var.jade @@ -0,0 +1,10 @@ + +.l-main-section + h2 Attribute variable + p.location-badge. + exported from angular2/annotations + + :markdown + + + diff --git a/public/docs/js/latest/api/annotations/Component-var.jade b/public/docs/js/latest/api/annotations/Component-var.jade new file mode 100644 index 0000000000..4f4977737f --- /dev/null +++ b/public/docs/js/latest/api/annotations/Component-var.jade @@ -0,0 +1,10 @@ + +.l-main-section + h2 Component variable + p.location-badge. + exported from angular2/annotations + + :markdown + + + diff --git a/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade b/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade new file mode 100644 index 0000000000..a667a0539a --- /dev/null +++ b/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade @@ -0,0 +1,257 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations_impl/annotations.ts (line 778) + +: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 `appInjector` 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'; + } + } + ``` + + + Dynamically loading a component at runtime: + + Regular Angular components are statically resolved. Dynamic components allows to resolve a + component at runtime + instead by providing a placeholder into which a regular Angular component can be dynamically + loaded. Once loaded, + the dynamically-loaded component becomes permanent and cannot be changed. + Dynamic components are declared just like components, but without a `@View` annotation. + + + ## Example + + Here we have `DynamicComp` which acts as the placeholder for `HelloCmp`. At runtime, the dynamic + component + `DynamicComp` requests loading of the `HelloCmp` component. + + There is nothing special about `HelloCmp`, which is a regular Angular component. It can also be + used in other static + locations. + + ``` + @Component({ + selector: 'dynamic-comp' + }) + class DynamicComp { + helloCmp:HelloCmp; + constructor(loader:DynamicComponentLoader, location:ElementRef) { + loader.load(HelloCmp, location).then((helloCmp) => { + this.helloCmp = helloCmp; + }); + } + } + + @Component({ + selector: 'hello-cmp' + }) + @View({ + template: "{{greeting}}" + }) + class HelloCmp { + greeting:string; + constructor() { + this.greeting = "hello"; + } + } + ``` + + +.l-main-section + h2 Members + .l-sub-section + h3 constructor + + + pre.prettyprint + code. + constructor({selector, properties, events, hostListeners, hostProperties, hostAttributes, + hostActions, appInjector, lifecycle, hostInjector, viewInjector, + changeDetection = DEFAULT, compileChildren = true}: { + selector?: string, + properties?: List<string>, + events?: List<string>, + hostListeners?: StringMap<string, string>, + hostProperties?: StringMap<string, string>, + hostAttributes?: StringMap<string, string>, + hostActions?: StringMap<string, string>, + appInjector?: List<any>, + lifecycle?: List<LifecycleEvent>, + hostInjector?: List<any>, + viewInjector?: List<any>, + changeDetection?: string, + compileChildren?: boolean + } = {}) + + :markdown + + + + + + + .l-sub-section + h3 appInjector + + + :markdown + + Defines the set of injectable objects that are visible to a Component and its children. + + The `appInjector` 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 `appInjector` 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 `appInjector` 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', + appInjector: [ + Greeter + ] + }) + @View({ + template: `{{greeter.greet('world')}}!`, + directives: [Child] + }) + class HelloWorld { + greeter:Greeter; + + constructor(greeter:Greeter) { + this.greeter = greeter; + } + } + ``` + + + + + + + + .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 viewInjector + + + :markdown + + Defines the set of injectable objects that are visible to its view dom children. + + ## Simple Example + + Here is an example of a class that can be injected: + + ``` + class Greeter { + greet(name:string) { + return 'Hello ' + name + '!'; + } + } + + @Directive({ + selector: 'needs-greeter' + }) + class NeedsGreeter { + greeter:Greeter; + + constructor(greeter:Greeter) { + this.greeter = greeter; + } + } + + @Component({ + selector: 'greet', + viewInjector: [ + Greeter + ] + }) + @View({ + template: ``, + directives: [NeedsGreeter] + }) + class HelloWorld { + } + + ``` + + + + + + diff --git a/public/docs/js/latest/api/annotations/Directive-var.jade b/public/docs/js/latest/api/annotations/Directive-var.jade new file mode 100644 index 0000000000..2126d4f288 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Directive-var.jade @@ -0,0 +1,10 @@ + +.l-main-section + h2 Directive variable + p.location-badge. + exported from angular2/annotations + + :markdown + + + diff --git a/public/docs/js/latest/api/annotations/DirectiveAnnotation-class.jade b/public/docs/js/latest/api/annotations/DirectiveAnnotation-class.jade new file mode 100644 index 0000000000..a01c14c16e --- /dev/null +++ b/public/docs/js/latest/api/annotations/DirectiveAnnotation-class.jade @@ -0,0 +1,858 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations_impl/annotations.ts (line 4) + +:markdown + Directives allow you to attach behavior to elements in the DOM. + + Directives with an embedded view are called Components. + + 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 instance has its own 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 + 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. + - `@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 + 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: + + ``` +
+
+
+
+
+
+
+
+
+
+ ``` + + With the following `dependency` decorator and `SomeService` injectable class. + + ``` + @Injectable() + class SomeService { + } + + @Directive({ + 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`. + + ``` + @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 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. + + ``` + @Directive({ 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. + + ``` + @Directive({ 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 a directive + that uses a ViewContainerRef such as a `for`, an `if`, or a `switch`. + + ``` + @Directive({ selector: '[my-directive]' }) + class MyDirective { + constructor(@Query(Dependency) 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 `@Query` above, but also includes the children of the child elements. + + ``` + @Directive({ selector: '[my-directive]' }) + class MyDirective { + constructor(@QueryDescendents(Dependency) 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]', + properties: [ + 'text: tooltip' + ], + hostListeners: { + 'onmouseenter': 'onMouseEnter()', + 'onmouseleave': '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 ViewContainerRef to instantiate, insert, move, and destroy views at + runtime. + The ViewContainerRef is created as a result of `