cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(docs): added more docs for core.ts

Browse Source
This commit is contained in:
Misko Hevery
2015-07-11 17:26:48 +02:00
parent 0906ee8a4e
commit c83a3f3372
48 changed files with 414 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
modules/angular2/src/core/compiler/dynamic_component_loader.ts
View File

@ -4,12 +4,41 @@ import {Type, BaseException, stringify, isPresent} from 'angular2/src/facade/lan
import {Promise} from 'angular2/src/facade/async';
import {AppViewManager} from 'angular2/src/core/compiler/view_manager';
import {ElementRef} from './element_ref';
import {ViewRef} from './view_ref';
import {ViewRef, HostViewRef} from './view_ref';
/**
* Angular's reference to a component instance.
*
* `ComponentRef` represents a component instance lifecycle and meta information.
*/
export class ComponentRef {
constructor(public location: ElementRef, public instance: any, public dispose: Function) {}
/**
* Location of the component host element.
*/
location: ElementRef;
get hostView(): ViewRef { return this.location.parentView; }
/**
* Instance of component.
*/
instance: any;
/**
* @private
*/
constructor(location: ElementRef, instance: any, private _dispose: () => void) {
this.location = location;
this.instance = instance;
}
/**
* Returns the host {@link ViewRef}.
*/
get hostView(): HostViewRef { return this.location.parentView; }
/**
* Dispose of the component instance.
*/
dispose() { this._dispose(); }
}
/**
@ -24,7 +53,56 @@ export class DynamicComponentLoader {
* Loads a root component that is placed at the first element that matches the component's
* selector.
*
* - `typeOrBinding` {@link Type} \ {@link Binding} - representing the component to load.
* - `overrideSelector` (optional) selector to load the component at (or use
* `@Component.selector`) The selector can be anywhere (i.e. outside the current component.)
* - `injector` {@link Injector} - optional injector to use for the component.
*
* The loaded component receives injection normally as a hosted view.
*
*
* ## Example
*
* ```
* @ng.Component({
* selector: 'child-component'
* })
* @ng.View({
* template: 'Child'
* })
* class ChildComponent {
* }
*
*
*
* @ng.Component({
* selector: 'my-app'
* })
* @ng.View({
* template: `
* Parent (<child id="child"></child>)
* `
* })
* class MyApp {
* constructor(dynamicComponentLoader: ng.DynamicComponentLoader, injector: ng.Injector) {
* dynamicComponentLoader.loadAsRoot(ChildComponent, '#child', injector);
* }
* }
*
* ng.bootstrap(MyApp);
* ```
*
* Resulting DOM:
*
* ```
* <my-app>
* Parent (
* <child id="child">
* Child
* </child>
* )
* </my-app>
* ```
*/
loadAsRoot(typeOrBinding: Type | Binding, overrideSelector: string,
injector: Injector): Promise<ComponentRef> {
@ -41,10 +119,51 @@ export class DynamicComponentLoader {
}
/**
* Loads a component into the component view of the provided ElementRef
* next to the element with the given name
* The loaded component receives
* injection normally as a hosted view.
* Loads a component into the component view of the provided ElementRef next to the element
* with the given name.
*
* The loaded component receives injection normally as a hosted view.
*
* ## Example
*
* ```
* @ng.Component({
* selector: 'child-component'
* })
* @ng.View({
* template: 'Child'
* })
* class ChildComponent {
* }
*
*
* @ng.Component({
* selector: 'my-app'
* })
* @ng.View({
* template: `
* Parent (<div #child></div>)
* `
* })
* class MyApp {
* constructor(dynamicComponentLoader: ng.DynamicComponentLoader, elementRef: ng.ElementRef) {
* dynamicComponentLoader.loadIntoLocation(ChildComponent, elementRef, 'child');
* }
* }
*
* ng.bootstrap(MyApp);
* ```
*
* Resulting DOM:
*
* ```
* <my-app>
* Parent (
* <div #child="" class="ng-binding"></div>
* <child-component class="ng-binding">Child</child-component>
* )
* </my-app>
* ```
*/
loadIntoLocation(typeOrBinding: Type | Binding, hostLocation: ElementRef, anchorName: string,
bindings: ResolvedBinding[] = null): Promise<ComponentRef> {
@ -54,8 +173,45 @@ export class DynamicComponentLoader {
}
/**
* Loads a component next to the provided ElementRef. The loaded component receives
* injection normally as a hosted view.
* Loads a component next to the provided ElementRef.
*
* The loaded component receives injection normally as a hosted view.
*
*
* ## Example
*
* ```
* @ng.Component({
* selector: 'child-component'
* })
* @ng.View({
* template: 'Child'
* })
* class ChildComponent {
* }
*
*
* @ng.Component({
* selector: 'my-app'
* })
* @ng.View({
* template: `Parent`
* })
* class MyApp {
* constructor(dynamicComponentLoader: ng.DynamicComponentLoader, elementRef: ng.ElementRef) {
* dynamicComponentLoader.loadIntoLocation(ChildComponent, elementRef, 'child');
* }
* }
*
* ng.bootstrap(MyApp);
* ```
*
* Resulting DOM:
*
* ```
* <my-app>Parent</my-app>
* <child-component>Child</child-component>
* ```
*/
loadNextToLocation(typeOrBinding: Type | Binding, location: ElementRef,
bindings: ResolvedBinding[] = null): Promise<ComponentRef> {
@ -68,7 +224,7 @@ export class DynamicComponentLoader {
var component = this._viewManager.getComponent(newLocation);
var dispose = () => {
var index = viewContainer.indexOf(hostViewRef);
var index = viewContainer.indexOf(<ViewRef>hostViewRef);
if (index !== -1) {
viewContainer.remove(index);
}

2
modules/angular2/src/core/compiler/element_binder.ts
View File

@ -1,4 +1,4 @@
import {AST} from 'angular2/change_detection';
import {AST} from 'angular2/src/change_detection/change_detection';
import {isBlank, isPresent, BaseException} from 'angular2/src/facade/lang';
import * as eiModule from './element_injector';
import {DirectiveBinding} from './element_injector';

6
modules/angular2/src/core/compiler/element_injector.ts
View File

@ -43,7 +43,11 @@ import {ElementRef} from './element_ref';
import {TemplateRef} from './template_ref';
import {Directive, Component, LifecycleEvent} from 'angular2/src/core/annotations_impl/annotations';
import {hasLifecycleHook} from './directive_lifecycle_reflector';
import {ChangeDetector, ChangeDetectorRef, Pipes} from 'angular2/change_detection';
import {
ChangeDetector,
ChangeDetectorRef,
Pipes
} from 'angular2/src/change_detection/change_detection';
import {QueryList} from './query_list';
import {reflector} from 'angular2/src/reflection/reflection';
import {DirectiveMetadata} from 'angular2/src/render/api';

2
modules/angular2/src/core/compiler/proto_view_factory.ts
View File

@ -13,7 +13,7 @@ import {
DEFAULT,
ChangeDetectorDefinition,
ASTWithSource
} from 'angular2/change_detection';
} from 'angular2/src/change_detection/change_detection';
import * as renderApi from 'angular2/src/render/api';
import {AppProtoView} from './view';

2
modules/angular2/src/core/compiler/view.ts
View File

@ -16,7 +16,7 @@ import {
DirectiveRecord,
DirectiveIndex,
ChangeDetectorRef
} from 'angular2/change_detection';
} from 'angular2/src/change_detection/change_detection';
import {
ProtoElementInjector,

53
modules/angular2/src/core/compiler/view_container_ref.ts
View File

@ -7,9 +7,19 @@ import * as viewModule from './view';
import {ElementRef} from './element_ref';
import {TemplateRef} from './template_ref';
import {ViewRef, ProtoViewRef, internalView} from './view_ref';
import {ViewRef, HostViewRef, ProtoViewRef, internalView} from './view_ref';
/**
* A location where {@link ViewRef}s 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.
*/
export class ViewContainerRef {
/**
* @private
*/
constructor(public viewManager: avmModule.AppViewManager, public element: ElementRef) {}
private _getViews(): List<viewModule.AppView> {
@ -17,16 +27,39 @@ export class ViewContainerRef {
return isPresent(vc) ? vc.views : [];
}
/**
* Remove all {@link ViewRef}s at current location.
*/
clear(): void {
for (var i = this.length - 1; i >= 0; i--) {
this.remove(i);
}
}
/**
* Return a {@link ViewRef} at specific index.
*/
get(index: number): ViewRef { return this._getViews()[index].ref; }
/**
* Returns number of {@link ViewRef}s currently attached at this location.
*/
get length(): number { return this._getViews().length; }
/**
* Create and insert a {@link ViewRef} into the view-container.
*
* - `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`.
*
* Returns newly created {@link ViewRef}.
*/
// TODO(rado): profile and decide whether bounds checks should be added
// to the methods below.
createEmbeddedView(templateRef: TemplateRef, atIndex: number = -1): ViewRef {
@ -35,21 +68,37 @@ export class ViewContainerRef {
}
createHostView(protoViewRef: ProtoViewRef = null, atIndex: number = -1,
dynamicallyCreatedBindings: ResolvedBinding[] = null): ViewRef {
dynamicallyCreatedBindings: ResolvedBinding[] = null): HostViewRef {
if (atIndex == -1) atIndex = this.length;
return this.viewManager.createHostViewInContainer(this.element, atIndex, protoViewRef,
dynamicallyCreatedBindings);
}
/**
* Insert a {@link ViewRef} at specefic index.
*
* The index is location at which the {@link ViewRef} should be attached. If omitted it is
* inserted at the end.
*
* Returns the inserted {@link ViewRef}.
*/
insert(viewRef: ViewRef, atIndex: number = -1): ViewRef {
if (atIndex == -1) atIndex = this.length;
return this.viewManager.attachViewInContainer(this.element, atIndex, viewRef);
}
/**
* Return the index of already inserted {@link ViewRef}.
*/
indexOf(viewRef: ViewRef): number {
return ListWrapper.indexOf(this._getViews(), internalView(viewRef));
}
/**
* Remove a {@link ViewRef} at specific index.
*
* If the index is omitted last {@link ViewRef} is removed.
*/
remove(atIndex: number = -1): void {
if (atIndex == -1) atIndex = this.length - 1;
this.viewManager.destroyViewInContainer(this.element, atIndex);

14
modules/angular2/src/core/compiler/view_manager.ts
View File

@ -2,7 +2,7 @@ import {Injector, Binding, Injectable, ResolvedBinding} from 'angular2/di';
import {isPresent, isBlank, BaseException} from 'angular2/src/facade/lang';
import * as viewModule from './view';
import {ElementRef} from './element_ref';
import {ProtoViewRef, ViewRef, internalView, internalProtoView} from './view_ref';
import {ProtoViewRef, ViewRef, HostViewRef, internalView, internalProtoView} from './view_ref';
import {ViewContainerRef} from './view_container_ref';
import {TemplateRef} from './template_ref';
import {
@ -40,8 +40,8 @@ export class AppViewManager {
/**
* Return the first child element of the host element view.
*/
getHostElement(hostViewRef: ViewRef): ElementRef {
var hostView = internalView(hostViewRef);
getHostElement(hostViewRef: HostViewRef): ElementRef {
var hostView = internalView(<ViewRef>hostViewRef);
if (hostView.proto.type !== ViewType.HOST) {
throw new BaseException('This operation is only allowed on host views');
}
@ -138,7 +138,7 @@ export class AppViewManager {
* ```
*/
createRootHostView(hostProtoViewRef: ProtoViewRef, overrideSelector: string,
injector: Injector): ViewRef {
injector: Injector): HostViewRef {
var hostProtoView: viewModule.AppProtoView = internalProtoView(hostProtoViewRef);
var hostElementSelector = overrideSelector;
if (isBlank(hostElementSelector)) {
@ -158,10 +158,10 @@ export class AppViewManager {
/**
* Remove the View created with {@link AppViewManager#createRootHostView}.
*/
destroyRootHostView(hostViewRef: ViewRef) {
destroyRootHostView(hostViewRef: HostViewRef) {
// Note: Don't put the hostView into the view pool
// as it is depending on the element for which it was created.
var hostView = internalView(hostViewRef);
var hostView = internalView(<ViewRef>hostViewRef);
this._renderer.detachFragment(hostView.renderFragment);
this._renderer.dehydrateView(hostView.render);
this._viewDehydrateRecurse(hostView);
@ -189,7 +189,7 @@ export class AppViewManager {
*/
createHostViewInContainer(viewContainerLocation: ElementRef, atIndex: number,
protoViewRef: ProtoViewRef,
imperativelyCreatedInjector: ResolvedBinding[]): ViewRef {
imperativelyCreatedInjector: ResolvedBinding[]): HostViewRef {
var protoView = internalProtoView(protoViewRef);
if (protoView.type !== ViewType.HOST) {
throw new BaseException('This method can only be called with host ProtoViews!');

2
modules/angular2/src/core/compiler/view_manager_utils.ts
View File

@ -8,7 +8,7 @@ import * as avmModule from './view_manager';
import {ElementRef} from './element_ref';
import {TemplateRef} from './template_ref';
import {Renderer, RenderViewWithFragments} from 'angular2/src/render/api';
import {Locals} from 'angular2/change_detection';
import {Locals} from 'angular2/src/change_detection/change_detection';
import {RenderViewRef, RenderFragmentRef, ViewType} from 'angular2/src/render/api';
@Injectable()

16
modules/angular2/src/core/compiler/view_ref.ts
View File

@ -12,6 +12,8 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro
return isPresent(protoViewRef) ? protoViewRef._protoView : null;
}
export interface HostViewRef {}
/**
* A reference to an Angular View.
*
@ -53,17 +55,20 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro
* The outter/inner {@link ProtoViewRef}s are then assembled into views like so:
*
* ```
* <!-- ViewRef: outter-0 -->
* <!-- ViewRef: outer-0 -->
* Count: 2
* <ul>
* <template view-container-ref></template>
* <!-- ViewRef: inner-1 --><li>first</li><!-- /ViewRef: inner-1 -->
* <!-- ViewRef: inner-2 --><li>second</li><!-- /ViewRef: inner-2 -->
* </ul>
* <!-- /ViewRef: outter-0 -->
* <!-- /ViewRef: outer-0 -->
* ```
*/
export class ViewRef {
export class ViewRef implements HostViewRef {
/**
* @private
*/
constructor(public _view: viewModule.AppView) {}
/**
@ -77,9 +82,10 @@ export class ViewRef {
get renderFragment(): RenderFragmentRef { return this._view.renderFragment; }
/**
* Set local variable for a view.
*
* Set local variable in a view.
*
* - `contextName` - Name of the local variable in a view.
* - `value` - Value for the local variable in a view.
*/
setLocal(contextName: string, value: any): void { this._view.setLocal(contextName, value); }
}