Documentation for ng-for

modules/angular2/src/core/directives/ng_for.ts

@@ -13,17 +13,52 @@ import {isPresent, isBlank} from 'angular2/src/core/facade/lang';
  * each instantiated template inherits from the outer context with the given loop variable set
  * to the current item from the iterable.
  *
- * It is possible to alias the `index` to a local variable that will be set to the current loop
- * iteration in the template context, and also to alias the 'last' to a local variable that will
- * be set to a boolean indicating if the item is the last one in the iteration
+ * # Local Variables
+ *
+ * `NgFor` provides several exported values that can be aliased to local variables:
+ *
+ * * `index` will be set to the current loop iteration for each template context.
+ * * `last` will be set to a boolean value indicating whether the item is the last one in the
+ *   iteration.
+ * * `even` will be set to a boolean value indicating whether this item has an even index.
+ * * `odd` will be set to a boolean value indicating whether this item has an odd index.
+ *
+ * # Change Propagation
+ *
+ * There are two reasons why `NgFor` will need to update the DOM:
+ * * The contents of the iterator changes.
+ * * The iterator itself is replaced.
  *
  * When the contents of the iterator changes, `NgFor` makes the corresponding changes to the DOM:
  *
  * * When an item is added, a new instance of the template is added to the DOM.
  * * When an item is removed, its template instance is removed from the DOM.
  * * When items are reordered, their respective templates are reordered in the DOM.
+ * * Otherwise, the DOM element for that item will remain the same.
+ *
+ * Angular uses object identity to track insertions and deletions within the iterator and reproduce
+ * those changes in the DOM. This has important implications for animations and any stateful controls
+ * (such as `<input>` elements which accept user input) that are present. Inserted rows can be
+ * animated in, deleted rows can be animated out, and unchanged rows retain any unsaved state such
+ * as user input.
  *
- * # Example
+ * It is possible for the identities of elements in the iterator to change while the data does not.
+ * This can happen, for example, if the iterator produced from an RPC to the server, and that
+ * RPC is re-run. Even if the data hasn't changed, the second response will produce objects with
+ * different identities, and Angular will tear down the entire DOM and rebuild it (as if all old
+ * elements were deleted and all new elements inserted). This is an expensive operation and should
+ * be avoided if possible.
+ *
+ * # Syntax
+ *
+ * - `<li *ng-for="#item of items; #i = index">...</li>`
+ * - `<li template="ng-for #item of items; #i = index">...</li>`
+ * - `<template ng-for #item [ng-for-of]="items" #i="index"><li>...</li></template>`
+ *
+ * ### Example
+ *
+ * See a [live demo](http://plnkr.co/edit/KVuXxDp0qinGDyo307QW?p=preview) for a more detailed
+ * example.
  *
  * ```
  * <ul>
@@ -32,12 +67,6 @@ import {isPresent, isBlank} from 'angular2/src/core/facade/lang';
  *   </li>
  * </ul>
  * ```
- *
- * # Syntax
- *
- * - `<li *ng-for="#item of items; #i = index">...</li>`
- * - `<li template="ng-for #item of items; #i = index">...</li>`
- * - `<template ng-for #item [ng-for-of]="items" #i="index"><li>...</li></template>`
  */
 @Directive({selector: '[ng-for][ng-for-of]', inputs: ['ngForOf', 'ngForTemplate']})
 export class NgFor implements DoCheck {