From 956b8c8792669de74082e01cec88ae5ee9aac565 Mon Sep 17 00:00:00 2001 From: Misko Hevery Date: Fri, 13 Mar 2015 21:54:19 +0000 Subject: [PATCH] docs: bootstrap method --- .../src/core/annotations/annotations.js | 4 + modules/angular2/src/core/application.js | 105 +++++++++++++++++- 2 files changed, 104 insertions(+), 5 deletions(-) diff --git a/modules/angular2/src/core/annotations/annotations.js b/modules/angular2/src/core/annotations/annotations.js index 20858dc7b3..099c416fdc 100644 --- a/modules/angular2/src/core/annotations/annotations.js +++ b/modules/angular2/src/core/annotations/annotations.js @@ -1,6 +1,10 @@ import {ABSTRACT, CONST, normalizeBlank, isPresent} from 'angular2/src/facade/lang'; import {ListWrapper, List} from 'angular2/src/facade/collection'; +/** + * Directives allow you to attach behavior to the DOM elements. Directive is an abstract concept, instead use concrete + * directives such as: [Component], [Decorator] or [Viewport]. + */ @ABSTRACT() export class Directive { selector:any; //string; diff --git a/modules/angular2/src/core/application.js b/modules/angular2/src/core/application.js index 4af4a34963..fc8cff2735 100644 --- a/modules/angular2/src/core/application.js +++ b/modules/angular2/src/core/application.js @@ -117,18 +117,113 @@ function _createVmZone(givenReporter:Function): VmTurnZone { return zone; } -// Multiple calls to this method are allowed. Each application would only share -// _rootInjector, which is not user-configurable by design, thus safe to share. -export function bootstrap(appComponentType: Type, bindings: List=null, givenBootstrapErrorReporter: Function=null): Promise { +/** + * Bootstrapping for Angular applications. + * + * You instantiate an Angular application by explicitly specifying a component to use as the root component for your + * application via the `bootstrap()` method. + * + * ## Simple Example + * + * Assuming this `index.html`: + * + * + * + * loading... + * + * + * + * An application is bootstrapped inside an existing browser DOM, typically `index.html`. Unlike Angular 1, Angular 2 + * does not compile/process bindings in `index.html`. This is mainly for security reasons, as well as architectural + * changes in Angular 2. This means that `index.html` can safely be processed using server-side binding technologies, + * which may use double-curly `{{syntax}}` without collision from Angular 2 component double-curly `{{syntax}}`. + * + * We can use this script code: + * @Component({ + * selector: 'my-app' + * }) + * @Template({ + * inline: 'Hello {{name}}!' + * }) + * class MyApp { + * name:string; + * + * constructor() { + * this.name = 'World'; + * } + * } + * + * main() { + * bootstrap(MyApp); + * } + * + * When the app developer invokes `bootstrap()` with the root component `MyApp` as its argument, Angular performs the + * following tasks: + * + * 1. It uses the component's `selector` property to locate the DOM element which needs to be upgraded into + * the angular component. + * 2. It creates a new child injector (from the primordial injector) and configures the injector with the component's + * `services`. Optionally, you can also override the injector configuration for an app by invoking + * `bootstrap` with the `componentServiceBindings` argument. + * 3. It creates a new [Zone] and connects it to the angular application's change detection domain instance. + * 4. It creates a shadow DOM on the selected component's host element and loads the template into it. + * 5. It instantiates the specified component. + * 6. Finally, Angular performs change detection to apply the initial data bindings for the application. + * + * + * ## Instantiating Multiple Applications on a Single Page + * + * There are two ways to do this. + * + * + * ### Isolated Applications + * + * Angular creates a new application each time that the `bootstrap()` method is invoked. When multiple applications + * are created for a page, Angular treats each application as independent within an isolated change detection and + * [Zone] domain. If you need to share data between applications, use the strategy described in the next + * section, "Applications That Share Change Detection." + * + * + * ### Applications That Share Change Detection + * + * If you need to bootstrap multiple applications that share common data, the applications must share a common + * change detection and zone. To do that, create a meta-component that lists the application components in its template. + * By only invoking the bootstrap()` method once with the meta-component as its argument, you ensure that only a single + * change detection zone is created and therefore data can be shared across the applications. + * + * + * ## Primordial Injector + * + * When working within a browser window, there are many singleton resources: cookies, title, location, and others. + * Angular services that represent these resources must likewise be shared across all Angular applications that + * occupy the same browser window. For this reason, Angular creates exactly one global primordial injector which stores + * all shared services, and each angular application injector has the primordial injector as its parent. + * + * Each application has its own private injector as well. When there are multiple applications on a page, Angular treats + * each application injector's services as private to that application. + * + * + * # API + * - [appComponentType]: The root component which should act as the application. This is a reference to a [Type] + * which is annotated with `@Component(...)`. + * - [componentServiceBindings]: An additional set of bindings that can be added to the [Component.services] to + * override default injection behavior. + * - [errorReporter]: `function(exception:any, stackTrace:string)` a default error reporter for unhandled exceptions. + * + * Returns the application`s private [Injector]. + */ +export function bootstrap(appComponentType: Type, + componentServiceBindings: List=null, + errorReporter: Function=null): Promise { BrowserDomAdapter.makeCurrent(); var bootstrapProcess = PromiseWrapper.completer(); - var zone = _createVmZone(givenBootstrapErrorReporter); + var zone = _createVmZone(errorReporter); zone.run(() => { // TODO(rado): prepopulate template cache, so applications with only // index.html and main.js are possible. - var appInjector = _createAppInjector(appComponentType, bindings, zone); + var appInjector = _createAppInjector(appComponentType, componentServiceBindings, zone); PromiseWrapper.then(appInjector.asyncGet(appViewToken), (rootView) => {