From e819e97f9a67344ea094e4a6d8078d115ae436e8 Mon Sep 17 00:00:00 2001 From: Misko Hevery Date: Tue, 14 Apr 2015 23:26:49 +0000 Subject: [PATCH] docs: expose more API to public, document QueryList --- modules/angular2/src/core/annotations/di.js | 52 ++++++++++-- .../{query_list.dart => base_query_list.dart} | 4 +- .../{query_list.es6 => base_query_list.es6} | 4 +- .../angular2/src/core/compiler/compiler.js | 4 +- .../core/compiler/dynamic_component_loader.js | 6 +- .../src/core/compiler/element_injector.js | 3 + .../angular2/src/core/compiler/query_list.js | 83 +++++++++++++++++++ modules/angular2/src/core/compiler/view.js | 2 - modules/angular2/src/test_lib/test_bed.js | 4 +- .../angular2/src/test_lib/test_injector.js | 1 + modules/angular2/test.js | 11 +++ 11 files changed, 160 insertions(+), 14 deletions(-) rename modules/angular2/src/core/compiler/{query_list.dart => base_query_list.dart} (88%) rename modules/angular2/src/core/compiler/{query_list.es6 => base_query_list.es6} (95%) create mode 100644 modules/angular2/src/core/compiler/query_list.js create mode 100644 modules/angular2/test.js diff --git a/modules/angular2/src/core/annotations/di.js b/modules/angular2/src/core/annotations/di.js index 34532d6e64..5fc2887af9 100644 --- a/modules/angular2/src/core/annotations/di.js +++ b/modules/angular2/src/core/annotations/di.js @@ -2,11 +2,17 @@ import {CONST} from 'angular2/src/facade/lang'; import {DependencyAnnotation} from 'angular2/di'; /** - * The directive can inject an emitter function that would emit events onto the - * directive host element. + * Specifies that a function for emitting events should be injected. + * + * NOTE: This is changing pre 1.0. + * + * The directive can inject an emitter function that would emit events onto the directive host element. + * + * @exportedAs angular2/annotations */ export class EventEmitter extends DependencyAnnotation { eventName: string; + @CONST() constructor(eventName) { super(); @@ -19,8 +25,13 @@ export class EventEmitter extends DependencyAnnotation { } /** - * The directive can inject a property setter that would allow setting this property on the - * host element + * Specifies that a function for setting host properties should be injected. + * + * NOTE: This is changing pre 1.0. + * + * The directive can inject a property setter that would allow setting this property on the host element. + * + * @exportedAs angular2/annotations */ export class PropertySetter extends DependencyAnnotation { propName: string; @@ -36,7 +47,32 @@ export class PropertySetter extends DependencyAnnotation { } /** - * The directive can inject the value of an attribute of the host element + * Specifies that a constant attribute value should be injected. + * + * The directive can inject constant string literals of host element attributes. + * + * ## Example + * + * suppose we have an `` element and would like to know its `type`. + * + * ```html + * + * ``` + * + * A decorator could inject string literal `text` like so: + * + * ```javascript + * @Decorator({ + * selector: `input' + * }) + * class InputDecorator { + * constructor(@Attribute('type') type) { + * // type would be `text` in this example + * } + * } + * ``` + * + * @exportedAs angular2/annotations */ export class Attribute extends DependencyAnnotation { attributeName: string; @@ -56,7 +92,11 @@ export class Attribute extends DependencyAnnotation { } /** - * The directive can inject an query that would reflect a list of ancestor directives + * Specifies that a [QueryList] should be injected. + * + * See: [QueryList] for usage. + * + * @exportedAs angular2/annotations */ export class Query extends DependencyAnnotation { directive; diff --git a/modules/angular2/src/core/compiler/query_list.dart b/modules/angular2/src/core/compiler/base_query_list.dart similarity index 88% rename from modules/angular2/src/core/compiler/query_list.dart rename to modules/angular2/src/core/compiler/base_query_list.dart index 4faedcdc56..0c6a7cf7ef 100644 --- a/modules/angular2/src/core/compiler/query_list.dart +++ b/modules/angular2/src/core/compiler/base_query_list.dart @@ -10,12 +10,12 @@ import 'dart:collection'; * In the future this class will implement an Observable interface. * For now it uses a plain list of observable callbacks. */ -class QueryList extends Object with IterableMixin { +class BaseQueryList extends Object with IterableMixin { List _results; List _callbacks; bool _dirty; - QueryList(): _results = [], _callbacks = [], _dirty = false; + BaseQueryList(): _results = [], _callbacks = [], _dirty = false; Iterator get iterator => _results.iterator; diff --git a/modules/angular2/src/core/compiler/query_list.es6 b/modules/angular2/src/core/compiler/base_query_list.es6 similarity index 95% rename from modules/angular2/src/core/compiler/query_list.es6 rename to modules/angular2/src/core/compiler/base_query_list.es6 index 628374f181..2dd782e713 100644 --- a/modules/angular2/src/core/compiler/query_list.es6 +++ b/modules/angular2/src/core/compiler/base_query_list.es6 @@ -7,8 +7,10 @@ import {Directive} from 'angular2/src/core/annotations/annotations'; * * In the future this class will implement an Observable interface. * For now it uses a plain list of observable callbacks. + * + * @exportedAs angular2/view */ -export class QueryList { +export class BaseQueryList { _results: List; _callbacks; _dirty; diff --git a/modules/angular2/src/core/compiler/compiler.js b/modules/angular2/src/core/compiler/compiler.js index 05f66b68f4..f3da148f96 100644 --- a/modules/angular2/src/core/compiler/compiler.js +++ b/modules/angular2/src/core/compiler/compiler.js @@ -40,7 +40,9 @@ export class CompilerCache { } } - +/** + * @exportedAs angular2/template + */ @Injectable() export class Compiler { _reader: DirectiveMetadataReader; diff --git a/modules/angular2/src/core/compiler/dynamic_component_loader.js b/modules/angular2/src/core/compiler/dynamic_component_loader.js index 8e00298ab9..9a719e0537 100644 --- a/modules/angular2/src/core/compiler/dynamic_component_loader.js +++ b/modules/angular2/src/core/compiler/dynamic_component_loader.js @@ -10,7 +10,9 @@ import {Renderer} from 'angular2/src/render/api'; import {ElementRef} from './element_injector'; import {AppView} from './view'; - +/** + * @exportedAs angular2/view + */ export class ComponentRef { location:ElementRef; instance:any; @@ -34,6 +36,8 @@ export class ComponentRef { /** * Service for dynamically loading a Component into an arbitrary position in the internal Angular * application tree. + * + * @exportedAs angular2/view */ @Injectable() export class DynamicComponentLoader { diff --git a/modules/angular2/src/core/compiler/element_injector.js b/modules/angular2/src/core/compiler/element_injector.js index 6ba3a15d79..3b97228574 100644 --- a/modules/angular2/src/core/compiler/element_injector.js +++ b/modules/angular2/src/core/compiler/element_injector.js @@ -19,6 +19,9 @@ var _undefined = new Object(); var _staticKeys; +/** + * @exportedAs angular2/view + */ export class ElementRef { elementInjector:ElementInjector; diff --git a/modules/angular2/src/core/compiler/query_list.js b/modules/angular2/src/core/compiler/query_list.js new file mode 100644 index 0000000000..db45648a70 --- /dev/null +++ b/modules/angular2/src/core/compiler/query_list.js @@ -0,0 +1,83 @@ +import {BaseQueryList} from './base_query_list'; + +/** + * An iterable live list of components in the Light DOM. + * + * Injectable Objects that contains a live list of child directives in the light DOM of a directive. + * The directives are kept in depth-first pre-order traversal of the DOM. + * + * The `QueryList` is iterable, therefore it can be used in both javascript code with `for..of` loop as well as in + * template with `*for="of"` viewport. + * + * NOTE: In the future this class will implement an `Observable` interface. For now it uses a plain list of observable + * callbacks. + * + * # Example: + * + * Assume that `` component would like to get a list its children which are `` components as shown in this + * example: + * + * ```html + * + * ... + * {{o.text}} + * + * ``` + * + * In the above example the list of `` elements needs to get a list of `` elements so that it could render + * tabs with the correct titles and in the correct order. + * + * A possible solution would be for a `` to inject `` component and then register itself with `` + * component's on `hydrate` and deregister on `dehydrate` event. While a reasonable approach, this would only work + * partialy since `*for` could rearange the list of `` components which would not be reported to `` + * component and thus the list of `` componets would be out of sync with respect to the list of `` elements. + * + * A prefferd solution is to inject a `QueryList` which is a live list of directives in the component`s light DOM. + * + * ```javascript + * @Component({ + * selector: 'tabs' + * }) + * @View({ + * template: ` + *
    + *
  • {{pane.title}}
    • + *
+ * + * ` + * }) + * class Tabs { + * panes: QueryList + * + * constructor(@Query(Pane) panes:QueryList) { + * this.panes = panes; + * } + * } + * + * @Component({ + * selector: 'pane', + * properties: ['title'] + * }) + * @View(...) + * class Pane { + * title:string; + * } + * ``` + * + * @exportedAs angular2/view + */ +export class QueryList extends BaseQueryList { + + /** + */ + onChange(callback) { + return super.onChange(callback); + } + + /** + */ + removeCallback(callback) { + return super.removeCallback(callback); + } + +} \ No newline at end of file diff --git a/modules/angular2/src/core/compiler/view.js b/modules/angular2/src/core/compiler/view.js index d455cb11e6..16ba1f3d47 100644 --- a/modules/angular2/src/core/compiler/view.js +++ b/modules/angular2/src/core/compiler/view.js @@ -13,7 +13,6 @@ import * as renderApi from 'angular2/src/render/api'; /** * Const of making objects: http://jsperf.com/instantiate-size-of-object * - * @exportedAs angular2/template */ @IMPLEMENTS(ChangeDispatcher) // TODO(tbosch): this is not supported in dart2js (no '.' is allowed) @@ -288,7 +287,6 @@ export class AppView { /** * - * @exportedAs angular2/template */ export class AppProtoView { elementBinders:List; diff --git a/modules/angular2/src/test_lib/test_bed.js b/modules/angular2/src/test_lib/test_bed.js index f4a8850b2e..a0ea3915b0 100644 --- a/modules/angular2/src/test_lib/test_bed.js +++ b/modules/angular2/src/test_lib/test_bed.js @@ -18,7 +18,9 @@ import {DirectiveMetadataReader} from 'angular2/src/core/compiler/directive_meta import {queryView, viewRootNodes, el} from './utils'; import {instantiateType, getTypeOf} from './lang_utils'; - +/** + * @exportedAs angular2/test + */ export class TestBed { _injector: Injector; diff --git a/modules/angular2/src/test_lib/test_injector.js b/modules/angular2/src/test_lib/test_injector.js index ce1ef162d3..467733da1e 100644 --- a/modules/angular2/src/test_lib/test_injector.js +++ b/modules/angular2/src/test_lib/test_injector.js @@ -142,6 +142,7 @@ export function createTestInjector(bindings: List) { * @param {Array} tokens * @param {Function} fn * @return {FunctionWithParamTokens} + * @exportedAs angular2/test */ export function inject(tokens: List, fn: Function) { return new FunctionWithParamTokens(tokens, fn); diff --git a/modules/angular2/test.js b/modules/angular2/test.js new file mode 100644 index 0000000000..7094ec54c5 --- /dev/null +++ b/modules/angular2/test.js @@ -0,0 +1,11 @@ +/** + * @module + * @public + * @description + * This module is used for writing tests for applications written in Angular. + * + * This module is not included in the `angular2` module; you must import the test module explicitly. + * + */ +export * from './src/test_lib/test_bed'; +export * from './src/test_lib/test_injector';