docs(api): updates for alpha-27 (plus a few interim additions pre-28)

This commit is contained in:
Naomi Black
2015-06-19 12:08:22 -07:00
parent 69c45dfa99
commit af8c852edb
254 changed files with 6658 additions and 6365 deletions
@@ -1,72 +0,0 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/visibility.js#L105">angular2/src/core/annotations_impl/visibility.js (line 105)</a>
: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:
```
<div dependency="1">
<div dependency="2">
<div>
<div dependency="3" my-directive></div>
</div>
</div>
</div>
```
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 `<div>`
- 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
@@ -3,6 +3,7 @@
h2 Ancestor <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L52-L52">angular2/src/core/annotations/decorators.ts (line 52)</a>
:markdown
@@ -1,70 +0,0 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/di.js#L31">angular2/src/core/annotations_impl/di.js (line 31)</a>
: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 `<input>` element and want to know its `type`.
```html
<input type="text">
```
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
@@ -3,6 +3,7 @@
h2 Attribute <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L56-L56">angular2/src/core/annotations/decorators.ts (line 56)</a>
:markdown
@@ -1,191 +0,0 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/annotations.js#L732">angular2/src/core/annotations_impl/annotations.js (line 732)</a>
: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 <a href='../di/Injector-class.html'><code>Injector</code></a> which is configured with the `injectables` for the <a href='Component-class.html'><code>Component</code></a>.
All template expressions and statements are then evaluated against the component instance.
For details on the `@View` annotation, see <a href='View-class.html'><code>View</code></a>.
## 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 <a href='../di/Injector-class.html'><code>Injector</code></a> injectable configuration.
See <a href='../di/Injector-class.html'><code>Injector</code></a> 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;
}
}
```
@@ -3,8 +3,10 @@
h2 Component <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L43-L43">angular2/src/core/annotations/decorators.ts (line 43)</a>
:markdown
@@ -1,7 +1,7 @@
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/annotations.ts#L776-L1009">angular2/src/core/annotations_impl/annotations.ts (line 776)</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations_impl/annotations.ts#L812-L981">angular2/src/core/annotations_impl/annotations.ts (line 812)</a>
: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&lt;string&gt;,
events?: List&lt;string&gt;,
hostListeners?: StringMap&lt;string, string&gt;,
hostProperties?: StringMap&lt;string, string&gt;,
hostAttributes?: StringMap&lt;string, string&gt;,
hostActions?: StringMap&lt;string, string&gt;,
appInjector?: List&lt;any&gt;,
lifecycle?: List&lt;LifecycleEvent&gt;,
hostInjector?: List&lt;any&gt;,
viewInjector?: List&lt;any&gt;,
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
@@ -0,0 +1,48 @@
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations_impl/annotations.ts#L981-L987">angular2/src/core/annotations_impl/annotations.ts (line 981)</a>
:markdown
.l-main-section
h2 Members
.l-sub-section
h3 appInjector
:markdown
.l-sub-section
h3 viewInjector
:markdown
.l-sub-section
h3 changeDetection
:markdown
@@ -0,0 +1,26 @@
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L18-L22">angular2/src/core/annotations/decorators.ts (line 18)</a>
:markdown
.l-main-section
h2 Members
.l-sub-section
h3 View
pre.prettyprint
code.
View(obj: ViewArgs)
:markdown
File diff suppressed because it is too large Load Diff
@@ -3,8 +3,10 @@
h2 Directive <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L44-L44">angular2/src/core/annotations/decorators.ts (line 44)</a>
:markdown
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,113 @@
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations_impl/annotations.ts#L801-L812">angular2/src/core/annotations_impl/annotations.ts (line 801)</a>
:markdown
.l-main-section
h2 Members
.l-sub-section
h3 selector
:markdown
.l-sub-section
h3 properties
:markdown
.l-sub-section
h3 events
:markdown
.l-sub-section
h3 host
:markdown
.l-sub-section
h3 lifecycle
:markdown
.l-sub-section
h3 hostInjector
:markdown
.l-sub-section
h3 exportAs
:markdown
.l-sub-section
h3 compileChildren
:markdown
@@ -0,0 +1,8 @@
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L16-L18">angular2/src/core/annotations/decorators.ts (line 16)</a>
:markdown
@@ -1,59 +0,0 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/visibility.js#L44">angular2/src/core/annotations_impl/visibility.js (line 44)</a>
:markdown
Specifies that an injector should retrieve a dependency from the direct parent.
## Example
Here is a simple directive that retrieves a dependency from its parent element.
```
@Directive({
selector: '[dependency]',
properties: {
'id':'dependency'
}
})
class Dependency {
id:string;
}
@Directive({
selector: '[my-directive]'
})
class Dependency {
constructor(@Parent() dependency:Dependency) {
expect(dependency.id).toEqual(1);
};
}
```
We use this with the following HTML template:
```
<div dependency="1">
<div dependency="2" my-directive></div>
</div>
```
The `@Parent()` annotation in our constructor forces the injector to retrieve the dependency from the
parent element (even thought the current element could resolve it): Angular injects `dependency=1`.
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor()
:markdown
@@ -3,6 +3,7 @@
h2 Parent <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L51-L51">angular2/src/core/annotations/decorators.ts (line 51)</a>
:markdown
@@ -1,37 +0,0 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/di.js#L55">angular2/src/core/annotations_impl/di.js (line 55)</a>
:markdown
Specifies that a <a href='../view/QueryList-class.html'><code>QueryList</code></a> should be injected.
See <a href='../view/QueryList-class.html'><code>QueryList</code></a> for usage and example.
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor(directive)
:markdown
.l-sub-section
h3 directive
:markdown
@@ -3,6 +3,7 @@
h2 Query <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L57-L57">angular2/src/core/annotations/decorators.ts (line 57)</a>
:markdown
@@ -3,6 +3,7 @@
h2 Self <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L50-L50">angular2/src/core/annotations/decorators.ts (line 50)</a>
:markdown
@@ -3,6 +3,7 @@
h2 Unbounded <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L53-L53">angular2/src/core/annotations/decorators.ts (line 53)</a>
:markdown
@@ -1,132 +0,0 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations_impl/view.js#L34">angular2/src/core/annotations_impl/view.js (line 34)</a>
:markdown
Declares the available HTML templates for an application.
Each angular component requires a single `@Component` and at least one `@View` annotation. The @View
annotation specifies the HTML template to use, and lists the directives that are active within the template.
When a component is instantiated, the template is loaded into the component's shadow root, and the
expressions and statements in the template are evaluated against the component.
For details on the `@Component` annotation, see <a href='Component-class.html'><code>Component</code></a>.
## Example
```
@Component({
selector: 'greet'
})
@View({
template: 'Hello {{name}}!',
directives: [GreetUser, Bold]
})
class Greet {
name: string;
constructor() {
this.name = 'World';
}
}
```
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor({
templateUrl,
template,
directives,
renderer
}: {
templateUrl: string,
template: string,
directives: List&lt;Type&gt;,
renderer: string
})
:markdown
.l-sub-section
h3 directives
:markdown
Specifies a list of directives that can be used within a template.
Directives must be listed explicitly to provide proper component encapsulation.
```javascript
@Component({
selector: 'my-component'
})
@View({
directives: [For]
template: '
<ul>
<li *for="item in items">{{item}}</li>
</ul>'
})
class MyComponent {
}
```
.l-sub-section
h3 renderer
:markdown
Specify a custom renderer for this View.
If this is set, neither `template`, `templateURL` nor `directives` are used.
.l-sub-section
h3 template
:markdown
Specifies an inline template for an angular component.
NOTE: either `templateUrl` or `template` should be used, but not both.
.l-sub-section
h3 templateUrl
:markdown
Specifies a template URL for an angular component.
NOTE: either `templateUrl` or `template` should be used, but not both.
@@ -3,8 +3,10 @@
h2 View <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L47-L47">angular2/src/core/annotations/decorators.ts (line 47)</a>
:markdown
@@ -0,0 +1,26 @@
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations/decorators.ts#L22-L24">angular2/src/core/annotations/decorators.ts (line 22)</a>
:markdown
.l-main-section
h2 Members
.l-sub-section
h3 View
pre.prettyprint
code.
View(obj: ViewArgs)
:markdown
@@ -12,6 +12,14 @@
"title" : "DirectiveAnnotation Class"
},
"ComponentArgs-interface" : {
"title" : "ComponentArgs Interface"
},
"DirectiveArgs-interface" : {
"title" : "DirectiveArgs Interface"
},
"onDestroy-const" : {
"title" : "onDestroy Const"
},
@@ -32,14 +40,26 @@
"title" : "onAllChangesDone Const"
},
"Component-var" : {
"title" : "Component Var"
"DirectiveTypeDecorator-interface" : {
"title" : "DirectiveTypeDecorator Interface"
},
"ComponentTypeDecorator-interface" : {
"title" : "ComponentTypeDecorator Interface"
},
"ViewTypeDecorator-interface" : {
"title" : "ViewTypeDecorator Interface"
},
"Directive-var" : {
"title" : "Directive Var"
},
"Component-var" : {
"title" : "Component Var"
},
"View-var" : {
"title" : "View Var"
},
@@ -1,5 +1,5 @@
p.location-badge.
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/annotations.ts#L1-L15">angular2/annotations.ts (line 1)</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/annotations.ts#L1-L15">angular2/annotations.ts (line 1)</a>
ul
for page, slug in public.docs[current.path[1]][current.path[2]][current.path[3]][current.path[4]]._data
@@ -3,9 +3,11 @@
h2 onAllChangesDone <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations_impl/annotations.ts#L1127-L1127">angular2/src/core/annotations_impl/annotations.ts (line 1127)</a>
:markdown
Notify a directive when the bindings of all its children have been changed.
Notify a directive when the bindings of all its children have been checked (whether they have
changed or not).
## Example:
@@ -1,24 +0,0 @@
.l-main-section
h2 onAllChangesDone <span class="type">variable</span>
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
:markdown
Notify a directive when the bindings of all its children have been changed.
## Example:
```
@Directive({
selector: '[class-set]',
lifecycle: [onAllChangesDone]
})
class ClassSet {
onAllChangesDone() {
}
}
```
@@ -3,6 +3,7 @@
h2 onChange <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations_impl/annotations.ts#L1057-L1057">angular2/src/core/annotations_impl/annotations.ts (line 1057)</a>
:markdown
Notify a directive when any of its bindings have changed.
@@ -1,40 +0,0 @@
.l-main-section
h2 onChange <span class="type">variable</span>
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
:markdown
Notify a directive when any of its bindings have changed.
This method is called right after the directive's bindings have been checked,
and before any of its children's bindings have been checked.
It is invoked only if at least one of the directive's bindings has changed.
## Example:
```
@Directive({
selector: '[class-set]',
properties: {
'propA': 'propA'
'propB': 'propB'
},
lifecycle: [onChange]
})
class ClassSet {
propA;
propB;
onChange(changes:{[idx: string, PropertyUpdate]}) {
// This will get called after any of the properties have been updated.
if (changes['propA']) {
// if propA was updated
}
if (changes['propA']) {
// if propB was updated
}
}
}
```
@@ -3,6 +3,7 @@
h2 onCheck <span class="type">variable</span>
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/3a0410a/modules/angular2/src/core/annotations_impl/annotations.ts#L1081-L1081">angular2/src/core/annotations_impl/annotations.ts (line 1081)</a>
:markdown
Notify a directive when it has been checked.

Some files were not shown because too many files have changed in this diff Show More