From 7c2c1a8e03cfea1805b8867db34493b39c6e9de7 Mon Sep 17 00:00:00 2001 From: vsavkin Date: Tue, 22 Sep 2015 14:35:17 -0700 Subject: [PATCH] docs(change_detection): add docs to ChangeDetectorRef --- .../change_detection/change_detector_ref.ts | 169 +++++++++++++++++- modules/angular2/test/public_api_spec.ts | 11 +- 2 files changed, 164 insertions(+), 16 deletions(-) diff --git a/modules/angular2/src/core/change_detection/change_detector_ref.ts b/modules/angular2/src/core/change_detection/change_detector_ref.ts index 40bfbaf710..066465a25b 100644 --- a/modules/angular2/src/core/change_detection/change_detector_ref.ts +++ b/modules/angular2/src/core/change_detection/change_detector_ref.ts @@ -2,10 +2,7 @@ import {ChangeDetector} from './interfaces'; import {ChangeDetectionStrategy} from './constants'; /** - * Controls change detection. - * - * {@link ChangeDetectorRef} allows requesting checks for detectors that rely on observables. It - * also allows detaching and attaching change detector subtrees. + * Reference to a component's change detection object. */ export class ChangeDetectorRef { /** @@ -14,7 +11,42 @@ export class ChangeDetectorRef { constructor(private _cd: ChangeDetector) {} /** - * Request to check all OnPush ancestors. + * Marks all {@link OnPush} ancestors as to be checked. + * + * + * + * ### Example ([live demo](http://plnkr.co/edit/GC512b?p=preview)) + * + * ```typescript + * @Component({selector: 'cmp', changeDetection: ChangeDetectionStrategy.OnPush}) + * @View({template: `Number of ticks: {{numberOfTicks}}`}) + * class Cmp { + * numberOfTicks = 0; + * + * constructor(ref: ChangeDetectorRef) { + * setInterval(() => { + * this.numberOfTicks ++ + * // the following is required, otherwise the view will not be updated + * this.ref.markForCheck(); + * }, 1000); + * } + * } + * + * @Component({ + * selector: 'app', + * changeDetection: ChangeDetectionStrategy.OnPush + * }) + * @View({ + * template: ` + * + * `, + * directives: [Cmp] + * }) + * class App { + * } + * + * bootstrap(App); + * ``` */ markForCheck(): void { this._cd.markPathToRootAsCheckOnce(); } @@ -22,16 +54,141 @@ export class ChangeDetectorRef { * Detaches the change detector from the change detector tree. * * The detached change detector will not be checked until it is reattached. + * + * This can also be used in combination with {@link detectChanges} to implement local change + * detection checks. + * + * + * + * + * ### Example + * + * The following example defines a component with a large list of readonly data. + * Imagine the data changes constantly, many times per second. For performance reasons, + * we want to check and update the list every five seconds. We can do that by detaching + * the component's change detector and doing a local check every five seconds. + * + * ```typescript + * class DataProvider { + * // in a real application the returned data will be different every time + * get data() { + * return [1,2,3,4,5]; + * } + * } + * + * @Component({selector: 'giant-list'}) + * @View({ + * template: ` + *
  • Data {{d}} + * `, + * directives: [NgFor] + * }) + * class GiantList { + * constructor(private ref: ChangeDetectorRef, private dataProvider:DataProvider) { + * ref.detach(); + * setInterval(() => { + * this.ref.detectChanges(); + * }, 5000); + * } + * } + * + * @Component({ + * selector: 'app', bindings: [DataProvider] + * }) + * @View({ + * template: ` + * + * `, + * directives: [GiantList] + * }) + * class App { + * } + * + * bootstrap(App); + * ``` */ detach(): void { this._cd.mode = ChangeDetectionStrategy.Detached; } + /** + * Checks the change detector and its children. + * + * This can also be used in combination with {@link detach} to implement local change detection + * checks. + * + * + * + * + * ### Example + * + * The following example defines a component with a large list of readonly data. + * Imagine, the data changes constantly, many times per second. For performance reasons, + * we want to check and update the list every five seconds. + * + * We can do that by detaching the component's change detector and doing a local change detection + * check + * every five seconds. + * + * See {@link detach} for more information. + */ detectChanges(): void { this._cd.detectChanges(); } /** * Reattach the change detector to the change detector tree. * - * This also requests a check of this change detector. This reattached change detector will be + * This also marks OnPush ancestors as to be checked. This reattached change detector will be * checked during the next change detection run. + * + * + * + * ### Example ([live demo](http://plnkr.co/edit/aUhZha?p=preview)) + * + * The following example creates a component displaying `live` data. The component will detach + * its change detector from the main change detector tree when the component's live property + * is set to false. + * + * ```typescript + * class DataProvider { + * data = 1; + * + * constructor() { + * setInterval(() => { + * this.data = this.data * 2; + * }, 500); + * } + * } + * + * @Component({selector: 'live-data', properties: ['live']}) + * @View({ + * template: `Data: {{dataProvider.data}}` + * }) + * class LiveData { + * constructor(private ref: ChangeDetectorRef, private dataProvider:DataProvider) {} + * + * set live(value) { + * if (value) + * this.ref.reattach(); + * else + * this.ref.detach(); + * } + * } + * + * @Component({ + * selector: 'app', + * bindings: [DataProvider] + * }) + * @View({ + * template: ` + * Live Update: + * + * `, + * directives: [LiveData, FORM_DIRECTIVES] + * }) + * class App { + * live = true; + * } + * + * bootstrap(App); + * ``` */ reattach(): void { this._cd.mode = ChangeDetectionStrategy.CheckAlways; diff --git a/modules/angular2/test/public_api_spec.ts b/modules/angular2/test/public_api_spec.ts index 23665ca3ac..e057c567e6 100644 --- a/modules/angular2/test/public_api_spec.ts +++ b/modules/angular2/test/public_api_spec.ts @@ -544,18 +544,9 @@ var NG_API = [ 'KeyValueDiffers', 'KeyValueDiffers.factories', 'KeyValueDiffers.find()', - 'LifeCycle', + 'LifeCycle', // TODO: replace with ApplicationRef 'LifeCycle.registerWith()', 'LifeCycle.tick()', - 'Locals', - 'Locals.clearValues()', - 'Locals.contains()', - 'Locals.current', - 'Locals.current=', - 'Locals.get()', - 'Locals.parent', - 'Locals.parent=', - 'Locals.set()', 'LowerCasePipe', 'LowerCasePipe.transform()', 'MAX_IN_MEMORY_ELEMENTS_PER_TEMPLATE',