Skip to content

Commit af9f916

Browse files
IgorMinarIgorMinar
committed
docs(compiler): compiler/view related api docs
Closes angular#4268
1 parent d348e50 commit af9f916

8 files changed

Lines changed: 209 additions & 124 deletions

File tree

‎modules/angular2/src/core/compiler/compiler.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,11 @@ export class CompilerCache {
9191
* ```
9292
*/
9393
/**
94-
* Service for compiling {@link Component}s so that they can be later instantiated and their
95-
* {@link View}s can be rendered.
94+
* Low-level service for compiling {@link Component}s into {@link ProtoViewRef ProtoViews}s, which
95+
* can later be used to create and render a Component instance.
9696
*
97-
* <!-- TODO: check Component and View links, they should likely go to glossary instead -->
97+
* Most applications should instead use higher-level {@link DynamicComponentLoader} service, which
98+
* both compiles and instantiates a Component.
9899
*/
99100
@Injectable()
100101
export class Compiler {
@@ -133,8 +134,10 @@ export class Compiler {
133134
}
134135

135136
/**
136-
* Compiles an {@link EntryPointComponent entry-point Component} and returns a promise for a
137-
* {@link ProtoViewRef} that can be passed into {@link AppViewManager
137+
* Compiles a {@link Component} and returns a promise for this component's {@link ProtoViewRef}.
138+
*
139+
* Returns `ProtoViewRef` that can be later used to instantiate a component via
140+
* {@link ViewContainerRef#createHostView} or {@link AppViewManager#createHostViewInContainer}.
138141
*/
139142
compileInHost(componentType: Type): Promise<ProtoViewRef> {
140143
var r = wtfStartTimeRange('Compiler#compile()', stringify(componentType));

‎modules/angular2/src/core/compiler/dynamic_component_loader.ts‎

Lines changed: 71 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,44 @@ import {ElementRef} from './element_ref';
77
import {ViewRef, HostViewRef} from './view_ref';
88

99
/**
10-
* Represents a component instance as a node in application's component tree and provides access to
11-
* other objects related to this component instance.
10+
* Represents an instance of a Component created via {@link DynamicComponentLoader}.
11+
*
12+
* `ComponentRef` provides access to the Component Instance as well other objects related to this
13+
* Component Instance and allows you to destroy the Component Instance via the {@link #dispose}
14+
* method.
1215
*/
1316
export class ComponentRef {
1417
/**
15-
* Location of the component host element.
18+
* Location of the Host Element of this Component Instance.
1619
*/
1720
location: ElementRef;
1821

1922
/**
20-
* Instance of component.
23+
* The instance of the Component.
2124
*/
2225
instance: any;
2326

27+
/**
28+
* The user defined component type, represented via the constructor function.
29+
*
30+
* <!-- TODO: customize wording for Dart docs -->
31+
*/
2432
componentType: Type;
2533

34+
/**
35+
* @private
36+
*
37+
* The injector provided {@link DynamicComponentLoader#loadAsRoot}.
38+
*
39+
* TODO(i): this api is useless and should be replaced by an injector retrieved from
40+
* the HostElementRef, which is currently not possible.
41+
*/
2642
injector: Injector;
2743

2844
/**
2945
* @private
46+
*
47+
* TODO(i): refactor into public/private fields
3048
*/
3149
constructor(location: ElementRef, instance: any, componentType: Type, injector: Injector,
3250
private _dispose: () => void) {
@@ -37,42 +55,61 @@ export class ComponentRef {
3755
}
3856

3957
/**
40-
* Returns the host {@link ViewRef}.
58+
* The {@link ViewRef} of the Host View of this Component instance.
4159
*/
4260
get hostView(): HostViewRef { return this.location.parentView; }
4361

62+
/**
63+
* @private
64+
*
65+
* Returns the type of this Component instance.
66+
*
67+
* TODO(i): this api should be removed
68+
*/
4469
get hostComponentType(): Type { return this.componentType; }
4570

71+
/**
72+
* @private
73+
*
74+
* The instance of the component.
75+
*
76+
* TODO(i): this api should be removed
77+
*/
4678
get hostComponent(): any { return this.instance; }
4779

4880
/**
49-
* Dispose of the component instance.
81+
* Destroys the component instance and all of the data structures associated with it.
82+
*
83+
* TODO(i): rename to destroy to be consistent with AppViewManager and ViewContainerRef
5084
*/
5185
dispose() { this._dispose(); }
5286
}
5387

5488
/**
55-
* Service for creating an instance of a component and attaching it to the component tree of an
56-
* application at a specified location.
89+
* Service for instantiating a Component and attaching it to a View at a specified location.
5790
*/
5891
@Injectable()
5992
export class DynamicComponentLoader {
60-
6193
/**
6294
* @private
6395
*/
6496
constructor(private _compiler: Compiler, private _viewManager: AppViewManager) {}
6597

6698
/**
67-
* Loads a root component that is placed at the first element that matches the component's
68-
* selector.
99+
* Creates an instance of a Component `type` and attaches it to the first element in the
100+
* platform-specific global view that matches the component's selector.
101+
*
102+
* In a browser the platform-specific global view is the main DOM Document.
69103
*
70-
* - `typeOrBinding` `Type` - representing the component to load.
71-
* - `overrideSelector` (optional) selector to load the component at (or use
72-
* `@Component.selector`) The selector can be anywhere (i.e. outside the current component.)
73-
* - `injector` {@link Injector} - optional injector to use for the component.
104+
* If needed, the component's selector can be overridden via `overrideSelector`.
74105
*
75-
* The loaded component receives injection normally as a hosted view.
106+
* You can optionally provide `injector` and this {@link Injector} will be used to instantiate the
107+
* Component.
108+
*
109+
* To be notified when this Component instance is destroyed, you can also optionally provide
110+
* `onDispose` callback.
111+
*
112+
* Returns a promise for the {@link ComponentRef} representing the newly created Component.
76113
*
77114
*
78115
* ## Example
@@ -137,10 +174,18 @@ export class DynamicComponentLoader {
137174
}
138175

139176
/**
140-
* Loads a component into the component view of the provided ElementRef next to the element
141-
* with the given name.
177+
* Creates an instance of a Component and attaches it to a View Container located inside of the
178+
* Component View of another Component instance.
179+
*
180+
* The targeted Component Instance is specified via its `hostLocation` {@link ElementRef}. The
181+
* location within the Component View of this Component Instance is specified via `anchorName`
182+
* Template Variable Name.
183+
*
184+
* You can optionally provide `bindings` to configure the {@link Injector} provisioned for this
185+
* Component Instance.
186+
*
187+
* Returns a promise for the {@link ComponentRef} representing the newly created Component.
142188
*
143-
* The loaded component receives injection normally as a hosted view.
144189
*
145190
* ## Example
146191
*
@@ -190,9 +235,13 @@ export class DynamicComponentLoader {
190235
}
191236

192237
/**
193-
* Loads a component next to the provided ElementRef.
238+
* Creates an instance of a Component and attaches it to the View Container found at the
239+
* `location` specified as {@link ElementRef}.
240+
*
241+
* You can optionally provide `bindings` to configure the {@link Injector} provisioned for this
242+
* Component Instance.
194243
*
195-
* The loaded component receives injection normally as a hosted view.
244+
* Returns a promise for the {@link ComponentRef} representing the newly created Component.
196245
*
197246
*
198247
* ## Example
@@ -216,7 +265,7 @@ export class DynamicComponentLoader {
216265
* })
217266
* class MyApp {
218267
* constructor(dynamicComponentLoader: ng.DynamicComponentLoader, elementRef: ng.ElementRef) {
219-
* dynamicComponentLoader.loadIntoLocation(ChildComponent, elementRef, 'child');
268+
* dynamicComponentLoader.loadNextToLocation(ChildComponent, elementRef);
220269
* }
221270
* }
222271
*

‎modules/angular2/src/core/compiler/element_ref.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,16 @@ import {ViewRef} from './view_ref';
33
import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api';
44

55
/**
6-
* Represents a location in a View that has an injection, change-detection and render contexts
6+
* Represents a location in a View that has an injection, change-detection and render context
77
* associated with it.
88
*
99
* An `ElementRef` is created for each element in the Template that contains a Directive, Component
1010
* or data-binding.
1111
*
12-
* An `ElementRef` is backed by a render-specific element. In the browser context, this is usually a
13-
* DOM element.
12+
* An `ElementRef` is backed by a render-specific element. In the browser, this is usually a DOM
13+
* element.
1414
*/
1515
export class ElementRef implements RenderElementRef {
16-
1716
/**
1817
* @private
1918
*
@@ -72,7 +71,7 @@ export class ElementRef implements RenderElementRef {
7271
* </p>
7372
* <p>
7473
* Relying on direct DOM access creates tight coupling between your application and rendering
75-
* layers which will make it impossible to separate the two and deploy your application in into a
74+
* layers which will make it impossible to separate the two and deploy your application into a
7675
* web worker.
7776
* </p>
7877
* <!-- TODO: add info about custom renderers that should be used instead -->

‎modules/angular2/src/core/compiler/template_ref.ts‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,30 @@ import {ElementRef} from './element_ref';
33
import * as viewModule from './view';
44

55
/**
6-
* Represents an Embedded Template that can be used for creating Embedded Views.
6+
* Represents an Embedded Template that can be used to instantiate Embedded Views.
77
*
8-
* Use {@link ViewContainerRef#createEmbeddedView} method to instantiate an Embedded View and attach
9-
* it to a View Container.
8+
* You can access a `TemplateRef`, in two ways. Via a directive placed on a `<template>` element (or
9+
* directive prefixed with `*`) and have the `TemplateRef` for this Embedded View injected into the
10+
* constructor of the directive using the `TemplateRef` Token. Alternatively you can query for the
11+
* `TemplateRef` from a Component or a Directive via {@link Query}.
1012
*
11-
* <!-- TODO: how to get hold of it? -->
13+
* To instantiate Embedded Views based on a Template, use
14+
* {@link ViewContainerRef#createEmbeddedView}, which will create the View and attach it to the
15+
* View Container.
1216
*/
1317
export class TemplateRef {
14-
1518
/**
16-
* The location in the View where the Embedded View logically belong to.
19+
* The location in the View where the Embedded View logically belongs to.
20+
*
21+
* The data-binding and injection contexts of Embedded Views created from this `TemplateRef`
22+
* inherit from the contexts of this location.
23+
*
24+
* Typically new Embedded Views are attached to the View Container of this location, but in
25+
* advanced use-cases, the View can be attached to a different container while keeping the
26+
* data-binding and injection context from the original location.
1727
*
18-
* This `ElementRef` provides the data-binding and injection context for Embedded Views created
19-
* from this `TemplateRef`.
2028
*/
29+
// TODO(i): rename to anchor or location
2130
elementRef: ElementRef;
2231

2332
/**
@@ -33,13 +42,15 @@ export class TemplateRef {
3342
}
3443

3544
/**
36-
* Reference to the ProtoView created by compiling the original Embedded Template, from which the
37-
* Embedded View is instatiated.
45+
* @private
46+
*
47+
* Reference to the ProtoView used for creating Embedded Views that are based on the compiled
48+
* Embedded Template.
3849
*/
3950
get protoViewRef(): ProtoViewRef { return this._getProtoView().ref; }
4051

4152
/**
42-
* Returns true if the Template declares a Local Variable with the given name.
53+
* Allows you to check if this Embedded Template defines Local Variable with name matching `name`.
4354
*/
4455
hasLocal(name: string): boolean { return this._getProtoView().variableBindings.has(name); }
4556
}

0 commit comments

Comments
 (0)