diff --git a/modules/angular2/src/core/compiler/compiler.ts b/modules/angular2/src/core/compiler/compiler.ts index af97572fa9..b8ee0da65f 100644 --- a/modules/angular2/src/core/compiler/compiler.ts +++ b/modules/angular2/src/core/compiler/compiler.ts @@ -70,8 +70,7 @@ export class CompilerCache { } } -/** - * +/* * ## URL Resolution * * ``` @@ -88,9 +87,15 @@ export class CompilerCache { * var url = viewAnnotation.templateUrl; * var componentUrl = componentUrlMapper.getUrl(componentType); * var componentResolvedUrl = urlResolver.resolve(appRootUrl.value, componentUrl); - * var templateResolvedUrl = urlResolver.resolve(componetResolvedUrl, url); + * var templateResolvedUrl = urlResolver.resolve(componentResolvedUrl, url); * ``` */ +/** + * Service for compiling {@link Component}s so that they can be later instantiated and their + * {@link View}s can be rendered. + * + * + */ @Injectable() export class Compiler { private _compiling: Map> = new Map(); @@ -127,8 +132,10 @@ export class Compiler { return PipeBinding.createFromType(typeOrBinding, meta); } - // Create a hostView as if the compiler encountered . - // Used for bootstrapping. + /** + * Compiles an {@link EntryPointComponent entry-point Component} and returns a promise for a + * {@link ProtoViewRef} that can be passed into {@link AppViewManager + */ compileInHost(componentType: Type): Promise { var r = wtfStartTimeRange('Compiler#compile()', stringify(componentType)); diff --git a/modules/angular2/src/core/compiler/dynamic_component_loader.ts b/modules/angular2/src/core/compiler/dynamic_component_loader.ts index 4438e4c990..a1d2237e25 100644 --- a/modules/angular2/src/core/compiler/dynamic_component_loader.ts +++ b/modules/angular2/src/core/compiler/dynamic_component_loader.ts @@ -7,9 +7,8 @@ import {ElementRef} from './element_ref'; import {ViewRef, HostViewRef} from './view_ref'; /** - * Angular's reference to a component instance. - * - * `ComponentRef` represents a component instance lifecycle and meta information. + * Represents a component instance as a node in application's component tree and provides access to + * other objects related to this component instance. */ export class ComponentRef { /** @@ -24,7 +23,6 @@ export class ComponentRef { componentType: Type; - injector: Injector; /** @@ -54,11 +52,15 @@ export class ComponentRef { } /** - * Service for dynamically loading a Component into an arbitrary position in the internal Angular - * application tree. + * Service for creating an instance of a component and attaching it to the component tree of an + * application at a specified location. */ @Injectable() export class DynamicComponentLoader { + + /** + * @private + */ constructor(private _compiler: Compiler, private _viewManager: AppViewManager) {} /** diff --git a/modules/angular2/src/core/compiler/element_ref.ts b/modules/angular2/src/core/compiler/element_ref.ts index c3ee07ec57..45dbf41005 100644 --- a/modules/angular2/src/core/compiler/element_ref.ts +++ b/modules/angular2/src/core/compiler/element_ref.ts @@ -3,20 +3,28 @@ import {ViewRef} from './view_ref'; import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api'; /** - * An opaque reference to the underlying element. + * Represents a location in a View that has an injection, change-detection and render contexts + * associated with it. * - * The underlying native element is a DOM Element in a browser context, but may represent other - * types on other rendering platforms. In the browser the `ElementRef` can be sent to the Web - * Worker. Web Workers can not have references to the DOM Elements. + * An `ElementRef` is created for each element in the Template that contains a Directive, Component + * or data-binding. + * + * An `ElementRef` is backed by a render-specific element. In the browser context, this is usually a + * DOM element. */ export class ElementRef implements RenderElementRef { + /** - * Reference to the {@link ViewRef} where the `ElementRef` is inside of. + * @private + * + * Reference to the {@link ViewRef} that this `ElementRef` is part of. */ parentView: ViewRef; /** + * @private + * * Index of the element inside the {@link ViewRef}. * * This is used internally by the Angular framework to locate elements. @@ -24,12 +32,17 @@ export class ElementRef implements RenderElementRef { boundElementIndex: number; /** + * @private + * * Index of the element inside the `RenderViewRef`. * * This is used internally by the Angular framework to locate elements. */ renderBoundElementIndex: number; + /** + * @private + */ constructor(parentView: ViewRef, boundElementIndex: number, renderBoundElementIndex: number, private _renderer: Renderer) { this.parentView = parentView; @@ -38,7 +51,7 @@ export class ElementRef implements RenderElementRef { } /** - * + * @private */ get renderView(): RenderViewRef { return this.parentView.render; } @@ -48,15 +61,22 @@ export class ElementRef implements RenderElementRef { set renderView(viewRef: RenderViewRef) { throw new BaseException('Abstract setter'); } /** - * Returns the native Element implementation. + * The underlying native element or `null` if direct access to native elements is not supported + * (e.g. when the application runs in a web worker). * - * In the browser this represents the DOM element. - * - * The `nativeElement` can be used as an escape hatch when direct DOM manipulation is needed. Use - * this with caution, as it creates tight coupling between your application and the browser, which - * will not work in Web Workers. - * - * NOTE: This method will return null in the webworker scenario! + *
+ *
Use with caution
+ *

+ * Use this api as the last resort when direct access to DOM is needed. Use templating and + * data-binding provided by Angular instead. + *

+ *

+ * Relying on direct DOM access creates tight coupling between your application and rendering + * layers which will make it impossible to separate the two and deploy your application in into a + * web worker. + *

+ * + *
*/ get nativeElement(): any { return this._renderer.getNativeElementSync(this); } } diff --git a/modules/angular2/src/core/compiler/template_ref.ts b/modules/angular2/src/core/compiler/template_ref.ts index e01c601b63..0282204fb7 100644 --- a/modules/angular2/src/core/compiler/template_ref.ts +++ b/modules/angular2/src/core/compiler/template_ref.ts @@ -3,17 +3,26 @@ import {ElementRef} from './element_ref'; import * as viewModule from './view'; /** - * Reference to a template within a component. + * Represents an Embedded Template that can be used for creating Embedded Views. * - * Represents an opaque reference to the underlying template that can - * be instantiated using the {@link ViewContainerRef}. + * Use {@link ViewContainerRef#createEmbeddedView} method to instantiate an Embedded View and attach + * it to a View Container. + * + * */ export class TemplateRef { + /** - * The location of the template + * The location in the View where the Embedded View logically belong to. + * + * This `ElementRef` provides the data-binding and injection context for Embedded Views created + * from this `TemplateRef`. */ elementRef: ElementRef; + /** + * @private + */ constructor(elementRef: ElementRef) { this.elementRef = elementRef; } private _getProtoView(): viewModule.AppProtoView { @@ -23,10 +32,14 @@ export class TemplateRef { .nestedProtoView; } + /** + * Reference to the ProtoView created by compiling the original Embedded Template, from which the + * Embedded View is instatiated. + */ get protoViewRef(): ProtoViewRef { return this._getProtoView().ref; } /** - * Whether this template has a local variable with the given name + * Returns true if the Template declares a Local Variable with the given name. */ hasLocal(name: string): boolean { return this._getProtoView().variableBindings.has(name); } } diff --git a/modules/angular2/src/core/compiler/view_container_ref.ts b/modules/angular2/src/core/compiler/view_container_ref.ts index ebd7f2501a..453d4efdd0 100644 --- a/modules/angular2/src/core/compiler/view_container_ref.ts +++ b/modules/angular2/src/core/compiler/view_container_ref.ts @@ -10,17 +10,44 @@ import {TemplateRef} from './template_ref'; import {ViewRef, HostViewRef, ProtoViewRef, internalView} from './view_ref'; /** - * A location where {@link ViewRef}s can be attached. + * Represents a container where one or more Views can be attached. * - * A `ViewContainerRef` represents a location in a {@link ViewRef} where other child - * {@link ViewRef}s can be inserted. Adding and removing views is the only way of structurally - * changing the rendered DOM of the application. + * The container can contain two kinds of Views. Host Views, created by instantiating a + * {@link Component} via {@link #createHostView}s, and Embedded Views, created by instantiating an + * {@link TemplateRef Embedded Template} via {@link #createEmbeddedView}). + * + * The location of the View Container within the containing View is specified by the Anchor + * `element`. Each View Container can have only one Anchor Element and each Anchor Element can only + * have a single View Container. + * + * Root elements of Views attached to this container become siblings of the Anchor Element in + * the Rendered View. + * + * To access a ViewContainerRef of an Element, you can either place a {@link Directive} injected + * with `ViewContainerRef` on the Element, or you obtain it via + * {@link ViewManager#getViewContainer}. + * + * + * */ export class ViewContainerRef { + /** * @private */ - constructor(public viewManager: avmModule.AppViewManager, public element: ElementRef) {} + constructor( + /** + * @private + */ + public viewManager: avmModule.AppViewManager, + + /** + * Anchor element that specifies the location of this container in the containing View. + */ + public element: ElementRef + ) { + + } private _getViews(): Array { var vc = internalView(this.element.parentView).viewContainers[this.element.boundElementIndex]; @@ -28,7 +55,7 @@ export class ViewContainerRef { } /** - * Remove all {@link ViewRef}s at current location. + * Destroys all Views in the container. */ clear(): void { for (var i = this.length - 1; i >= 0; i--) { @@ -37,28 +64,22 @@ export class ViewContainerRef { } /** - * Return a {@link ViewRef} at specific index. + * Returns the {@link ViewRef} for the View located in this container at the specified index. */ get(index: number): ViewRef { return this._getViews()[index].ref; } /** - * Returns number of {@link ViewRef}s currently attached at this location. + * Returns the number of Views currently attached to this container. */ get length(): number { return this._getViews().length; } /** - * Create and insert a {@link ViewRef} into the view-container. + * Instantiates an Embedded View based on the {@link TemplateRef `templateRef`} and inserts it + * into this container at index specified via `atIndex`. * - * - `protoViewRef` (optional) {@link ProtoViewRef} - The `ProtoView` to use for creating - * `View` to be inserted at this location. If `ViewContainer` is created at a location - * of inline template, then `protoViewRef` is the `ProtoView` of the template. - * - `atIndex` (optional) `number` - location of insertion point. (Or at the end if unspecified.) - * - `context` (optional) {@link ElementRef} - Context (for expression evaluation) from the - * {@link ElementRef} location. (Or current context if unspecified.) - * - `bindings` (optional) Array of {@link ResolvedBinding} - Used for configuring - * `ElementInjector`. + * If `atIndex` is not specified, the new View will be inserted as the last View in the container. * - * Returns newly created {@link ViewRef}. + * Returns the {@link ViewRef} for the newly created View. */ // TODO(rado): profile and decide whether bounds checks should be added // to the methods below. @@ -67,6 +88,20 @@ export class ViewContainerRef { return this.viewManager.createEmbeddedViewInContainer(this.element, atIndex, templateRef); } + /** + * Instantiates a single {@link Component} and inserts it into this container at index specified + * via `atIndex`. + * + * The component is instantiated using its {@link ProtoViewRef `protoViewRef`} which can be + * obtained via {@link Compiler#compileInHost}. + * + * If `atIndex` is not specified, the new View will be inserted as the last View in the container. + * + * You can optionally specify `dynamicallyCreatedBindings`, which configure the {@link Injector} + * that will be created for the new Host View. + * + * Returns the {@link ViewRef} for the newly created View. + */ createHostView(protoViewRef: ProtoViewRef = null, atIndex: number = -1, dynamicallyCreatedBindings: ResolvedBinding[] = null): HostViewRef { if (atIndex == -1) atIndex = this.length; @@ -75,12 +110,14 @@ export class ViewContainerRef { } /** - * Insert a {@link ViewRef} at specefic index. + * + * Inserts a View identified by a {@link ViewRef} into the container at index specified via + * `atIndex`. * - * The index is location at which the {@link ViewRef} should be attached. If omitted it is - * inserted at the end. + * If `atIndex` is not specified, the new View will be inserted as the last View in the container. * * Returns the inserted {@link ViewRef}. + * */ insert(viewRef: ViewRef, atIndex: number = -1): ViewRef { if (atIndex == -1) atIndex = this.length; @@ -88,16 +125,17 @@ export class ViewContainerRef { } /** - * Return the index of already inserted {@link ViewRef}. + * Returns the index of the View, specified via {@link ViewRef}, within the current container. */ indexOf(viewRef: ViewRef): number { return ListWrapper.indexOf(this._getViews(), internalView(viewRef)); } /** - * Remove a {@link ViewRef} at specific index. + * + * Destroys a View attached to this container at index specified via `atIndex`. * - * If the index is omitted last {@link ViewRef} is removed. + * If `atIndex` is not specified, the last View in the container will be removed. */ remove(atIndex: number = -1): void { if (atIndex == -1) atIndex = this.length - 1; @@ -106,8 +144,11 @@ export class ViewContainerRef { } /** - * The method can be used together with insert to implement a view move, i.e. - * moving the DOM nodes while the directives in the view stay intact. + * + * Use along with {@link #insert} to move a View within the current container. + * + * If the `atIndex` param is omitted, the last {@link ViewRef} is detached. + * */ detach(atIndex: number = -1): ViewRef { if (atIndex == -1) atIndex = this.length - 1; diff --git a/modules/angular2/src/core/compiler/view_manager.ts b/modules/angular2/src/core/compiler/view_manager.ts index d5bf364216..047260476a 100644 --- a/modules/angular2/src/core/compiler/view_manager.ts +++ b/modules/angular2/src/core/compiler/view_manager.ts @@ -19,9 +19,10 @@ import {AppViewListener} from './view_listener'; import {wtfCreateScope, wtfLeave, WtfScopeFn} from '../profile/profile'; /** - * Entry point for creating, moving views in the view hierarchy and destroying views. - * This manager contains all recursion and delegates to helper methods - * in AppViewManagerUtils and the Renderer, so unit tests get simpler. + * Service exposing low level API for creating, moving and destroying Views. + * + * Most applications should use higher-level abstractions like {@link DynamicComponentLoader} and + * {@link ViewContainerRef} instead. */ @Injectable() export class AppViewManager { @@ -178,6 +179,7 @@ export class AppViewManager { _createEmbeddedViewInContainerScope: WtfScopeFn = wtfCreateScope('AppViewManager#createEmbeddedViewInContainer()'); /** + * * * See {@link AppViewManager#destroyViewInContainer}. */ @@ -195,6 +197,7 @@ export class AppViewManager { _createHostViewInContainerScope: WtfScopeFn = wtfCreateScope('AppViewManager#createHostViewInContainer()'); /** + * * * See {@link AppViewManager#destroyViewInContainer}. */ @@ -258,6 +261,7 @@ export class AppViewManager { _destroyViewInContainerScope = wtfCreateScope('AppViewMananger#destroyViewInContainer()'); /** + * * * See {@link AppViewManager#createViewInContainer}. */ @@ -271,6 +275,7 @@ export class AppViewManager { _attachViewInContainerScope = wtfCreateScope('AppViewMananger#attachViewInContainer()'); /** + * * * See {@link AppViewManager#detachViewInContainer}. */ @@ -293,6 +298,7 @@ export class AppViewManager { _detachViewInContainerScope = wtfCreateScope('AppViewMananger#detachViewInContainer()'); /** + * * * See {@link AppViewManager#attachViewInContainer}. */ diff --git a/modules/angular2/src/core/compiler/view_ref.ts b/modules/angular2/src/core/compiler/view_ref.ts index 6d73a2781f..5cee4e0449 100644 --- a/modules/angular2/src/core/compiler/view_ref.ts +++ b/modules/angular2/src/core/compiler/view_ref.ts @@ -13,21 +13,31 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro return isPresent(protoViewRef) ? protoViewRef._protoView : null; } -export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; } +/** + * Represents the View of a {@link Component} that was compiled via {@link Compiler#compileInHost + */ +export interface HostViewRef { + /** + * @private + */ + changeDetectorRef: ChangeDetectorRef; +} /** - * A reference to an Angular View. + * Represents an Angular View. * - * A View is a fundamental building block of Application UI. A View is the smallest set of - * elements which are created and destroyed together. A View can change properties on the elements - * within the view, but it can not change the structure of those elements. + * + * A View is a fundamental building block of the application UI. It is the smallest grouping of + * Elements which are created and destroyed together. * - * To change structure of the elements, the Views can contain zero or more {@link ViewContainerRef}s - * which allow the views to be nested. + * Properties of elements in a View can change, but the structure (number and order) of elements in + * a View cannot. Changing the structure of elements can only be done by inserting, moving or + * removing nested Views via a View Container. Each View can contain many View Containers. + * * * ## Example * - * Given this template + * Given this template... * * ``` * Count: {{items.length}} @@ -36,9 +46,9 @@ export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; } * * ``` * - * The above example we have two {@link ProtoViewRef}s: + * ... we have two {@link ProtoViewRef}s: * - * Outter {@link ProtoViewRef}: + * Outer {@link ProtoViewRef}: * ``` * Count: {{items.length}} *
    @@ -53,7 +63,7 @@ export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; } * * Notice that the original template is broken down into two separate {@link ProtoViewRef}s. * - * The outter/inner {@link ProtoViewRef}s are then assembled into views like so: + * The outer/inner {@link ProtoViewRef}s are then assembled into views like so: * * ``` * @@ -85,6 +95,8 @@ export class ViewRef implements HostViewRef { get renderFragment(): RenderFragmentRef { return this._view.renderFragment; } /** + * @private + * * Return `ChangeDetectorRef` */ get changeDetectorRef(): ChangeDetectorRef { @@ -107,13 +119,14 @@ export class ViewRef implements HostViewRef { } /** - * A reference to an Angular ProtoView. + * Represents Angular's ProtoView. * - * A ProtoView is a reference to a template for easy creation of views. - * (See {@link AppViewManager#createViewInContainer `AppViewManager#createViewInContainer`} and + * A ProtoView is a prototypical View that is the result of Template compilation and enables + * Angular to efficiently create an instance of a View based on the compiled Template. + * + * A ProtoView is created {@link AppViewManager#createViewInContainer} and * {@link AppViewManager#createRootHostView `AppViewManager#createRootHostView`}). * - * A `ProtoView` is a factory for creating `View`s. * * ## Example * @@ -128,7 +141,7 @@ export class ViewRef implements HostViewRef { * * The above example we have two {@link ProtoViewRef}s: * - * Outter {@link ProtoViewRef}: + * Outer {@link ProtoViewRef}: * ``` * Count: {{items.length}} *