diff --git a/public/docs/js/latest/api/annotations/Ancestor-class.jade b/public/docs/js/latest/api/annotations/Ancestor-class.jade deleted file mode 100644 index 1397f550a4..0000000000 --- a/public/docs/js/latest/api/annotations/Ancestor-class.jade +++ /dev/null @@ -1,72 +0,0 @@ - -p.location-badge. - exported from angular2/annotations - defined in angular2/src/core/annotations_impl/visibility.js (line 105) - -:markdown - Specifies that an injector should retrieve a dependency from any ancestor element. - - An ancestor is any element between the parent element and shadow root. - - - ## Example - - Here is a simple directive that retrieves a dependency from an ancestor element. - - ``` - @Directive({ - selector: '[dependency]', - properties: { - 'id':'dependency' - } - }) - class Dependency { - id:string; - } - - - @Directive({ - selector: '[my-directive]' - }) - class Dependency { - constructor(@Ancestor() dependency:Dependency) { - expect(dependency.id).toEqual(2); - }; - } - ``` - - We use this with the following HTML template: - - ``` -
-
-
-
-
-
-
- ``` - - The `@Ancestor()` annotation in our constructor forces the injector to retrieve the dependency from the - nearest ancestor element: - - The current element `dependency="3"` is skipped because it is not an ancestor. - - Next parent has no directives `
` - - Next parent has the `Dependency` directive and so the dependency is satisfied. - - Angular injects `dependency=2`. - -.l-main-section - h2 Members - .l-sub-section - h3 constructor - - - pre.prettyprint - code. - constructor() - - :markdown - - - - diff --git a/public/docs/js/latest/api/annotations/Ancestor-var.jade b/public/docs/js/latest/api/annotations/Ancestor-var.jade index d1728743d2..20e5c70a94 100644 --- a/public/docs/js/latest/api/annotations/Ancestor-var.jade +++ b/public/docs/js/latest/api/annotations/Ancestor-var.jade @@ -3,6 +3,7 @@ h2 Ancestor variable p.location-badge. exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 52) :markdown diff --git a/public/docs/js/latest/api/annotations/Attribute-class.jade b/public/docs/js/latest/api/annotations/Attribute-class.jade deleted file mode 100644 index 68a8010a4b..0000000000 --- a/public/docs/js/latest/api/annotations/Attribute-class.jade +++ /dev/null @@ -1,70 +0,0 @@ - -p.location-badge. - exported from angular2/annotations - defined in angular2/src/core/annotations_impl/di.js (line 31) - -:markdown - Specifies that a constant attribute value should be injected. - - The directive can inject constant string literals of host element attributes. - - ## Example - - Suppose we have an `` element and want to know its `type`. - - ```html - - ``` - - A decorator can inject string literal `text` like so: - - ```javascript - @Directive({ - selector: `input' - }) - class InputDirective { - constructor(@Attribute('type') type) { - // type would be `text` in this example - } - } - ``` - -.l-main-section - h2 Members - .l-sub-section - h3 constructor - - - pre.prettyprint - code. - constructor(attributeName) - - :markdown - - - - - - .l-sub-section - h3 attributeName - - - :markdown - - - - - - - - .l-sub-section - h3 token - - - :markdown - - - - - - diff --git a/public/docs/js/latest/api/annotations/Attribute-var.jade b/public/docs/js/latest/api/annotations/Attribute-var.jade index 4b6462f6a3..69cc8b0141 100644 --- a/public/docs/js/latest/api/annotations/Attribute-var.jade +++ b/public/docs/js/latest/api/annotations/Attribute-var.jade @@ -3,6 +3,7 @@ h2 Attribute variable p.location-badge. exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 56) :markdown 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 cf6bcf58ff..0000000000 --- a/public/docs/js/latest/api/annotations/Component-class.jade +++ /dev/null @@ -1,191 +0,0 @@ - -p.location-badge. - exported from angular2/annotations - defined in angular2/src/core/annotations_impl/annotations.js (line 732) - -: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'; - } - } - ``` - - - 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, - injectables, - lifecycle, - changeDetection = DEFAULT, - compileChildren = true, - }:{ - selector:string, - properties:Object, - events:List, - hostListeners:any, - hostProperties:any, - injectables:List, - lifecycle:List, - changeDetection:string, - compileChildren:boolean - }={}) - - :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/Component-var.jade b/public/docs/js/latest/api/annotations/Component-var.jade index 4f4977737f..3b60ddc46a 100644 --- a/public/docs/js/latest/api/annotations/Component-var.jade +++ b/public/docs/js/latest/api/annotations/Component-var.jade @@ -3,8 +3,10 @@ h2 Component variable p.location-badge. exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 43) :markdown + diff --git a/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade b/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade index 38f123e16c..cb79d9b790 100644 --- a/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade +++ b/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade @@ -1,7 +1,7 @@ p.location-badge. exported from angular2/annotations - defined in angular2/src/core/annotations_impl/annotations.ts (line 776) + defined in angular2/src/core/annotations_impl/annotations.ts (line 812) :markdown Declare reusable UI building blocks for an application. @@ -40,54 +40,6 @@ p.location-badge. ``` - 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 @@ -96,23 +48,9 @@ p.location-badge. 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 - } = {}) + constructor({selector, properties, events, host, exportAs, appInjector, lifecycle, hostInjector, + viewInjector, changeDetection = DEFAULT, + compileChildren = true}?: ComponentArgs) :markdown @@ -121,6 +59,28 @@ p.location-badge. + .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 appInjector @@ -183,28 +143,6 @@ p.location-badge. - .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 diff --git a/public/docs/js/latest/api/annotations/ComponentArgs-interface.jade b/public/docs/js/latest/api/annotations/ComponentArgs-interface.jade new file mode 100644 index 0000000000..d5dc42b787 --- /dev/null +++ b/public/docs/js/latest/api/annotations/ComponentArgs-interface.jade @@ -0,0 +1,48 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations_impl/annotations.ts (line 981) + +:markdown + + +.l-main-section + h2 Members + .l-sub-section + h3 appInjector + + + :markdown + + + + + + + + + .l-sub-section + h3 viewInjector + + + :markdown + + + + + + + + + .l-sub-section + h3 changeDetection + + + :markdown + + + + + + + diff --git a/public/docs/js/latest/api/annotations/ComponentTypeDecorator-interface.jade b/public/docs/js/latest/api/annotations/ComponentTypeDecorator-interface.jade new file mode 100644 index 0000000000..2619941aa3 --- /dev/null +++ b/public/docs/js/latest/api/annotations/ComponentTypeDecorator-interface.jade @@ -0,0 +1,26 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 18) + +:markdown + + +.l-main-section + h2 Members + .l-sub-section + h3 View + + + pre.prettyprint + code. + View(obj: ViewArgs) + + :markdown + + + + + + + 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 a714392c37..0000000000 --- a/public/docs/js/latest/api/annotations/Directive-class.jade +++ /dev/null @@ -1,701 +0,0 @@ - -p.location-badge. - exported from angular2/annotations - defined in angular2/src/core/annotations_impl/annotations.js (line 371) - -: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` 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: 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(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. - - ``` - @Directive({ 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. - - ``` - @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 `