702 lines
21 KiB
Plaintext
702 lines
21 KiB
Plaintext
|
|
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#L371">angular2/src/core/annotations_impl/annotations.js (line 371)</a>
|
|
|
|
:markdown
|
|
Directives allow you to attach behavior to elements in the DOM.
|
|
|
|
<a href='Directive-class.html'><code>Directive</code></a>s with an embedded view are called <a href='Component-class.html'><code>Component</code></a>s.
|
|
|
|
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 <a href='../di/Injector-class.html'><code>Injector</code></a> 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 <a href='../di/Injector-class.html'><code>Injector</code></a>, 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 <a href='View-class.html'><code>View</code></a>:
|
|
|
|
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<DirectiveType>`: A live collection of direct child directives (will be implemented in later release).
|
|
- `@Descendants query:Query<DirectiveType>`: 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 <a href='Directive-class.html'><code>Directive</code></a> 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:
|
|
|
|
```
|
|
<div dependency="1">
|
|
<div dependency="2">
|
|
<div dependency="3" my-directive>
|
|
<div dependency="4">
|
|
<div dependency="5"></div>
|
|
</div>
|
|
<div dependency="6"></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
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 <a href='../view/QueryList-class.html'><code>QueryList</code></a>, which updates its contents as children are added, removed, or moved by a directive
|
|
that uses a <a href='../core/ViewContainerRef-class.html'><code>ViewContainerRef</code></a> such as a `for`, an `if`, or a `switch`.
|
|
|
|
```
|
|
@Directive({ selector: '[my-directive]' })
|
|
class MyDirective {
|
|
constructor(@Query(Marker) dependencies:QueryList<Maker>) {
|
|
}
|
|
}
|
|
```
|
|
|
|
This directive would be instantiated with a <a href='../view/QueryList-class.html'><code>QueryList</code></a> 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<Maker>) {
|
|
}
|
|
}
|
|
```
|
|
|
|
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 `<div>` or any other element with the `tooltip` selector,
|
|
like so:
|
|
|
|
```
|
|
<div tooltip="some text here"></div>
|
|
```
|
|
|
|
Directives can also control the instantiation, destruction, and positioning of inline template elements:
|
|
|
|
A directive uses a <a href='../core/ViewContainerRef-class.html'><code>ViewContainerRef</code></a> to instantiate, insert, move, and destroy views at runtime.
|
|
The <a href='../core/ViewContainerRef-class.html'><code>ViewContainerRef</code></a> is created as a result of `<template>` element, and represents a location in the current view
|
|
where these actions are performed.
|
|
|
|
Views are always created as children of the current <a href='View-class.html'><code>View</code></a>, and as siblings of the `<template>` element. Thus a
|
|
directive in a child view cannot inject the directive that created it.
|
|
|
|
Since directives that create views via ViewContainers are common in Angular, and using the full `<template>` element syntax is wordy, Angular
|
|
also supports a shorthand notation: `<li *foo="bar">` and `<li template="foo: bar">` are equivalent.
|
|
|
|
Thus,
|
|
|
|
```
|
|
<ul>
|
|
<li *foo="bar" title="text"></li>
|
|
</ul>
|
|
```
|
|
|
|
Expands in use to:
|
|
|
|
```
|
|
<ul>
|
|
<template [foo]="bar">
|
|
<li title="text"></li>
|
|
</template>
|
|
</ul>
|
|
```
|
|
|
|
Notice that although the shorthand places `*foo="bar"` within the `<li>` element, the binding for the directive
|
|
controller is correctly instantiated on the `<template>` element rather than the `<li>` element.
|
|
|
|
|
|
## Example
|
|
|
|
Let's suppose we want to implement the `unless` behavior, to conditionally include a template.
|
|
|
|
Here is a simple directive that triggers on an `unless` selector:
|
|
|
|
```
|
|
@Directive({
|
|
selector: '[unless]',
|
|
properties: {
|
|
'unless': 'unless'
|
|
}
|
|
})
|
|
export class Unless {
|
|
viewContainer: ViewContainerRef;
|
|
protoViewRef: ProtoViewRef;
|
|
prevCondition: boolean;
|
|
|
|
constructor(viewContainer: ViewContainerRef, protoViewRef: ProtoViewRef) {
|
|
this.viewContainer = viewContainer;
|
|
this.protoViewRef = protoViewRef;
|
|
this.prevCondition = null;
|
|
}
|
|
|
|
set unless(newCondition) {
|
|
if (newCondition && (isBlank(this.prevCondition) || !this.prevCondition)) {
|
|
this.prevCondition = true;
|
|
this.viewContainer.clear();
|
|
} else if (!newCondition && (isBlank(this.prevCondition) || this.prevCondition)) {
|
|
this.prevCondition = false;
|
|
this.viewContainer.create(this.protoViewRef);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
We can then use this `unless` selector in a template:
|
|
```
|
|
<ul>
|
|
<li *unless="expr"></li>
|
|
</ul>
|
|
```
|
|
|
|
Once the directive instantiates the child view, the shorthand notation for the template expands and the result is:
|
|
|
|
```
|
|
<ul>
|
|
<template [unless]="exp">
|
|
<li></li>
|
|
</template>
|
|
<li></li>
|
|
</ul>
|
|
```
|
|
|
|
Note also that although the `<li></li>` template still exists inside the `<template></template>`, the instantiated
|
|
view occurs on the second `<li></li>` which is a sibling to the `<template>` element.
|
|
|
|
.l-main-section
|
|
h2 Members
|
|
.l-sub-section
|
|
h3 constructor
|
|
|
|
|
|
pre.prettyprint
|
|
code.
|
|
constructor({
|
|
selector,
|
|
properties,
|
|
events,
|
|
hostListeners,
|
|
hostProperties,
|
|
lifecycle,
|
|
compileChildren = true,
|
|
}:{
|
|
selector:string,
|
|
properties:any,
|
|
events:List,
|
|
hostListeners: any,
|
|
hostProperties: any,
|
|
lifecycle:List,
|
|
compileChildren:boolean
|
|
}={})
|
|
|
|
:markdown
|
|
|
|
|
|
|
|
|
|
|
|
.l-sub-section
|
|
h3 compileChildren
|
|
|
|
|
|
:markdown
|
|
|
|
If set to true the compiler does not compile the children of this directive.
|
|
|
|
|
|
|
|
|
|
|
|
.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 <a href='onChange-var.html'><code>onChange</code></a>, <a href='onDestroy-var.html'><code>onDestroy</code></a>, <a href='onAllChangesDone-var.html'><code>onAllChangesDone</code></a> 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:
|
|
|
|
```
|
|
@Directive({
|
|
selector: 'input',
|
|
hostListeners: {
|
|
'change': 'onChange($event)',
|
|
'window:resize': 'onResize($event)'
|
|
}
|
|
})
|
|
class InputDirective {
|
|
onChange(event:Event) {
|
|
}
|
|
onResize(event:Event) {
|
|
}
|
|
}
|
|
```
|
|
|
|
Here the `onChange` method of `InputDirective` is invoked whenever the DOM element fires the 'change' event.
|
|
|
|
|
|
|
|
|
|
|
|
.l-sub-section
|
|
h3 hostProperties
|
|
|
|
|
|
:markdown
|
|
|
|
Specifies which DOM properties a directives updates.
|
|
|
|
## Syntax
|
|
|
|
```
|
|
@Directive({
|
|
selector: 'input',
|
|
hostProperties: {
|
|
'value': 'value'
|
|
}
|
|
})
|
|
class InputDirective {
|
|
value:string;
|
|
}
|
|
|
|
In this example every time the value property of the decorator changes, Angular will update the value property of
|
|
the host element.
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
.l-sub-section
|
|
h3 lifecycle
|
|
|
|
|
|
:markdown
|
|
|
|
Specifies a set of lifecycle hostListeners in which the directive participates.
|
|
|
|
See <a href='onChange-var.html'><code>onChange</code></a>, <a href='onDestroy-var.html'><code>onDestroy</code></a>, <a href='onAllChangesDone-var.html'><code>onAllChangesDone</code></a> 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 <a href='../pipes/Pipe-class.html'><code>Pipe</code></a> 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:
|
|
|
|
```
|
|
@Directive({
|
|
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
|
|
<div [tooltip]="someExpression">...</div>
|
|
<div tooltip="Some Text">...</div>
|
|
```
|
|
|
|
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 <a href='../pipes/Pipe-class.html'><code>Pipe</code></a> and <a href='../pipes/keyValDiff-var.html'><code>keyValDiff</code></a> documentation for more details.
|
|
|
|
```
|
|
@Directive({
|
|
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
|
|
<div [class-set]="someExpression | somePipe">
|
|
```
|
|
|
|
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
|
|
<form>
|
|
<input type="text">
|
|
<input type="radio">
|
|
<form>
|
|
```
|
|
|
|
The directive would only be instantiated on the `<input type="text">` element.
|
|
|
|
|
|
|
|
|