docs(core): improve applicationref.bootstrap docs (#42407)

add proper examples and update usage notes
add references to the method at relevant places in the docs

PR Close #42407
This commit is contained in:
Umair Hafeez 2021-05-25 01:29:30 -04:00 committed by Dylan Hunn
parent 9498da1038
commit 8a67770687
4 changed files with 104 additions and 16 deletions

View File

@ -165,7 +165,10 @@ most applications have only one component tree and bootstrap a single root compo
This one root component is usually called `AppComponent` and is in the This one root component is usually called `AppComponent` and is in the
root module's `bootstrap` array. root module's `bootstrap` array.
In a situation where you want to bootstrap a component based on an API response,
or you want to mount the `AppComponent` in a different DOM node that doesn't match
the component selector, please refer to `ApplicationRef.bootstrap()`
documentation.
## More about Angular Modules ## More about Angular Modules

View File

@ -682,20 +682,41 @@ export class ApplicationRef {
} }
/** /**
* Bootstrap a new component at the root level of the application. * Bootstrap a component onto the element identified by its selector or, optionally, to a
* specified element.
* *
* @usageNotes * @usageNotes
* ### Bootstrap process * ### Bootstrap process
* *
* When bootstrapping a new root component into an application, Angular mounts the * When bootstrapping a component, Angular mounts it onto a target DOM element
* specified application component onto DOM elements identified by the componentType's * and kicks off automatic change detection. The target DOM element can be
* selector and kicks off automatic change detection to finish initializing the component. * provided using the `rootSelectorOrNode` argument.
* *
* Optionally, a component can be mounted onto a DOM element that does not match the * If the target DOM element is not provided, Angular tries to find one on a page
* componentType's selector. * using the `selector` of the component that is being bootstrapped
* (first matched element is used).
* *
* ### Example * ### Example
* {@example core/ts/platform/platform.ts region='longform'} *
* Generally, we define the component to bootstrap in the `bootstrap` array of `NgModule`,
* but it requires us to know the component while writing the application code.
*
* Imagine a situation where we have to wait for an API call to decide about the component to
* bootstrap. We can use the `ngDoBootstrap` hook of the `NgModule` and call this method to
* dynamically bootstrap a component.
*
* {@example core/ts/platform/platform.ts region='componentSelector'}
*
* Optionally, a component can be mounted onto a DOM element that does not match the
* selector of the bootstrapped component.
*
* In the following example, we are providing a CSS selector to match the target element.
*
* {@example core/ts/platform/platform.ts region='cssSelector'}
*
* While in this example, we are providing reference to a DOM node.
*
* {@example core/ts/platform/platform.ts region='domNode'}
*/ */
bootstrap<C>(componentOrFactory: ComponentFactory<C>|Type<C>, rootSelectorOrNode?: string|any): bootstrap<C>(componentOrFactory: ComponentFactory<C>|Type<C>, rootSelectorOrNode?: string|any):
ComponentRef<C> { ComponentRef<C> {

View File

@ -19,6 +19,9 @@ import {ApplicationRef} from '../application_ref';
* See ["Bootstrapping"](guide/bootstrapping) and ["Entry components"](guide/entry-components). * See ["Bootstrapping"](guide/bootstrapping) and ["Entry components"](guide/entry-components).
* *
* @usageNotes * @usageNotes
* The example below uses `ApplicationRef.bootstrap()` to render the
* `AppComponent` on the page.
*
* ```typescript * ```typescript
* class AppModule implements DoBootstrap { * class AppModule implements DoBootstrap {
* ngDoBootstrap(appRef: ApplicationRef) { * ngDoBootstrap(appRef: ApplicationRef) {

View File

@ -6,14 +6,75 @@
* found in the LICENSE file at https://angular.io/license * found in the LICENSE file at https://angular.io/license
*/ */
import {Component, createPlatformFactory} from '@angular/core'; import {ApplicationRef, Component, DoBootstrap, NgModule, Type} from '@angular/core';
import {platformBrowserDynamic} from '@angular/platform-browser-dynamic'; import {BrowserModule} from '@angular/platform-browser';
// #docregion longform @Component({
@Component({selector: 'app-root', template: 'Hello World'}) selector: 'app-root',
class MyApp { template: ` <h1>Component One</h1> `,
})
export class ComponentOne {
} }
const myPlatformFactory = createPlatformFactory(platformBrowserDynamic, 'myPlatform'); @Component({
myPlatformFactory().bootstrapModule(MyApp); selector: 'app-root',
// #enddocregion template: ` <h1>Component Two</h1> `,
})
export class ComponentTwo {
}
@Component({
selector: 'app-root',
template: ` <h1>Component Three</h1> `,
})
export class ComponentThree {
}
@Component({
selector: 'app-root',
template: ` <h1>Component Four</h1> `,
})
export class ComponentFour {
}
@NgModule({imports: [BrowserModule], declarations: [ComponentOne, ComponentTwo]})
export class AppModule implements DoBootstrap {
// #docregion componentSelector
ngDoBootstrap(appRef: ApplicationRef) {
this.fetchDataFromApi().then((componentName: string) => {
if (componentName === 'ComponentOne') {
appRef.bootstrap(ComponentOne);
} else {
appRef.bootstrap(ComponentTwo);
}
});
}
// #enddocregion
fetchDataFromApi(): Promise<string> {
return new Promise((resolve) => {
setTimeout(() => {
resolve('ComponentTwo');
}, 2000);
});
}
}
@NgModule({imports: [BrowserModule], declarations: [ComponentThree]})
export class AppModuleTwo implements DoBootstrap {
// #docregion cssSelector
ngDoBootstrap(appRef: ApplicationRef) {
appRef.bootstrap(ComponentThree, '#root-element');
}
// #enddocregion cssSelector
}
@NgModule({imports: [BrowserModule], declarations: [ComponentFour]})
export class AppModuleThree implements DoBootstrap {
// #docregion domNode
ngDoBootstrap(appRef: ApplicationRef) {
const element = document.querySelector('#root-element');
appRef.bootstrap(ComponentFour, element);
}
// #enddocregion domNode
}