diff --git a/public/docs/_examples/dependency-injection/ts/app/app.module.ts b/public/docs/_examples/dependency-injection/ts/app/app.module.ts index 2929f502a2..67ae8ae913 100644 --- a/public/docs/_examples/dependency-injection/ts/app/app.module.ts +++ b/public/docs/_examples/dependency-injection/ts/app/app.module.ts @@ -32,6 +32,7 @@ import { AppComponent, CarComponent, HeroesComponent, + // #enddocregion ngmodule HeroListComponent, InjectorComponent, TestComponent, @@ -46,6 +47,7 @@ import { Provider8Component, Provider9Component, Provider10Component, + // #docregion ngmodule ], // #docregion ngmodule-providers providers: [ @@ -56,4 +58,3 @@ import { bootstrap: [ AppComponent ] }) export class AppModule { } -// #enddocregion ngmodule diff --git a/public/docs/dart/latest/guide/dependency-injection.jade b/public/docs/dart/latest/guide/dependency-injection.jade index fb6313e574..12e8f76c4d 100644 --- a/public/docs/dart/latest/guide/dependency-injection.jade +++ b/public/docs/dart/latest/guide/dependency-injection.jade @@ -10,6 +10,34 @@ block ctor-syntax We also leveraged Dart's constructor syntax for declaring parameters and initializing properties simultaneously. +block register-provider-ngmodule + :marked + Before we do, let's see an example of provider registration during bootstrapping: + + +makeExcerpt('app/main.1.ts (discouraged)', 'bootstrap-discouraged', '') + + :marked + The injector now knows about our `HeroService`. + An instance of our `HeroService` will be available for injection across our entire application. + + Of course we can't help wondering about that comment telling us not to do it this way. + It *will* work. It's just not a best practice. + The bootstrap provider option is intended for configuring and overriding Angular's own + preregistered services, such as its routing support. + + The preferred approach is to register application providers in application components. + Because the `HeroService` is used within the *Heroes* feature area — + and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`. + +block ngmodule-vs-component + :marked + Look at the `providers` part of the `@Component` annotation. + An instance of the `HeroService` is now available for injection in this `HeroesComponent` + and all of its child components. + + The `HeroesComponent` itself doesn't happen to need the `HeroService`. + But its child `HeroListComponent` does, so we head there next. + block injectable-not-always-needed-in-ts //- The [Angular Dart Transformer](https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer) //- generates static code to replace the use of dart:mirrors. It requires that types be diff --git a/public/docs/ts/_cache/guide/dependency-injection.jade b/public/docs/ts/_cache/guide/dependency-injection.jade index 54ece28d23..59ec0cc72f 100644 --- a/public/docs/ts/_cache/guide/dependency-injection.jade +++ b/public/docs/ts/_cache/guide/dependency-injection.jade @@ -247,43 +247,49 @@ block ctor-syntax We don't have to create an Angular injector. Angular creates an application-wide injector for us during the bootstrap process. -+makeExample('dependency-injection/ts/app/main.ts', 'bootstrap', 'app/main.ts (excerpt)')(format='.') ++makeExcerpt('app/main.ts', 'bootstrap') :marked We do have to configure the injector by registering the **providers** that create the services our application requires. We'll explain what [providers](#providers) are later in this chapter. - Before we do, let's see an example of provider registration during bootstrapping: -+makeExample('dependency-injection/ts/app/main.1.ts', 'bootstrap-discouraged')(format='.') +block register-provider-ngmodule + :marked + We can either register a provider within an [NgModule](ngmodule.html) or in application components -:marked - The injector now knows about our `HeroService`. - An instance of our `HeroService` will be available for injection across our entire application. + ### Registering providers in an NgModule + Here's our AppModule where we register a `Logger`, a `UserService`, and an `APP_CONFIG` provider. - Of course we can't help wondering about that comment telling us not to do it this way. - It *will* work. It's just not a best practice. - The bootstrap provider option is intended for configuring and overriding Angular's own - preregistered services, such as its routing support. - - The preferred approach is to register application providers in application components. - Because the `HeroService` is used within the *Heroes* feature area — - and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`. + - var app_module_ts = 'app/app.module.ts'; + +makeExcerpt(app_module_ts + ' (excerpt)', 'ngmodule', app_module_ts, { otl: /(providers:)/ }) + //- The preferred approach is to register application providers in application components. + //- Because the `HeroService` is used within the *Heroes* feature area — + //- and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`. :marked ### Registering providers in a component + Here's a revised `HeroesComponent` that registers the `HeroService`. -- var stylePattern = { otl: /(providers:.*),/ }; -+makeExample('dependency-injection/ts/app/heroes/heroes.component.1.ts', 'full','app/heroes/heroes.component.ts', stylePattern)(format='.') +- var stylePattern = { otl: /(providers:[^,]+),/ }; ++makeExample('app/heroes/heroes.component.1.ts', 'full', 'app/heroes/heroes.component.ts', stylePattern)(format='.') -:marked - Look closely at the `providers` part of the `@Component` metadata. - An instance of the `HeroService` is now available for injection in this `HeroesComponent` - and all of its child components. +block ngmodule-vs-component + :marked + ### When to use the NgModule and when an application component? - The `HeroesComponent` itself doesn't happen to need the `HeroService`. - But its child `HeroListComponent` does, so we head there next. + On the one hand, a provider in an NgModule is registered in the root injector. That means that every provider + registered within an NgModule will be accessible in the _entire application_. + + On the other hand, a provider registered in an application component is available only on that component and all its children. + + We want the `APP_CONFIG` service to be available all across the application, but a `HeroService` is only used within the *Heroes* + feature area and nowhere else. + + .l-sub-section + :marked + Also see *"Should I add app-wide providers to the root `AppModule` or the root `AppComponent`?"* in the [NgModule FAQ](../cookbook/ngmodule-faq.html#root-component-or-module). :marked ### Preparing the HeroListComponent for injection @@ -387,7 +393,6 @@ block ctor-syntax The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `#{_priv}logger`. We call that property within our `getHeroes` method when anyone asks for heroes. -//- FIXME refer to Dart API when that page becomes available. - var injUrl = '../api/core/index/Injectable-decorator.html'; h3#injectable Why @Injectable()? :marked @@ -462,7 +467,7 @@ block injectable-not-always-needed-in-ts Our logger service is quite simple: -+makeExample('dependency-injection/ts/app/logger.service.ts', null, 'app/logger.service.ts') ++makeExample('app/logger.service.ts') block real-logger //- N/A @@ -470,9 +475,9 @@ block real-logger :marked We're likely to need the same logger service everywhere in our application, so we put it in the project's `#{_appDir}` folder, and - we register it in the `providers` #{_array} of the metadata for our application root component, `AppComponent`. + we register it in the `providers` #{_array} of our application !{_moduleVsComp}, `!{_AppModuleVsAppComp}`. -+makeExcerpt('app/providers.component.ts','providers-logger','app/app.component.ts (excerpt)') ++makeExcerpt('app/providers.component.ts (excerpt)', 'providers-logger','app/app.module.ts') :marked If we forget to register the logger, Angular throws an exception when it first looks for the logger: @@ -497,7 +502,7 @@ code-example(format="nocode"). We must register a service *provider* with the injector, or it won't know how to create the service. - Earlier we registered the `Logger` service in the `providers` #{_array} of the metadata for the `AppComponent` like this: + Earlier we registered the `Logger` service in the `providers` #{_array} of the metadata for the `AppModule` like this: +makeExample('dependency-injection/ts/app/providers.component.ts','providers-logger') @@ -766,7 +771,7 @@ block what-should-we-use-as-token The TypeScript interface disappears from the generated JavaScript. There is no interface type information left for Angular to find at runtime. -//- FIXME simplify once APIs are defined for Dart. +//- FIXME update once https://github.com/dart-lang/angular2/issues/16 is addressed. - var opaquetoken = _docsFor == 'dart' ? 'OpaqueToken' : 'OpaqueToken' :marked ### OpaqueToken @@ -796,9 +801,9 @@ block what-should-we-use-as-token block dart-map-alternative :marked - Or we can provide and inject the configuration object in our top-level `AppComponent`. + Or we can provide and inject the configuration object in an ngModule like `AppModule`. - +makeExcerpt('app/app.component.ts','providers') + +makeExcerpt('app/app.module.ts','ngmodule-providers') #optional :marked diff --git a/public/docs/ts/latest/guide/dependency-injection.jade b/public/docs/ts/latest/guide/dependency-injection.jade index 50829c4581..59ec0cc72f 100644 --- a/public/docs/ts/latest/guide/dependency-injection.jade +++ b/public/docs/ts/latest/guide/dependency-injection.jade @@ -247,43 +247,49 @@ block ctor-syntax We don't have to create an Angular injector. Angular creates an application-wide injector for us during the bootstrap process. -+makeExample('dependency-injection/ts/app/main.ts', 'bootstrap', 'app/main.ts (excerpt)')(format='.') ++makeExcerpt('app/main.ts', 'bootstrap') :marked We do have to configure the injector by registering the **providers** that create the services our application requires. We'll explain what [providers](#providers) are later in this chapter. - We can either register a provider within an [NgModule](ngmodule.html) or in application components +block register-provider-ngmodule + :marked + We can either register a provider within an [NgModule](ngmodule.html) or in application components - ### Registering providers in an NgModule - Here's our AppModule where we register a `Logger`, a `UserService`, and an `APP_CONFIG` provider. + ### Registering providers in an NgModule + Here's our AppModule where we register a `Logger`, a `UserService`, and an `APP_CONFIG` provider. -- var stylePattern = { otl: /(providers)/ }; -+makeExample('dependency-injection/ts/app/app.module.ts', 'ngmodule','app/app.module.ts', stylePattern)(format='.') - + - var app_module_ts = 'app/app.module.ts'; + +makeExcerpt(app_module_ts + ' (excerpt)', 'ngmodule', app_module_ts, { otl: /(providers:)/ }) + //- The preferred approach is to register application providers in application components. + //- Because the `HeroService` is used within the *Heroes* feature area — + //- and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`. :marked ### Registering providers in a component + Here's a revised `HeroesComponent` that registers the `HeroService`. -+makeExample('dependency-injection/ts/app/heroes/heroes.component.1.ts', 'full','app/heroes/heroes.component.ts', stylePattern)(format='.') +- var stylePattern = { otl: /(providers:[^,]+),/ }; ++makeExample('app/heroes/heroes.component.1.ts', 'full', 'app/heroes/heroes.component.ts', stylePattern)(format='.') -:marked - ### When to use the NgModule and when an application component? - On the one hand, a provider in an NgModule is registered in the root injector. That means that every provider - registered within an NgModule will be accessible in the entire application. - - On the other hand, a provider registered in an application component is available only on that component and all its children. - - We want the `APP_CONFIG` service to be available all across the application, but a `HeroService` is only used within the *Heroes* - feature area — and nowhere else. — - -.l-sub-section +block ngmodule-vs-component :marked - Read also **Should I add app-wide providers to the root `AppModule` or the root `AppComponent`?** in the [NgModule FAQ](../cookbook/ngmodule-faq.html#root-component-or-module) chapter. + ### When to use the NgModule and when an application component? + + On the one hand, a provider in an NgModule is registered in the root injector. That means that every provider + registered within an NgModule will be accessible in the _entire application_. + + On the other hand, a provider registered in an application component is available only on that component and all its children. + + We want the `APP_CONFIG` service to be available all across the application, but a `HeroService` is only used within the *Heroes* + feature area and nowhere else. + + .l-sub-section + :marked + Also see *"Should I add app-wide providers to the root `AppModule` or the root `AppComponent`?"* in the [NgModule FAQ](../cookbook/ngmodule-faq.html#root-component-or-module). :marked ### Preparing the HeroListComponent for injection @@ -387,7 +393,6 @@ block ctor-syntax The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `#{_priv}logger`. We call that property within our `getHeroes` method when anyone asks for heroes. -//- FIXME refer to Dart API when that page becomes available. - var injUrl = '../api/core/index/Injectable-decorator.html'; h3#injectable Why @Injectable()? :marked @@ -462,7 +467,7 @@ block injectable-not-always-needed-in-ts Our logger service is quite simple: -+makeExample('dependency-injection/ts/app/logger.service.ts', null, 'app/logger.service.ts') ++makeExample('app/logger.service.ts') block real-logger //- N/A @@ -470,9 +475,9 @@ block real-logger :marked We're likely to need the same logger service everywhere in our application, so we put it in the project's `#{_appDir}` folder, and - we register it in the `providers` #{_array} of the metadata for our application module, `AppModule`. + we register it in the `providers` #{_array} of our application !{_moduleVsComp}, `!{_AppModuleVsAppComp}`. -+makeExcerpt('app/providers.component.ts','providers-logger','app/app.module.ts (excerpt)') ++makeExcerpt('app/providers.component.ts (excerpt)', 'providers-logger','app/app.module.ts') :marked If we forget to register the logger, Angular throws an exception when it first looks for the logger: @@ -766,7 +771,7 @@ block what-should-we-use-as-token The TypeScript interface disappears from the generated JavaScript. There is no interface type information left for Angular to find at runtime. -//- FIXME simplify once APIs are defined for Dart. +//- FIXME update once https://github.com/dart-lang/angular2/issues/16 is addressed. - var opaquetoken = _docsFor == 'dart' ? 'OpaqueToken' : 'OpaqueToken' :marked ### OpaqueToken