docs(cb-di): more Ward tweaks

Author: wardbell

public/docs/_examples/cb-dependency-injection/ts/app/app.component.ts

@@ -9,28 +9,29 @@ import { HeroesBaseComponent,
 import { HighlightDirective }          from './highlight.directive';
 import { ParentPasserComponent }       from './parent-passer.component';
 
+const DIRECTIVES = [
+    HeroBiosComponent, HeroBiosAndContactsComponent,
+    HeroesBaseComponent, SortedHeroesComponent,
+    HeroOfTheMonthComponent,
+    HighlightDirective,
+    ParentPasserComponent
+];
+
 // #docregion import-services
 import { LoggerService }      from './logger.service';
 import { UserContextService } from './user-context.service';
 import { UserService }        from './user.service';
-// #enddocregion import-services
 
 @Component({
   selector: 'my-app',
   templateUrl:'app/app.component.html',
-  directives: [
-    HeroBiosComponent, HeroBiosAndContactsComponent,
-    HeroesBaseComponent, SortedHeroesComponent,
-    HeroOfTheMonthComponent,
-    HighlightDirective,
-    ParentPasserComponent
-  ],
+  directives: DIRECTIVES,
 // #docregion providers
   providers: [LoggerService, UserContextService, UserService]
 // #enddocregion providers
 })
-
 export class AppComponent {
+// #enddocregion import-services
 
   private userId:number = 1;
 
@@ -40,4 +41,6 @@ export class AppComponent {
     logger.logInfo('AppComponent initialized');
   }
   // #enddocregion ctor
+// #docregion import-services
 }
+// #enddocregion import-services

public/docs/_examples/cb-dependency-injection/ts/app/hero-bios.component.ts

@@ -40,7 +40,9 @@ export class HeroBiosComponent{
     <hero-bio [heroId]="3"> <hero-contact></hero-contact> </hero-bio>`,
   // #enddocregion template
   directives:[HeroBioComponent, HeroContactComponent],
+  // #docregion class-provider
   providers: [HeroService]
+  // #enddocregion class-provider
 })
 export class HeroBiosAndContactsComponent{
   constructor(logger: LoggerService) {

public/docs/_examples/cb-dependency-injection/ts/app/hero-of-the-month.component.ts

@@ -1,10 +1,11 @@
+// #docplaster
 // #docregion opaque-token
 import {OpaqueToken} from 'angular2/core';
 
 export const TITLE = new OpaqueToken('title');
 // #enddocregion opaque-token
 
-// #docregion
+// #docregion hero-of-the-month
 import { Component, Inject, provide } from 'angular2/core';
 
 import { DateLoggerService,
@@ -15,9 +16,12 @@ import { LoggerService }     from './logger.service';
 import { RunnersUp }         from './runners-up';
 import { runnersUpFactory }  from './runners-up-provider.service';
 
-@Component({
-  selector:'hero-of-the-month',
-  template:`
+// #enddocregion hero-of-the-month
+// #docregion some-hero
+const someHero = new Hero(42, 'Magma','Had a great month!','555-555-5555');
+// #enddocregion some-hero
+
+const template = `
   <h3>{{title}}</h3>
   <div>Winner: <strong>{{_heroOfTheMonth.name}}</strong></div>
   <div>Reason for award: <strong>{{_heroOfTheMonth.description}}</strong></div>
@@ -27,13 +31,19 @@ import { runnersUpFactory }  from './runners-up-provider.service';
   <div id="logs">
     <div *ngFor="#log of logs">{{log}}</div>
   </div>
-  `,
+  `;
 
+// #docregion hero-of-the-month
+@Component({
+  selector:'hero-of-the-month',
+  template: template,
 // #docregion providers
   providers:[
-    HeroService,
-    provide(Hero,          {useValue:    new Hero(42, 'Magma','Had a great month!','555-555-5555')}),
+    provide(Hero,          {useValue:    someHero}),
+    // #docregion use-class
+    provide(HeroService,   {useClass:    HeroService}),
     provide(LoggerService, {useClass:    DateLoggerService}),
+    // #enddocregion use-class
     provide(MinimalLogger, {useExisting: LoggerService}),
     provide(RunnersUp,     {useFactory:  runnersUpFactory, deps:[Hero, HeroService]}),
     provide(TITLE,         {useValue:    'Hero of the Month'})
@@ -55,4 +65,4 @@ export class HeroOfTheMonthComponent {
   }
 }
 // #enddocregion class
-// #enddocregion
+// #enddocregion hero-of-the-month

public/docs/ts/latest/cookbook/dependency-injection.jade

@@ -35,13 +35,14 @@ include ../_util-fns
   ## Application-wide dependencies   
   Register providers for dependencies used throughout the application in the root application component, `AppComponent`.
 
-  In the following example we import and register several services 
+  In the following example, we import and register several services 
   (the `LoggerService`, `UserContext`, and the `UserService`)
   in the `@Component` metadata `providers` array.
 
-+makeExample('cb-dependency-injection/ts/app/app.component.ts','import-services','app/app.component.ts (imports)')(format='.') 
-
-+makeExample('cb-dependency-injection/ts/app/app.component.ts','providers','app/app.component.ts (providers)') 
++makeExample('cb-dependency-injection/ts/app/app.component.ts','import-services','app/app.component.ts (excerpt)')(format='.') 
+.l-sub-section
+  :marked
+    Learn more about providers [below](#providers).
 :marked
   Now we can inject these services into the constructor of *any* application sub-component or service.
 +makeExample('cb-dependency-injection/ts/app/hero-bios.component.ts','ctor','app/hero-bios.component.ts (component constructor injection)')(format='.') 
@@ -193,7 +194,8 @@ figure.image-display
 figure.image-display
   img(src="/resources/images/cookbooks/dependency-injection/hero-bios.png" alt="Bios")    
 
-<a id="qualify-dependency-lookup"></a>
+a(id="optional")
+a(id="qualify-dependency-lookup")
 .l-main-section
 :marked
   ## Qualify dependency lookup with *@Optional* and *@Host*
@@ -283,21 +285,75 @@ figure.image-display
 .l-main-section
 :marked
   ## Providers: defining dependency creation
-  In the following sample we will show how to configure Angular's DI framework and control how instances are resolved.
 
-  A typical use case for wanting to customize DI is mocking. Mocks can be created for unit tests, 
-  but also to work ahead on a feature while we wait for other teams to build the services our components depend on. 
-  In the following example we will be building `HeroOfTheMonthComponent`
-  where we customize the behavior of some of the services we introduced in previous sections.
-   
-+makeExample('cb-dependency-injection/ts/app/hero-of-the-month.component.ts','','hero-of-the-month.component.ts')   
+  In this section we learn to write providers that deliver dependent services.
+  
+  ### Background
+  We get a service from a dependency injector by giving it a ***token***. 
+  
+  We usually let Angular handle this transaction for us by specifying a constructor parameter and its type.
+  The parameter type serves as the injector lookup *token*. 
+  Angular passes this token to the injector and assigns the result to the parameter.
+  Here's a typical example:
 
++makeExample('cb-dependency-injection/ts/app/hero-bios.component.ts','ctor','app/hero-bios.component.ts (component constructor injection)')(format='.') 
 :marked
-  ***useValue*** 
+  Angular asks the injector for the service associated with the `LoggerService` and
+  and assigns the returned value to the `logger` parameter.
 
-  We are using `useValue` to always return a specific hero whenever a `Hero` is injected.
+  Where did the injector get that value?
+  It may already have that value in its internal container. 
+  It it doesn't, it may be able to make one with the help of a ***provider***.
+  A *provider* is a recipe for delivering a service associated with a *token*.
+.l-sub-section
+  :marked
+    If the injector doesn't have a provider for the requested *token*, it delegates the request 
+    to its parent injector, where the process repeats until there are no more injectors. 
+    If the search is futile, the injector throws an error ... unless the request was [optional](#optional).
+    
+    Let's return our attention to providers themselves.
+:marked
+  A new injector has no providers.
+  Angular initializes the injectors it creates with some providers it cares about.
+  We have to register our _own_ application providers manually, 
+  usually in the `providers` array of the `Component` or `Directive` metadata:
++makeExample('cb-dependency-injection/ts/app/app.component.ts','providers','app/app.component.ts (providers)') 
+:marked
+  ### Defining providers
+  
+  The simple class provider is the most typical by far.
+  We mention the class in the `providers` array and we're done.
++makeExample('cb-dependency-injection/ts/app/hero-bios.component.ts','class-provider','app/hero-bios.component.ts (class provider)')(format='.') 
+:marked
+  It's that simple because the most common injected service is an instance of a class.
+  But not every dependency can be satisfied by creating a new instance of a class.
+  We need other ways to deliver dependency values and that means we need other ways to specify a provider.
+  
+  Here's a component we can talk about that demonstrates many of the alternatives and why we need them.
++makeExample('cb-dependency-injection/ts/app/hero-of-the-month.component.ts','hero-of-the-month','hero-of-the-month.component.ts')   
+:marked
+  #### provide
+  The imported Angular `provide` function creates an instance of 
+  the Angular [Provider](../api/core/Provider-class.html) class.
 
-  ***useClass***
+  The `provide` function takes a *token* and a *definition object*.
+  All but one (`TITLE`) of the tokens is a class name; we'll discuss `TITLE` in due course.
+  
+  The *definition* object has one main property, (e.g. `useValue`) that indicates how the provider 
+  should create or return the provided value.
+  
+  #### useValue
+  
+  The `useValue` property supplies the value returned as the dependency.
+  The value must be known *now*.  Here it's an instance of the `Hero` class:
++makeExample('cb-dependency-injection/ts/app/hero-of-the-month.component.ts','some-hero')
+:marked
+  #### useClass
+  The `useClass` provider creates and returns new instance of the specified class.
++makeExample('cb-dependency-injection/ts/app/hero-of-the-month.component.ts','use-class','hero-of-the-month.component.ts')   
+:marked
+  The first `HeroService` example is the *de-sugared*, expanded form of the most typical case in which the
+  class to be created is also the token. We write it the long way only to de-mystify the preferred short form.
 
   Previously we created `LoggerService`, but we are experimenting with a new logger, 
   so in `HeroOfTheMonthComponent` we want to use `useClass` to return an instance of `DateLoggerService` whenever requesting a `LoggerService`.