honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: annotations

This commit is contained in:
Nick Van Dyck 2015-03-19 14:31:41 +01:00 committed by Misko Hevery
parent 1c9938ed98
commit 0e61a86763
2 changed files with 69 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
modules/angular2/docs/core/01_templates.md
View File

@ -187,7 +187,7 @@ Example:
<pre>
```
<ul>
<li template="foreach: #item in items">
<li template="for: #item of items">
{{item}}
</li>
</ul>
@ -201,8 +201,8 @@ Example:
<pre>
```
<ul>
<template def-foreach:"item"
bind-foreach-in="items">
<template def-for:"item"
bind-for-in="items">
<li>
{{item}}
</li>
@ -221,8 +221,8 @@ Example:
<pre>
```
<template #foreach="item"
[foreach-in]="items">
<template #for="item"
[for-in]="items">
_some_content_to_repeat_
</template>
```
@ -234,8 +234,8 @@ Example:
Example:
<pre>
```
<template def-foreach="item"
bind-foreach-in="items">
<template def-for="item"
bind-for-in="items">
_some_content_to_repeat_
</template>
```
@ -408,22 +408,22 @@ NOTE: Only Viewport directives can be placed on the template element. (Decorator
### Template Microsyntax
Often times it is necessary to encode a lot of different bindings into a template to control how the instantiation
of the templates occurs. One such example is `foreach`.
of the templates occurs. One such example is `for`.
```
<form #foo=form>
</form>
<ul>
<template foreach #person [in]="people" #i="index">
<template for #person [in]="people" #i="index">
<li>{{i}}. {{person}}<li>
</template>
</ul>
```
Where:
* `foreach` triggers the foreach directive.
* `[in]="people"` binds an iterable object to the `foreach` controller.
* `#person` exports the implicit `foreach` item.
* `for` triggers the for directive.
* `[in]="people"` binds an iterable object to the `for` controller.
* `#person` exports the implicit `for` item.
* `#i=index` exports item index as `i`.
The above example is explicit but quite wordy. For this reason in most situations a short hand version of the
@ -431,7 +431,7 @@ syntax is preferable.
```
<ul>
<li template="foreach; #person; in=people; #i=index;">{{i}}. {{person}}<li>
<li template="for; #person; in=people; #i=index;">{{i}}. {{person}}<li>
</ul>
```
@ -441,19 +441,28 @@ which allows us to further shorten the text.
```
<ul>
<li template="foreach #person in people #i=index">{{i}}. {{person}}<li>
<li template="for #person of people #i=index">{{i}}. {{person}}<li>
</ul>
```
We can also optionally use `var` instead of `#` and add `:` to `foreach` which creates the following recommended
microsyntax for `foreach`.
We can also optionally use `var` instead of `#` and add `:` to `for` which creates the following recommended
microsyntax for `for`.
```
<ul>
<li template="foreach: var person in people; var i=index">{{i}}. {{person}}<li>
<li template="for: var person of people; var i=index">{{i}}. {{person}}<li>
</ul>
```
Finally, we can move the `for` keyword to the left hand side and prefix it with `*` as so:
```
<ul>
<li *for="var person of people; var i=index">{{i}}. {{person}}<li>
</ul>
```
The format is intentionally defined freely, so that developers of directives can build an expressive microsyntax for
their directives. The following code describes a more formal definition.

72
modules/angular2/src/core/annotations/annotations.js vendored
View File

@ -556,7 +556,7 @@ export class Component extends Directive {
}
/**
* A directive used for dynamically loading components.
* Directive used for dynamically loading components.
*
* Regular angular components are statically resolved. DynamicComponent allows to you resolve a component at runtime
* instead by providing a placeholder into which a regular angular component can be dynamically loaded. Once loaded,
@ -637,9 +637,9 @@ export class DynamicComponent extends Directive {
/**
* Directive that attaches behavior to DOM elements.
*
* A decorator directive attaches behavior to a DOM element in a composable manner.
* A decorator directive attaches behavior to a DOM element in a composable manner.
* (see: http://en.wikipedia.org/wiki/Composition_over_inheritance)
*
*
* Decorators:
* - are simplest form of [Directive]s.
* - are best used as a composition pattern ()
@ -652,7 +652,7 @@ export class DynamicComponent extends Directive {
*
* ## Example
*
* Here we use a decorator directive to simply define basic tool-tip behavior.
* Here we use a decorator directive to simply define basic tool-tip behavior.
*
* ```
* @Decorator({
@ -685,9 +685,9 @@ export class DynamicComponent extends Directive {
* }
* }
* ```
* In our HTML template, we can then add this behavior to a `<div>` or any other element with the `tooltip` selector,
* 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>
* ```
@ -728,24 +728,45 @@ export class Decorator extends Directive {
}
/**
* Viewport is used for controlling the instatiation of inline templates. [TODO: needs co-work :)]
* Directive that controls the instantiation, destruction, and positioning of inline template elements.
*
* Viewport consist of a controller which can inject [ViewContainer]. A [ViewContainer] represents a location in the
* current view where child views can be inserted. [ViewContainer] is created as a result of `<template>` element.
* A viewport directive uses a [ViewContainer] to instantiate, insert, move, and destroy views at runtime.
* The [ViewContainer] is created as a result of `<template>` element, and represents a location in the current view
* where these actions are performed.
*
* NOTE: `<template>` directives can be created in shorthand form as `<TAG template="...">` or `<TAG *key="...">`
* Views are always created as children of the current [View], and as siblings of the `<template>` element. Thus a
* directive in a child view cannot inject the viewport directive that created it.
*
* ## Example
* Since viewport directives 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.
*
* Given folowing inline template, let's implement the `unless` behavior.
* Thus,
*
* ```
* <ul>
* <li *unless="expr"></li>
* <li *foo="bar" title="text"></li>
* </ul>
* ```
*
* Can be implemented using:
* 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 `Viewport`
* 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 viewport directive that triggers on an `unless` selector:
*
* ```
* @Viewport({
@ -754,7 +775,7 @@ export class Decorator extends Directive {
* 'condition': 'unless'
* }
* })
* export class If {
* export class Unless {
* viewContainer: ViewContainer;
* prevCondition: boolean;
*
@ -775,20 +796,14 @@ export class Decorator extends Directive {
* }
* ```
*
* To better undarstand what is hapening, remember that angular converts the above template to:
*
* We can then use this `unless` selector in a template:
* ```
* <ul>
* <template [unless]="exp">
* <li></li>
* </template>
* <li *unless="expr"></li>
* </ul>
* ```
*
* Notice that the `*unless="exp"` got hoisted to `<template>`. This means that the `Viewport` controller is instantiated
* on the `<template>` element rather thna the `<li>` element.
*
* Once the viewport insntantiates the child view the result is:
* Once the viewport instantiates the child view, the shorthand notation for the template expands and the result is:
*
* ```
* <ul>
@ -799,9 +814,8 @@ export class Decorator extends Directive {
* </ul>
* ```
*
* The key thing to notice here is that `<li>` instance is a sibling of `<template>` not a child. For this reason
* it is not possible to inject `Viewport` directive into other directives, (`Viweport` directives are always on
* `<template>` elements which are leafs.)
* 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.
*
*
* @publicModule angular2/annotations
@ -831,7 +845,7 @@ export class Viewport extends Directive {
//TODO(misko): turn into LifecycleEvent class once we switch to TypeScript;
/**
* Specify that a directive should be notified whenever a [View] that contains it is destroyed.
* Notify a directive whenever a [View] that contains it is destroyed.
*
* ## Example
*
@ -852,7 +866,7 @@ export const onDestroy = "onDestroy";
/**
* Specify that a directive should be notified when any of its bindings have changed.
* Notify a directive when any of its bindings have changed.
*
* ## Example:
*