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

chore(docs): adding docs to core.ts and annotations.ts

Browse Source
This commit is contained in:
Misko Hevery
2015-07-07 08:15:58 +02:00
committed by Alex Eagle
parent 12a427e158
commit 3ab8a0c438
22 changed files with 870 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
modules/angular2/src/core/compiler/compiler.ts
View File

@ -60,6 +60,26 @@ export class CompilerCache {
}
/**
*
* ## URL Resolution
*
* ```
* var appRootUrl: AppRootUrl = ...;
* var componentUrlMapper: ComponentUrlMapper = ...;
* var urlResolver: UrlResolver = ...;
*
* var componentType: Type = ...;
* var componentAnnotation: ComponentAnnotation = ...;
* var viewAnnotation: ViewAnnotation = ...;
*
* // Resolving a URL
*
* var url = viewAnnotation.templateUrl;
* var componentUrl = componentUrlMapper.getUrl(componentType);
* var componentResolvedUrl = urlResolver.resolve(appRootUrl.value, componentUrl);
* var templateResolvedUrl = urlResolver.resolve(componetResolvedUrl, url);
* ```
*
* @exportedAs angular2/view
*/
@Injectable()
@ -74,6 +94,9 @@ export class Compiler {
private _render: renderApi.RenderCompiler;
private _protoViewFactory: ProtoViewFactory;
/**
* @private
*/
constructor(reader: DirectiveResolver, cache: CompilerCache, viewResolver: ViewResolver,
componentUrlMapper: ComponentUrlMapper, urlResolver: UrlResolver,
render: renderApi.RenderCompiler, protoViewFactory: ProtoViewFactory,
@ -112,7 +135,7 @@ export class Compiler {
if (isPresent(hostAppProtoView)) {
hostPvPromise = PromiseWrapper.resolve(hostAppProtoView);
} else {
var componentBinding = this._bindDirective(componentTypeOrBinding);
var componentBinding: DirectiveBinding = this._bindDirective(componentTypeOrBinding);
Compiler._assertTypeIsComponent(componentBinding);
var directiveMetadata = componentBinding.metadata;

17
modules/angular2/src/core/compiler/component_url_mapper.ts
View File

@ -2,12 +2,21 @@ import {Injectable} from 'angular2/di';
import {Type, isPresent} from 'angular2/src/facade/lang';
import {Map, MapWrapper} from 'angular2/src/facade/collection';
/**
* Resolve a {@link Type} from a {@link Component} into a URL.
*
* This interface can be overridden by the application developer to create custom behavior.
*
* See {@link Compiler}
*/
@Injectable()
export class ComponentUrlMapper {
// Returns the base URL to the component source file.
// The returned URL could be:
// - an absolute URL,
// - a path relative to the application
/**
* Returns the base URL to the component source file.
* The returned URL could be:
* - an absolute URL,
* - a path relative to the application
*/
getUrl(component: Type): string { return './'; }
}

10
modules/angular2/src/core/compiler/directive_resolver.ts
View File

@ -3,8 +3,18 @@ import {Type, isPresent, BaseException, stringify} from 'angular2/src/facade/lan
import {Directive} from '../annotations_impl/annotations';
import {reflector} from 'angular2/src/reflection/reflection';
/**
* Resolve a {@link Type} for {@link Directive}.
*
* This interface can be overridden by the application developer to create custom behavior.
*
* See {@link Compiler}
*/
@Injectable()
export class DirectiveResolver {
/**
* Return {@link Directive} for a given {@link Type}.
*/
resolve(type: Type): Directive {
var annotations = reflector.annotations(resolveForwardRef(type));
if (isPresent(annotations)) {

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

@ -26,8 +26,9 @@ export class DynamicComponentLoader {
constructor(private _compiler: Compiler, private _viewManager: AppViewManager) {}
/**
* Loads a root component that is placed at the first element that matches the
* component's selector.
* Loads a root component that is placed at the first element that matches the component's
* selector.
*
* The loaded component receives injection normally as a hosted view.
*/
loadAsRoot(typeOrBinding: Type | Binding, overrideSelector: string,

42
modules/angular2/src/core/compiler/element_ref.ts
View File

@ -3,20 +3,54 @@ import {ViewRef} from './view_ref';
import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/render/api';
/**
* Reference to the element.
*
* Represents an opeque refference to the underlying element. The element is a DOM ELement in
* a Browser, 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.
*
* @exportedAs angular2/view
*/
export class ElementRef implements RenderElementRef {
constructor(public parentView: ViewRef, public boundElementIndex: number,
private _renderer: Renderer) {}
/**
* Reference to the {@link ViewRef} where the `ElementRef` is inside of.
*/
parentView: ViewRef;
/**
* Index of the element inside the {@link ViewRef}.
*
* This is used internally by the Angular framework to locate elements.
*/
boundElementIndex: number;
constructor(parentView: ViewRef, boundElementIndex: number, private _renderer: Renderer) {
this.parentView = parentView;
this.boundElementIndex = boundElementIndex;
}
/**
*
*/
get renderView(): RenderViewRef { return this.parentView.render; }
// TODO(tbosch): remove this once Typescript supports declaring interfaces
// that contain getters
// https://github.com/Microsoft/TypeScript/issues/3745
set renderView(viewRef: RenderViewRef) { throw new BaseException('Abstract setter'); }
/**
* Exposes the underlying native element.
* Attention: This won't work in a webworker scenario!
* Returns the native Element implementation.
*
* 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 WebWorkers.
*
* NOTE: This method will return null in the webworker scenario!
*/
get nativeElement(): any { return this._renderer.getNativeElementSync(this); }
}

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

@ -155,6 +155,9 @@ class BindingRecordsCreator {
@Injectable()
export class ProtoViewFactory {
/**
* @private
*/
constructor(public _changeDetection: ChangeDetection) {}
createAppProtoViews(hostComponentBinding: DirectiveBinding,

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

@ -30,7 +30,7 @@ export class AppViewContainer {
}
/**
* Const of making objects: http://jsperf.com/instantiate-size-of-object
* Cost of making objects: http://jsperf.com/instantiate-size-of-object
*
*/
export class AppView implements ChangeDispatcher, EventDispatcher {

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

@ -16,27 +16,48 @@ import {AppViewListener} from './view_listener';
*/
@Injectable()
export class AppViewManager {
/**
* @private
*/
constructor(public _viewPool: AppViewPool, public _viewListener: AppViewListener,
public _utils: AppViewManagerUtils, public _renderer: Renderer) {}
/**
* Returns associated Component {@link ViewRef} from {@link ElementRef}.
*
* If an {@link ElementRef} is from an element which has a component, this method returns
* the component's {@link ViewRef}.
*/
getComponentView(hostLocation: ElementRef): ViewRef {
var hostView = internalView(hostLocation.parentView);
var hostView: viewModule.AppView = internalView(hostLocation.parentView);
var boundElementIndex = hostLocation.boundElementIndex;
return hostView.componentChildViews[boundElementIndex].ref;
}
/**
* Returns a {@link ViewContainerRef} at the {@link ElementRef} location.
*/
getViewContainer(location: ElementRef): ViewContainerRef {
var hostView = internalView(location.parentView);
return hostView.elementInjectors[location.boundElementIndex].getViewContainerRef();
}
/**
* Return the first child element of the host element view.
*/
// TODO(misko): remove https://github.com/angular/angular/issues/2891
getHostElement(hostViewRef: ViewRef): ElementRef {
return internalView(hostViewRef).elementRefs[0];
}
/**
* Returns an ElementRef for the element with the given variable name
* in the component view of the component at the provided ElementRef.
* in the current view.
*
* - `hostLocation`: {@link ElementRef} of any element in the View which defines the scope of
* search.
* - `variableName`: Name of the variable to locate.
* - Returns {@link ElementRef} of the found element or null. (Throws if not found.)
*/
getNamedElementInComponentView(hostLocation: ElementRef, variableName: string): ElementRef {
var hostView = internalView(hostLocation.parentView);
@ -52,15 +73,75 @@ export class AppViewManager {
return componentView.elementRefs[elementIndex];
}
/**
* Returns the component instance for a given element.
*
* The component is the execution context as seen by an expression at that {@link ElementRef}
* location.
*/
getComponent(hostLocation: ElementRef): any {
var hostView = internalView(hostLocation.parentView);
var boundElementIndex = hostLocation.boundElementIndex;
return this._utils.getComponentInstance(hostView, boundElementIndex);
}
/**
* Load component view into existing element.
*
* Use this if a host element is already in the DOM and it is necessary to upgrade
* the element into Angular component by attaching a view but reusing the existing element.
*
* - `hostProtoViewRef`: {@link ProtoViewRef} Proto view to use in creating a view for this
* component.
* - `overrideSelector`: (optional) selector to use in locating the existing element to load
* the view into. If not specified use the selector in the component definition of the
* `hostProtoView`.
* - injector: {@link Injector} to use as parent injector for the view.
*
* See {@link AppViewManager#destroyRootHostView}.
*
* ## Example
*
* ```
* @ng.Component({
* selector: 'child-component'
* })
* @ng.View({
* template: 'Child'
* })
* class ChildComponent {
*
* }
*
* @ng.Component({
* selector: 'my-app'
* })
* @ng.View({
* template: `
* Parent (<some-component></some-component>)
* `
* })
* class MyApp {
* viewRef: ng.ViewRef;
*
* constructor(public appViewManager: ng.AppViewManager, compiler: ng.Compiler) {
* compiler.compileInHost(ChildComponent).then((protoView: ng.ProtoViewRef) => {
* this.viewRef = appViewManager.createRootHostView(protoView, 'some-component', null);
* })
* }
*
* onDestroy() {
* this.appViewManager.destroyRootHostView(this.viewRef);
* this.viewRef = null;
* }
* }
*
* ng.bootstrap(MyApp);
* ```
*/
createRootHostView(hostProtoViewRef: ProtoViewRef, overrideSelector: string,
injector: Injector): ViewRef {
var hostProtoView = internalProtoView(hostProtoViewRef);
var hostProtoView: viewModule.AppProtoView = internalProtoView(hostProtoViewRef);
var hostElementSelector = overrideSelector;
if (isBlank(hostElementSelector)) {
hostElementSelector = hostProtoView.elementBinders[0].componentDirective.metadata.selector;
@ -77,6 +158,9 @@ export class AppViewManager {
return hostView.ref;
}
/**
* Remove the View created with {@link AppViewManager#createRootHostView}.
*/
destroyRootHostView(hostViewRef: ViewRef) {
// Note: Don't detach the hostView as we want to leave the
// root element in place. Also don't put the hostView into the view pool
@ -88,6 +172,10 @@ export class AppViewManager {
this._viewListener.viewDestroyed(hostView);
}
/**
*
* See {@link AppViewManager#destroyViewInContainer}.
*/
createViewInContainer(viewContainerLocation: ElementRef, atIndex: number,
protoViewRef: ProtoViewRef, context: ElementRef = null,
bindings: ResolvedBinding[] = null): ViewRef {
@ -112,12 +200,20 @@ export class AppViewManager {
return view.ref;
}
/**
*
* See {@link AppViewManager#createViewInContainer}.
*/
destroyViewInContainer(viewContainerLocation: ElementRef, atIndex: number) {
var parentView = internalView(viewContainerLocation.parentView);
var boundElementIndex = viewContainerLocation.boundElementIndex;
this._destroyViewInContainer(parentView, boundElementIndex, atIndex);
}
/**
*
* See {@link AppViewManager#detachViewInContainer}.
*/
attachViewInContainer(viewContainerLocation: ElementRef, atIndex: number,
viewRef: ViewRef): ViewRef {
var view = internalView(viewRef);
@ -134,6 +230,10 @@ export class AppViewManager {
return viewRef;
}
/**
*
* See {@link AppViewManager#attachViewInContainer}.
*/
detachViewInContainer(viewContainerLocation: ElementRef, atIndex: number): ViewRef {
var parentView = internalView(viewContainerLocation.parentView);
var boundElementIndex = viewContainerLocation.boundElementIndex;

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

@ -13,19 +13,115 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro
}
/**
* A reference to an Angular View.
*
* A View is a fundemental building block of Application UI. A View is the smallest set of
* elements which are created and destroyed together. A View can chane properties on the elements
* within the view, but it can not change the structure of those elements.
*
* To change structure of the elements, the Views can contain zero or more {@link ViewContainerRef}s
* which allow the views to be nested.
*
* ## Example
*
* Given this template
*
* ```
* Count: {{items.length}}
* <ul>
* <li *ng-for="var item of items">{{item}}</li>
* </ul>
* ```
*
* The above example we have two {@link ProtoViewRef}s:
*
* Outter {@link ProtoViewRef}:
* ```
* Count: {{items.length}}
* <ul>
* <template ng-for var-item [ng-for-of]="items"></template>
* </ul>
* ```
*
* Inner {@link ProtoViewRef}:
* ```
* <li>{{item}}</li>
* ```
*
* Notice that the original template is broken down into two separet {@link ProtoViewRef}s.
*
* The outter/inner {@link ProtoViewRef}s are then assambled into views like so:
*
* ```
* <!-- ViewRef: outter-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 -->
* ```
*
* @exportedAs angular2/view
*/
export class ViewRef {
constructor(public _view: viewModule.AppView) {}
/**
* Return {@link RenderViewRef}
*/
get render(): RenderViewRef { return this._view.render; }
/**
* Set local variable for a view.
*
*
*/
setLocal(contextName: string, value: any): void { this._view.setLocal(contextName, value); }
}
/**
* A reference to an an Angular ProtoView.
*
* A ProtoView is a reference to a template for easy creation of views.
* (See {@link AppViewManager#createViewInContainer} and {@link AppViewManager#createRootHostView}).
*
* A `ProtoView` is a foctary for creating `View`s.
*
* ## Example
*
* Given this template
*
* ```
* Count: {{items.length}}
* <ul>
* <li *ng-for="var item of items">{{item}}</li>
* </ul>
* ```
*
* The above example we have two {@link ProtoViewRef}s:
*
* Outter {@link ProtoViewRef}:
* ```
* Count: {{items.length}}
* <ul>
* <template ng-for var-item [ng-for-of]="items"></template>
* </ul>
* ```
*
* Inner {@link ProtoViewRef}:
* ```
* <li>{{item}}</li>
* ```
*
* Notice that the original template is broken down into two separet {@link ProtoViewRef}s.
*
* @exportedAs angular2/view
*/
export class ProtoViewRef {
/**
* @private
*/
constructor(public _protoView: viewModule.AppProtoView) {}
}