From b2cae850d8d5c9a44f84e2eabf3c16ba4570def2 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Fri, 11 Dec 2015 13:18:37 -0800 Subject: [PATCH] docs(Hierarchical DI): code shuffle, text, & alpha52 updates closes #480 --- .../ts/app/boot.ts | 13 +++ .../ts/{src => }/app/edit-item.ts | 0 .../ts/{src => }/app/hero-card.component.ts | 2 +- .../ts/{src => }/app/hero-editor.component.ts | 6 +- .../ts/{src => }/app/hero.ts | 0 .../ts/{src => }/app/heroes-list.component.ts | 8 +- .../heroes.service.ts} | 0 .../restore.service.ts} | 0 .../ts/{src => }/index.html | 6 +- .../ts/package.json | 20 ++-- .../ts/plnkr.json | 5 + .../ts/{src => }/tsconfig.json | 11 ++- .../hierarchical-dependency-injection.jade | 91 +++++++++++-------- 13 files changed, 95 insertions(+), 67 deletions(-) create mode 100644 public/docs/_examples/hierarchical-dependency-injection/ts/app/boot.ts rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/app/edit-item.ts (100%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/app/hero-card.component.ts (82%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/app/hero-editor.component.ts (84%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/app/hero.ts (100%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/app/heroes-list.component.ts (86%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src/app/heroes-service.ts => app/heroes.service.ts} (100%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src/app/restore-service.ts => app/restore.service.ts} (100%) rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/index.html (63%) create mode 100644 public/docs/_examples/hierarchical-dependency-injection/ts/plnkr.json rename public/docs/_examples/hierarchical-dependency-injection/ts/{src => }/tsconfig.json (50%) diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/app/boot.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/boot.ts new file mode 100644 index 0000000000..7b3189eb3e --- /dev/null +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/app/boot.ts @@ -0,0 +1,13 @@ +// #docregion +import {bootstrap} from 'angular2/platform/browser'; +import {HeroesListComponent} from './heroes-list.component'; +import {HeroesService} from './heroes.service'; + +bootstrap(HeroesListComponent, [HeroesService]) + +/* Documentation artifact below +// #docregion bad-alternative +// Don't do this! +bootstrap(HeroesListComponent, [HeroesService, RestoreService]) +// #enddocregion bad-alternative +*/ \ No newline at end of file diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/edit-item.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/edit-item.ts similarity index 100% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/edit-item.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/edit-item.ts diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero-card.component.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/hero-card.component.ts similarity index 82% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero-card.component.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/hero-card.component.ts index e430617320..04d64ad19d 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero-card.component.ts +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/app/hero-card.component.ts @@ -1,5 +1,5 @@ // #docregion -import {Component, Input} from 'angular2/angular2'; +import {Component, Input} from 'angular2/core'; import {Hero} from './hero'; @Component({ diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero-editor.component.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/hero-editor.component.ts similarity index 84% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero-editor.component.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/hero-editor.component.ts index 2c6f6a84db..1c19577cda 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero-editor.component.ts +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/app/hero-editor.component.ts @@ -1,6 +1,6 @@ // #docregion -import {Component, Input, Output, EventEmitter} from 'angular2/angular2'; -import {RestoreService} from './restore-service'; +import {Component, Input, Output, EventEmitter} from 'angular2/core'; +import {RestoreService} from './restore.service'; import {Hero} from './hero'; @Component({ @@ -11,7 +11,7 @@ import {Hero} from './hero'; template: `
Name: - +
diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/hero.ts similarity index 100% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/hero.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/hero.ts diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/heroes-list.component.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/heroes-list.component.ts similarity index 86% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/heroes-list.component.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/heroes-list.component.ts index 9bda26c20c..a2d477710a 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/heroes-list.component.ts +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/app/heroes-list.component.ts @@ -1,7 +1,7 @@ // #docregion -import {Component, bootstrap} from 'angular2/angular2'; +import {Component} from 'angular2/core'; import {EditItem} from './edit-item'; -import {HeroesService} from './heroes-service'; +import {HeroesService} from './heroes.service'; import {HeroCardComponent} from './hero-card.component'; import {HeroEditorComponent} from './hero-editor.component'; import {Hero} from './hero'; @@ -11,7 +11,7 @@ import {Hero} from './hero'; template: `
    -
  • +
  • @@ -49,5 +49,5 @@ export class HeroesListComponent { } } -bootstrap(HeroesListComponent, [HeroesService]); + // #enddocregion diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/heroes-service.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/heroes.service.ts similarity index 100% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/heroes-service.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/heroes.service.ts diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/app/restore-service.ts b/public/docs/_examples/hierarchical-dependency-injection/ts/app/restore.service.ts similarity index 100% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/app/restore-service.ts rename to public/docs/_examples/hierarchical-dependency-injection/ts/app/restore.service.ts diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/index.html b/public/docs/_examples/hierarchical-dependency-injection/ts/index.html similarity index 63% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/index.html rename to public/docs/_examples/hierarchical-dependency-injection/ts/index.html index 7f0313830e..5875b1e372 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/src/index.html +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/index.html @@ -3,13 +3,13 @@ Hierarchical Injectors - - + + diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/package.json b/public/docs/_examples/hierarchical-dependency-injection/ts/package.json index d82952aa81..73108957ce 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/package.json +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/package.json @@ -1,21 +1,15 @@ { - "name": "angular2-getting-started", + "name": "angular2-hierarchical-injection", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { - "tsc": "tsc -p src -w", - "start": "live-server --open=src" + "tsc": "tsc", + "tsc:w": "tsc -w", + "lite": "lite-server", + "both": "concurrent \"npm run tsc:w\" \"npm run lite\" " }, "keywords": [], "author": "", - "license": "ISC", - "dependencies": { - "angular2": "2.0.0-alpha.46", - "systemjs": "0.19.2" - }, - "devDependencies": { - "live-server": "^0.8.1", - "typescript": "^1.6.2" - } -} + "license": "ISC" +} \ No newline at end of file diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/plnkr.json b/public/docs/_examples/hierarchical-dependency-injection/ts/plnkr.json new file mode 100644 index 0000000000..84cd89d7ca --- /dev/null +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/plnkr.json @@ -0,0 +1,5 @@ +{ + "description": "Hierachical Injectors", + "files":["!**/*.d.ts", "!**/*.js"], + "tags": ["dependency", "injection"] +} \ No newline at end of file diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/src/tsconfig.json b/public/docs/_examples/hierarchical-dependency-injection/ts/tsconfig.json similarity index 50% rename from public/docs/_examples/hierarchical-dependency-injection/ts/src/tsconfig.json rename to public/docs/_examples/hierarchical-dependency-injection/ts/tsconfig.json index 6a58b35a58..6ffae9f106 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/src/tsconfig.json +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/tsconfig.json @@ -1,11 +1,16 @@ { "compilerOptions": { "target": "ES5", - "module": "commonjs", + "module": "system", + "moduleResolution": "node", "sourceMap": true, "emitDecoratorMetadata": true, "experimentalDecorators": true, "removeComments": false, - "noImplicitAny": false - } + "noImplicitAny": true, + "suppressImplicitAnyIndexErrors": true + }, + "exclude": [ + "node_modules" + ] } \ No newline at end of file diff --git a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade index f798f7aaed..82133e09c9 100644 --- a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade +++ b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade @@ -1,36 +1,43 @@ include ../../../../_includes/_util-fns :marked - We learned the basics of Angular Dependency injection in an - [earlier chapter](./dependency-injection.html). + We learned the basics of Angular Dependency injection in the + [Dependency Injection](./dependency-injection.html) chapter. - In this chapter we learn that Angular has an - Hierarchical Dependency Injection system that supports trees of injectors. - - In practice, there is a tree of injectors that parallel an application's component tree. + Angular has an Hierarchical Dependency Injection system. + There is actually a tree of injectors + that parallel an application's component tree. We can re-configure the injectors at any level of that component tree with interesting and useful results. + + In this chapter we explore these points and write some code. + + [Live Example](/resources/live-examples/hierarchical-dependency-injection/ts/plnkr.html). .l-main-section :marked ## The Injector Tree - In an [earlier chapter](./dependency-injection.html) - we learned how to configure a dependency injector in different ways and how to retrieve dependencies where we need them. + In the [Dependency Injection](./dependency-injection.html) chapter + we learned how to configure a dependency injector and how to retrieve dependencies where we need them. - What if we told you there is no such thing as ***the*** injector? - In fact, each application has multiple injectors! + We oversimplified. In fact, there is no such thing as ***the*** injector! + An application may have multiple injectors! - We may have heard that an Angular application is a tree of components. - It may surprise us to learn that there is a corresponding tree of injectors - and each component instance in that tree has its own injector! + An Angular application is a tree of components. Each component instance has its own injector! + The tree of components parallels the tree of injectors. + .l-sub-section :marked - That isn't literally true. Angular is more efficient than that. What is true is that each component instance - has an injector and that components at different levels in the tree have different injectors. + Angular doesn't *literally* create a separate injector for each component. + Every component doesn't need its own injector and it would be horribly inefficient to create + masses of injectors for no good purpose. + + But it is true that every component ***has an injector*** (even if it shares that injector with another component) + and there may be many different injector instances operating at different levels of the component tree. - It is helpful for our purposes to pretend that every component has its own injector. + It is useful to pretend that every component has its own injector. :marked Consider a simple variation on the Tour of Heroes application consisting of three different components: `HeroesApp`, `HeroesListComponent` and `HeroesCardComponent`. @@ -41,7 +48,7 @@ include ../../../../_includes/_util-fns open simultaneously. figure.image-display - img(src="/resources/images/devguide/dependency-injection/component-hierarchy.png" alt="injector tree") + img(src="/resources/images/devguide/dependency-injection/component-hierarchy.png" alt="injector tree" width="500") :marked Each component instance gets its own injector and an injector at one level is a child injector of the injector above it in the tree. @@ -78,13 +85,13 @@ figure.image-display `Tires` resolved by the root injector (A). figure.image-display - img(src="/resources/images/devguide/dependency-injection/injector-tree.png" alt="injector tree") + img(src="/resources/images/devguide/dependency-injection/injector-tree.png" alt="injector tree" width="600") .l-main-section :marked ## Component Injectors - In the previous section, we talked about injectors and how they are organized like a tree. Lookups follow the injector tree upwards until they found the requested thing to inject. But when do we actually want to provide bindings on the root injector and when do we want to provide them on a child injector? + In the previous section, we talked about injectors and how they are organized like a tree. Lookups follow the injector tree upwards until they found the requested thing to inject. But when do we actually want to provide providers on the root injector and when do we want to provide them on a child injector? Consider you are building a component to show a list of super heroes that displays each super hero in a card with it’s name and superpower. There should also be an edit button that opens up an editor to change the name and superpower of our hero. @@ -92,64 +99,68 @@ figure.image-display Let’s take a look at the `HeroesListComponent` which is the root component for this example. -+makeExample('hierarchical-dependency-injection/ts/src/app/heroes-list.component.ts') ++makeExample('hierarchical-dependency-injection/ts/app/heroes-list.component.ts', null, 'app/heroes-list.component.ts') :marked Notice that it imports the `HeroService` that we’ve used before so we can skip its declaration. The only difference is that we’ve used a more formal approach for our `Hero`model and defined it upfront as such. -+makeExample('hierarchical-dependency-injection/ts/src/app/hero.ts') ++makeExample('hierarchical-dependency-injection/ts/app/hero.ts', null, 'app/hero.ts')(format=".") :marked Our `HeroesListComponent` defines a template that creates a list of `HeroCardComponents` and `HeroEditorComponents`, each bound to an instance of hero that is returned from the `HeroService`. Ok, that’s not entirely true. It actually binds to an `EditItem` which is a simple generic datatype that can wrap any type and indicate if the item being wrapped is currently being edited or not. -+makeExample('hierarchical-dependency-injection/ts/src/app/edit-item.ts') ++makeExample('hierarchical-dependency-injection/ts/app/edit-item.ts', null, 'app/edit-item.ts')(format=".") :marked But how is `HeroCardComponent` implemented? Let’s take a look. -+makeExample('hierarchical-dependency-injection/ts/src/app/hero-card.component.ts') ++makeExample('hierarchical-dependency-injection/ts/app/hero-card.component.ts', null, 'app/hero-card.component.ts') :marked The `HeroCardComponent` is basically a component that defines a template to render a hero. Nothing more. Let’s get to the interesting part and take a look at the `HeroEditorComponent` -+makeExample('hierarchical-dependency-injection/ts/src/app/hero-editor.component.ts') ++makeExample('hierarchical-dependency-injection/ts/app/hero-editor.component.ts', null, 'app/hero-editor.component.ts') :marked Now here it’s getting interesting. The `HeroEditorComponent`defines a template with an input to change the name of the hero and a `cancel` and a `save` button. Remember that we said we want to have the flexibility to cancel our editing and restore the old value? This means we need to maintain two copies of our `Hero` that we want to edit. Thinking ahead this is a perfect use case to abstract it into it’s own generic service since we have probably more cases like this in our app. And this is where the `RestoreService` enters the stage. -+makeExample('hierarchical-dependency-injection/ts/src/app/restore-service.ts') ++makeExample('hierarchical-dependency-injection/ts/app/restore.service.ts', null, 'app/estore.service.ts') :marked All this tiny service does is define an API to set a value of any type which can be altered, retrieved or set back to it’s initial value. That’s exactly what we need to implement the desired functionality. Our `HeroEditComponent` uses this services under the hood for it’s `hero` property. It intercepts the `get` and `set` method to delegate the actual work to our `RestoreService` which in turn makes sure that we won’t work on the original item but on a copy instead. - At this point we may be scratching our heads asking what this has to do with component injectors? If we look closely at our `HeroEditComponent` we’ll notice this piece of code - -+makeExample('hierarchical-dependency-injection/ts/src/app/hero-editor.component.ts', 'providers') + At this point we may be scratching our heads asking what this has to do with component injectors? + If closely at the metadata for our `HeroEditComponent`. Notice the `providers` property. ++makeExample('hierarchical-dependency-injection/ts/app/hero-editor.component.ts', 'providers') :marked - This creates a binding for the `RestoreService` in the injector of the `HeroEditComponent`. But couldn’t we simply alter our bootstrap call to this? - - ``` - bootstrap(HeroesListComponent, [HeroService, RestoreService]); - ``` + This adds a `RestoreService` provider to the injector of the `HeroEditComponent`. + Couldn’t we simply alter our bootstrap call to this? ++makeExample('hierarchical-dependency-injection/ts/app/boot.ts', 'bad-alternative') +:marked Technically we could, but our component wouldn’t quite behave the way it is supposed to. Remember that each injector treats the services that it provides as singletons. However, in order to be able to have multiple instances of `HeroEditComponent` edit multiple heroes at the same time we need to have multiple instances of the `RestoreService`. More specifically each instance of `HeroEditComponent` needs to be bound to it’s own instance of the `RestoreService`. - By configuring a binding for the `RestoreService` on the `HeroEditComponent`, we get exactly one instance of the `RestoreService`per `HeroEditComponent`. + By configuring a provider for the `RestoreService` on the `HeroEditComponent`, we get exactly one new instance of the `RestoreService`per `HeroEditComponent`. Does that mean that services aren’t singletons anymore in Angular 2? Yes and no. - While there’s only one instance per binding per injector there may be multiple instances of the same type across - the entire application due to the fact that we can create multiple bindings for the same type on different components. + There can be only one instance of a service type in a particular injector. + But we've learned that we can have multiple injectors operating at different levels of the application's component tree. + Any of those injectors could have its own instance of the service. - If we had only defined a binding for `RestoreService` on the root component, - we would have exactly one instance of the across the entire applicatoin. That’s clearly not what we want in this scenario. - We don’t want to share an instance. We want each component to have its own instance of the `RestoreService`. + If we defined a `RestoreService` provider only on the root component, + we would have exactly one instance of that service and it would be shared across the entire application. + + That’s clearly not what we want in this scenario. We want each component to have its own instance of the `RestoreService`. + Defining (or re-defining) a provider at the component level creates a new instance of the service for each new instance + of that component. We've made the `RestoreService` a kind of "private" singleton for each `HeroEditComponent`, + scoped to that component instance and its child components.