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..4947c95245 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Attribute-var.jade @@ -0,0 +1,12 @@ + +.l-main-section + h2 Attribute variable + p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 365) + + :markdown + Attribute factory function. + + + diff --git a/public/docs/js/latest/api/annotations/AttributeAnnotation-class.jade b/public/docs/js/latest/api/annotations/AttributeAnnotation-class.jade new file mode 100644 index 0000000000..282778c5df --- /dev/null +++ b/public/docs/js/latest/api/annotations/AttributeAnnotation-class.jade @@ -0,0 +1,91 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations_impl/di.ts (line 3) + +: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: string) + + :markdown + + + + + + + .l-sub-section + h3 attributeName + + + :markdown + + + + + + + + + .l-sub-section + h3 token + + + :markdown + + + + + + + + + .l-sub-section + h3 toString + + + pre.prettyprint + code. + toString() + + :markdown + + + + + + + diff --git a/public/docs/js/latest/api/annotations/AttributeFactory-interface.jade b/public/docs/js/latest/api/annotations/AttributeFactory-interface.jade new file mode 100644 index 0000000000..edc32790d8 --- /dev/null +++ b/public/docs/js/latest/api/annotations/AttributeFactory-interface.jade @@ -0,0 +1,52 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 241) + +:markdown + Attribute factory for creating annotations, decorators or DSL. + + ## Example as TypeScript Decorator + + ``` + import {Attribute, Component, View} from "angular2/angular2"; + + @Component({...}) + @View({...}) + class MyComponent { + constructor(@Attribute('title') title: string) { + ... + } + } + ``` + + ## Example as ES5 DSL + + ``` + var MyComponent = ng + .Component({...}) + .View({...}) + .Class({ + constructor: [new ng.Attribute('title'), function(title) { + ... + }] + }) + ``` + + ## Example as ES5 annotation + + ``` + var MyComponent = function(title) { + ... + }; + + MyComponent.annotations = [ + new ng.Component({...}) + new ng.View({...}) + ] + MyComponent.parameters = [ + [new ng.Attribute('title')] + ] + ``` + + diff --git a/public/docs/js/latest/api/annotations/Class-function.jade b/public/docs/js/latest/api/annotations/Class-function.jade new file mode 100644 index 0000000000..a1f678df18 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Class-function.jade @@ -0,0 +1,98 @@ + +.l-main-section + h2(class="function export") Class + + + pre.prettyprint + code. + Class(clsDef: ClassDefinition) : Type + + + p.location-badge. + exported from angular2/annotations + defined in angular2/src/util/decorators.ts (line 124) + + :markdown + Provides a way for expressing ES6 classes with parameter annotations in ES5. + + ## Basic Example + + ``` + var Greeter = ng.Class({ + constructor: function(name) { + this.name = name; + }, + + greet: function() { + alert('Hello ' + this.name + '!'); + } + }); + ``` + + is equivalent to ES6: + + ``` + class Greeter { + constructor(name) { + this.name = name; + } + + greet() { + alert('Hello ' + this.name + '!'); + } + } + ``` + + or equivalent to ES5: + + ``` + var Greeter = function (name) { + this.name = name; + } + + Greeter.prototype.greet = function () { + alert('Hello ' + this.name + '!'); + } + ``` + + ## Example with parameter annotations + + ``` + var MyService = neg.Class({ + constructor: [String, [new Query(), QueryList], function(name, queryList) { + ... + }]; + }); + ``` + + is equivalent to ES6: + + ``` + class MyService { + constructor(name: string, @Query() queryList: QueryList) { + ... + } + } + ``` + + ## Example with inheritance + + ``` + var Shape = ng.Class({ + constructor: (color) { + this.color = color; + } + }); + + var Square = ng.Class({ + extends: Shape, + constructor: function(color, size) { + Shape.call(this, color); + this.size = size; + } + }); + ``` + + + + diff --git a/public/docs/js/latest/api/annotations/ClassDefinition-interface.jade b/public/docs/js/latest/api/annotations/ClassDefinition-interface.jade new file mode 100644 index 0000000000..bc877cdb6b --- /dev/null +++ b/public/docs/js/latest/api/annotations/ClassDefinition-interface.jade @@ -0,0 +1,44 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/util/decorators.ts (line 1) + +:markdown + Declares the interface to be used with Class. + + +.l-main-section + h2 Members + .l-sub-section + h3 extends? + + + :markdown + + Optional argument for specifying the superclass. + + + + + + + + .l-sub-section + h3 constructor + + + :markdown + + Required constructor function for a class. + + The function may be optionally wrapped in an `Array`, in which case additional parameter + annotations may be specified. + The number of arguments and the number of parameter annotations must match. + + See Class for example of usage. + + + + + + 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..c16421b4f5 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Component-var.jade @@ -0,0 +1,12 @@ + +.l-main-section + h2 Component variable + p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 349) + + :markdown + Component factory function. + + + 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..4b4f0b529e --- /dev/null +++ b/public/docs/js/latest/api/annotations/ComponentAnnotation-class.jade @@ -0,0 +1,142 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations_impl/annotations.ts (line 782) + +: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 all the injectable objects configured with `hostInjector` and `viewInjector`. + + 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, host, exportAs, lifecycle, hostInjector, viewInjector, + changeDetection = DEFAULT, compileChildren = true}?: { + selector?: string, + properties?: List<string>, + events?: List<string>, + host?: StringMap<string, string>, + lifecycle?: List<LifecycleEvent>, + hostInjector?: List<any>, + exportAs?: string, + compileChildren?: boolean, + viewInjector?: List<any>, + 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 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/ComponentDecorator-interface.jade b/public/docs/js/latest/api/annotations/ComponentDecorator-interface.jade new file mode 100644 index 0000000000..1bd92ce070 --- /dev/null +++ b/public/docs/js/latest/api/annotations/ComponentDecorator-interface.jade @@ -0,0 +1,37 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 18) + +:markdown + Interface for the Component decorator function. + + See ComponentFactory. + + +.l-main-section + h2 Members + .l-sub-section + h3 View + + + pre.prettyprint + code. + View(obj: { + templateUrl?: string, + template?: string, + directives?: List<Type | any | List<any>>, + renderer?: string, + styles?: List<string>, + styleUrls?: List<string>, + }) + + :markdown + + Chain View annotation. + + + + + + diff --git a/public/docs/js/latest/api/annotations/ComponentFactory-interface.jade b/public/docs/js/latest/api/annotations/ComponentFactory-interface.jade new file mode 100644 index 0000000000..7a901782e7 --- /dev/null +++ b/public/docs/js/latest/api/annotations/ComponentFactory-interface.jade @@ -0,0 +1,49 @@ + +p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 109) + +:markdown + ComponentAnnotation factory for creating annotations, decorators or DSL. + + ## Example as TypeScript Decorator + + ``` + import {Component, View} from "angular2/angular2"; + + @Component({...}) + @View({...}) + class MyComponent { + constructor() { + ... + } + } + ``` + + ## Example as ES5 DSL + + ``` + var MyComponent = ng + .Component({...}) + .View({...}) + .Class({ + constructor: function() { + ... + } + }) + ``` + + ## Example as ES5 annotation + + ``` + var MyComponent = function() { + ... + }; + + MyComponent.annotations = [ + new ng.Component({...}) + new ng.View({...}) + ] + ``` + + 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..7fb90d3952 --- /dev/null +++ b/public/docs/js/latest/api/annotations/Directive-var.jade @@ -0,0 +1,12 @@ + +.l-main-section + h2 Directive variable + p.location-badge. + exported from angular2/annotations + defined in angular2/src/core/annotations/decorators.ts (line 354) + + :markdown + Directive factory function. + + + 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..f426d78c11 --- /dev/null +++ b/public/docs/js/latest/api/annotations/DirectiveAnnotation-class.jade @@ -0,0 +1,853 @@ + +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. + - `@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 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); + } + } + ``` + + `@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 `ng-for`, an + `ng-if`, or an `ng-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 + + 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]', + 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 `