2015-07-27 22:12:30 -07:00
p.location-badge.
exported from <a href='../annotations'>angular2/annotations</a>
2015-08-06 23:25:42 -07:00
defined in <a href="https://github.com/angular/angular/tree/2.0.0-alpha.34/modules/angular2/src/core/annotations_impl/annotations.ts#L4-L778">angular2/src/core/annotations_impl/annotations.ts (line 4)</a>
2015-07-27 22:12:30 -07:00
:markdown
Directives allow you to attach behavior to elements in the DOM.
<a href='Directive-var.html'><code>Directive</code></a>s with an embedded view are called <a href='Component-var.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 instance has its own <a href='../di/Injector-class.html'><code>Injector</code></a>, 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
<a href='View-var.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
2015-08-02 23:08:36 -07:00
- `@Host() directive:DirectiveType`: any directive that matches the type between the current
2015-07-27 22:12:30 -07:00
element and the
2015-08-02 23:08:36 -07:00
Shadow DOM root.
2015-07-27 22:12:30 -07:00
- `@Query(DirectiveType) query:QueryList<DirectiveType>`: A live collection of direct child
directives.
- `@QueryDescendants(DirectiveType) query:QueryList<DirectiveType>`: 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
<a href='Directive-var.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 any ancestor elements
Directives can inject other directives declared on any ancestor element (in the current Shadow
2015-08-02 23:08:36 -07:00
DOM), i.e. on the current element, the
parent element, or its parents.
2015-07-27 22:12:30 -07:00
```
@Directive({ selector: '[my-directive]' })
class MyDirective {
2015-08-02 23:08:36 -07:00
constructor(@Host() dependency: Dependency) {
2015-07-27 22:12:30 -07:00
expect(dependency.id).toEqual(2);
}
}
```
2015-08-02 23:08:36 -07:00
`@Host` checks the current element, the parent, as well as its parents recursively. If
`dependency="2"` didn't
2015-07-27 22:12:30 -07:00
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='../core/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 `ng-for`, an
`ng-if`, or an `ng-switch`.
```
@Directive({ selector: '[my-directive]' })
class MyDirective {
constructor(@Query(Dependency) dependencies:QueryList<Dependency>) {
}
}
```
This directive would be instantiated with a <a href='../core/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
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<Dependency>) {
}
}
```
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-var.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']
})
export class Unless {
viewContainer: ViewContainerRef;
templateRef: TemplateRef;
prevCondition: boolean;
constructor(viewContainer: ViewContainerRef, templateRef: TemplateRef) {
this.viewContainer = viewContainer;
this.templateRef = templateRef;
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.templateRef);
}
}
}
```
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.
2015-07-28 13:28:47 -07:00
.l-main-section
h2 Annotations
.l-sub-section
h3.annotation CONST
pre.prettyprint
code.
@CONST()
2015-07-27 22:12:30 -07:00
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor({
2015-08-02 23:08:36 -07:00
selector, properties, events, host, lifecycle, bindings, exportAs,
2015-07-30 11:19:45 -07:00
compileChildren = true,
}?: {
selector?: string,
properties?: List<string>,
events?: List<string>,
host?: StringMap<string, string>,
lifecycle?: List<LifecycleEvent>,
2015-08-02 23:08:36 -07:00
bindings?: List<any>,
2015-07-30 11:19:45 -07:00
exportAs?: string,
compileChildren?: boolean,
})
2015-07-27 22:12:30 -07:00
:markdown
.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.
.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`
configuration:
- `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='../change_detection/Pipe-interface.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
There is no need to specify both `directiveProperty` and `bindingProperty` when they both have
the same value.
```
@Directive({
properties: [
'propertyName', // shorthand notation for 'propertyName: propertyName'
'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(value: string) {
// This will get called every time with the new value when the 'tooltip' property changes
}
}
```
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.
2015-08-06 23:25:42 -07:00
See <a href='../change_detection/Pipe-interface.html'><code>Pipe</code></a> and `KeyValueChanges` documentation for more details.
2015-07-27 22:12:30 -07:00
```
@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 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');
}
}
```
Use `propertyName: eventName` when the event emitter property name is different from the name
of the emitted event:
```
@Component({
events: ['status: statusChange']
})
class TaskComponent {
status: EventEmitter;
constructor() {
this.status = new EventEmitter();
}
onComplete() {
this.status.next('completed');
}
}
```
.l-sub-section
h3 host
:markdown
Specifiy the events, actions, properties and attributes related to the host element.
## Events
Specifies which DOM hostListeners a directive listens to via 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({
host: {
'(event1)': 'onMethod1(arguments)',
'(target:event2)': 'onMethod2(arguments)',
...
}
}
```
## Basic Event Binding:
Suppose you want to write a directive that reacts to `change` events in the DOM and on
`resize` events in window.
You would define the event binding as follows:
```
@Directive({
selector: 'input',
host: {
'(change)': 'onChange($event)',
'(window:resize)': 'onResize($event)'
}
})
class InputDirective {
onChange(event:Event) {
// invoked when the input element fires the 'change' event
}
onResize(event:Event) {
// invoked when the window fires the 'resize' event
}
}
```
## Properties
Specifies which DOM properties a directives updates.
## Syntax
```
@Directive({
selector: 'input',
host: {
'[prop]': 'expression'
}
})
class InputDirective {
value:string;
}
```
In this example the prop property of the host element is updated with the expression value
every time it changes.
## Attributes
Specifies static attributes that should be propagated to a host element. Attributes specified
in `hostAttributes` are propagated only if a given attribute is not present on a host element.
## Syntax
```
@Directive({
selector: '[my-button]',
host: {
'role': 'button'
}
})
class MyButton {
}
```
In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
(here: `<div>` ) will ensure that this element will get the "button" role.
## Actions
Specifies which DOM methods a directive can invoke.
## Syntax
```
@Directive({
selector: 'input',
host: {
'@emitFocus': 'focus()'
}
})
class InputDirective {
constructor() {
this.emitFocus = new EventEmitter();
}
focus() {
this.emitFocus.next();
}
}
```
In this example calling focus on InputDirective will result in calling focus on the input.
.l-sub-section
h3 lifecycle
:markdown
Specifies which lifecycle should be notified to the directive.
See <a href='LifecycleEvent-enum.html'><code>LifecycleEvent</code></a> for details.
.l-sub-section
h3 compileChildren
:markdown
If set to false the compiler does not compile the children of this directive.
.l-sub-section
2015-08-02 23:08:36 -07:00
h3 bindings
2015-07-27 22:12:30 -07:00
:markdown
Defines the set of injectable objects that are visible to a Directive and its light 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: 'greet',
2015-08-02 23:08:36 -07:00
bindings: [
2015-07-27 22:12:30 -07:00
Greeter
]
})
class HelloWorld {
greeter:Greeter;
constructor(greeter:Greeter) {
this.greeter = greeter;
}
}
```
.l-sub-section
h3 exportAs
:markdown
Defines the name that can be used in the template to assign this directive to a variable.
## Simple Example
```
@Directive({
selector: 'child-dir',
exportAs: 'child'
})
class ChildDir {
}
@Component({
selector: 'main',
})
@View({
template: `<child-dir #c="child"></child-dir>`,
directives: [ChildDir]
})
class MainComponent {
}
```
