diff --git a/aio/content/examples/providers-viewproviders/e2e/src/app.e2e-spec.ts b/aio/content/examples/providers-viewproviders/e2e/src/app.e2e-spec.ts new file mode 100644 index 0000000000..d9e83d93fe --- /dev/null +++ b/aio/content/examples/providers-viewproviders/e2e/src/app.e2e-spec.ts @@ -0,0 +1,24 @@ +import { browser, element, by } from 'protractor'; +import { logging } from 'selenium-webdriver'; + +describe('Providers and ViewProviders', function () { + + + beforeEach(() => { + browser.get(''); + }); + + it('shows basic flower emoji', function() { + expect(element.all(by.css('p')).get(0).getText()).toContain('🌺'); + }); + + it('shows whale emoji', function() { + expect(element.all(by.css('p')).get(1).getText()).toContain('🐳'); + }); + + it('shows sunflower from FlowerService', function() { + expect(element.all(by.css('p')).get(8).getText()).toContain('🌻'); + }); + +}); + diff --git a/aio/content/examples/providers-viewproviders/example-config.json b/aio/content/examples/providers-viewproviders/example-config.json new file mode 100644 index 0000000000..e69de29bb2 diff --git a/aio/content/examples/providers-viewproviders/src/app/animal.service.ts b/aio/content/examples/providers-viewproviders/src/app/animal.service.ts new file mode 100755 index 0000000000..e7f6a98b08 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/animal.service.ts @@ -0,0 +1,10 @@ +// #docregion animal-service +import { Injectable } from '@angular/core'; + +@Injectable({ + providedIn: 'root' +}) +export class AnimalService { + emoji = '🐳'; +} +// #enddocregion animal-service diff --git a/aio/content/examples/providers-viewproviders/src/app/app.component.1.ts b/aio/content/examples/providers-viewproviders/src/app/app.component.1.ts new file mode 100644 index 0000000000..339661857a --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/app.component.1.ts @@ -0,0 +1,15 @@ +import { Component } from '@angular/core'; +import { FlowerService } from './flower.service'; +import { AnimalService } from './animal.service'; + + +@Component({ + selector: 'app-root', + templateUrl: './app.component.html', + styleUrls: [ './app.component.css' ] +}) +// #docregion injection +export class AppComponent { + constructor(public flower: FlowerService) {} +} +// #enddocregion injection diff --git a/aio/content/examples/providers-viewproviders/src/app/app.component.css b/aio/content/examples/providers-viewproviders/src/app/app.component.css new file mode 100755 index 0000000000..e69de29bb2 diff --git a/aio/content/examples/providers-viewproviders/src/app/app.component.html b/aio/content/examples/providers-viewproviders/src/app/app.component.html new file mode 100755 index 0000000000..1e958b5336 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/app.component.html @@ -0,0 +1,15 @@ + +

From AppComponent:

+ +

Emoji from FlowerService: {{flower.emoji}}

+ + +

Emoji from AnimalService: {{animal.emoji}}

+ + +
+ +

From ChildComponent:

+ + + diff --git a/aio/content/examples/providers-viewproviders/src/app/app.component.ts b/aio/content/examples/providers-viewproviders/src/app/app.component.ts new file mode 100755 index 0000000000..b656bdd94c --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/app.component.ts @@ -0,0 +1,15 @@ +import { Component } from '@angular/core'; +import { FlowerService } from './flower.service'; +import { AnimalService } from './animal.service'; + + +@Component({ + selector: 'app-root', + templateUrl: './app.component.html', + styleUrls: [ './app.component.css' ] +}) +// #docregion inject-animal-service +export class AppComponent { + constructor(public flower: FlowerService, public animal: AnimalService) {} +} +// #enddocregion inject-animal-service diff --git a/aio/content/examples/providers-viewproviders/src/app/app.module.ts b/aio/content/examples/providers-viewproviders/src/app/app.module.ts new file mode 100755 index 0000000000..eb20fc25b5 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/app.module.ts @@ -0,0 +1,17 @@ +import { NgModule } from '@angular/core'; +import { BrowserModule } from '@angular/platform-browser'; +import { FormsModule } from '@angular/forms'; + +import { AppComponent } from './app.component'; +import { ChildComponent } from './child/child.component'; +import { InspectorComponent } from './inspector/inspector.component'; + +// #docregion appmodule +@NgModule({ + imports: [ BrowserModule, FormsModule ], + declarations: [ AppComponent, ChildComponent, InspectorComponent ], + bootstrap: [ AppComponent ], + providers: [] +}) +export class AppModule { } +// #enddocregion appmodule diff --git a/aio/content/examples/providers-viewproviders/src/app/child/child.component.1.ts b/aio/content/examples/providers-viewproviders/src/app/child/child.component.1.ts new file mode 100644 index 0000000000..33b02df7f2 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/child/child.component.1.ts @@ -0,0 +1,19 @@ +import { Component, OnInit, Host, SkipSelf, Optional } from '@angular/core'; +import { FlowerService } from '../flower.service'; + +// #docregion flowerservice +@Component({ + selector: 'app-child', + templateUrl: './child.component.html', + styleUrls: ['./child.component.css'], + // use the providers array to provide a service + providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }] +}) + +export class ChildComponent { + // inject the service + constructor( public flower: FlowerService) { } +} + +// #enddocregion flowerservice + diff --git a/aio/content/examples/providers-viewproviders/src/app/child/child.component.css b/aio/content/examples/providers-viewproviders/src/app/child/child.component.css new file mode 100755 index 0000000000..13fdf763f4 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/child/child.component.css @@ -0,0 +1,4 @@ +.container { + border: 1px solid darkblue; + padding: 1rem; +} \ No newline at end of file diff --git a/aio/content/examples/providers-viewproviders/src/app/child/child.component.html b/aio/content/examples/providers-viewproviders/src/app/child/child.component.html new file mode 100755 index 0000000000..9bc45624f5 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/child/child.component.html @@ -0,0 +1,24 @@ + + + +

Emoji from FlowerService: {{flower.emoji}}

+ + +

Emoji from AnimalService: {{animal.emoji}}

+ + +
+

Content projection

+ +

The following is coming from content. It doesn't get to see the puppy because the puppy is declared inside the view only.

+ + +
+ +

Inside the view

+ +

The following is inside the view so it does see the puppy.

+ + + + diff --git a/aio/content/examples/providers-viewproviders/src/app/child/child.component.ts b/aio/content/examples/providers-viewproviders/src/app/child/child.component.ts new file mode 100755 index 0000000000..415bdc5506 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/child/child.component.ts @@ -0,0 +1,44 @@ +// #docplaster +import { Component, OnInit, Host, SkipSelf, Optional } from '@angular/core'; +import { FlowerService } from '../flower.service'; +import { AnimalService } from '../animal.service'; + +// #docregion provide-animal-service +@Component({ + selector: 'app-child', + templateUrl: './child.component.html', + styleUrls: ['./child.component.css'], + // provide services + providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }], + viewProviders: [{ provide: AnimalService, useValue: { emoji: '🐢' } }] +}) + +export class ChildComponent { + // inject service + constructor( public flower: FlowerService, public animal: AnimalService) { } +// #enddocregion provide-animal-service + + // viewProviders ensures that only the view gets to see this. + // With the AnimalService in the viewProviders, the + // InspectorComponent doesn't get to see it because the + // inspector is in the content. + + + // constructor( public flower: FlowerService, @Optional() @Host() public animal: AnimalService) { } + +// Comment out the above constructor and alternately +// uncomment the two following constructors to see the +// effects of @Host() and @Host() + @SkipSelf(). + +// constructor( +// @Host() public animal : AnimalService, +// @Host() @Optional() public flower : FlowerService) { } + +// constructor( +// @SkipSelf() @Host() public animal : AnimalService, +// @SkipSelf() @Host() @Optional() public flower : FlowerService) { } + +// #docregion provide-animal-service +} +// #enddocregion provide-animal-service + diff --git a/aio/content/examples/providers-viewproviders/src/app/flower.service.ts b/aio/content/examples/providers-viewproviders/src/app/flower.service.ts new file mode 100755 index 0000000000..00221005a3 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/flower.service.ts @@ -0,0 +1,11 @@ +import { Injectable } from '@angular/core'; + +// #docregion flowerservice +@Injectable({ + providedIn: 'root' +}) +export class FlowerService { + emoji = '🌺'; +} +// #enddocregion flowerservice + diff --git a/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.css b/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.css new file mode 100755 index 0000000000..e69de29bb2 diff --git a/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.html b/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.html new file mode 100755 index 0000000000..fe32d7578e --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.html @@ -0,0 +1,4 @@ + +

Emoji from FlowerService: {{flower.emoji}}

+

Emoji from AnimalService: {{animal.emoji}}

+ diff --git a/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.ts b/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.ts new file mode 100755 index 0000000000..d5e99835fe --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.ts @@ -0,0 +1,14 @@ +import { Component } from '@angular/core'; +import { FlowerService } from '../flower.service'; +import { AnimalService } from '../animal.service'; + +@Component({ + selector: 'app-inspector', + templateUrl: './inspector.component.html', + styleUrls: ['./inspector.component.css'] +}) +// #docregion injection +export class InspectorComponent { + constructor(public flower: FlowerService, public animal: AnimalService) { } +} +// #enddocregion injection diff --git a/aio/content/examples/providers-viewproviders/src/index.html b/aio/content/examples/providers-viewproviders/src/index.html new file mode 100644 index 0000000000..3f4775ce4a --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/index.html @@ -0,0 +1,14 @@ + + + + + providers vs. viewProviders + + + + + + + + + diff --git a/aio/content/examples/providers-viewproviders/src/main.ts b/aio/content/examples/providers-viewproviders/src/main.ts new file mode 100644 index 0000000000..91ec6da5f0 --- /dev/null +++ b/aio/content/examples/providers-viewproviders/src/main.ts @@ -0,0 +1,12 @@ +import { enableProdMode } from '@angular/core'; +import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; + +import { AppModule } from './app/app.module'; +import { environment } from './environments/environment'; + +if (environment.production) { + enableProdMode(); +} + +platformBrowserDynamic().bootstrapModule(AppModule) + .catch(err => console.log(err)); diff --git a/aio/content/examples/providers-viewproviders/stackblitz.json b/aio/content/examples/providers-viewproviders/stackblitz.json new file mode 100644 index 0000000000..f52293403f --- /dev/null +++ b/aio/content/examples/providers-viewproviders/stackblitz.json @@ -0,0 +1,10 @@ +{ + "description": "Inputs and Outputs", + "files": [ + "!**/*.d.ts", + "!**/*.js", + "!**/*.[1,2].*" + ], + "file": "src/app/app.component.ts", + "tags": ["Inputs and Outputs"] +} diff --git a/aio/content/examples/resolution-modifiers/e2e/src/app.e2e-spec.ts b/aio/content/examples/resolution-modifiers/e2e/src/app.e2e-spec.ts new file mode 100644 index 0000000000..4d8b621f1d --- /dev/null +++ b/aio/content/examples/resolution-modifiers/e2e/src/app.e2e-spec.ts @@ -0,0 +1,21 @@ +import { browser, element, by } from 'protractor'; + +describe('Resolution-modifiers-example', function () { + + beforeAll(function () { + browser.get(''); + }); + + it('shows basic flower emoji', function() { + expect(element.all(by.css('p')).get(0).getText()).toContain('🌸'); + }); + + it('shows basic leaf emoji', function() { + expect(element.all(by.css('p')).get(1).getText()).toContain('🌿'); + }); + + it('shows yellow flower in host child', function() { + expect(element.all(by.css('p')).get(9).getText()).toContain('🌼'); + }); + +}); diff --git a/aio/content/examples/resolution-modifiers/example-config.json b/aio/content/examples/resolution-modifiers/example-config.json new file mode 100644 index 0000000000..e69de29bb2 diff --git a/aio/content/examples/resolution-modifiers/src/app/app.component.css b/aio/content/examples/resolution-modifiers/src/app/app.component.css new file mode 100755 index 0000000000..e69de29bb2 diff --git a/aio/content/examples/resolution-modifiers/src/app/app.component.html b/aio/content/examples/resolution-modifiers/src/app/app.component.html new file mode 100755 index 0000000000..dc130393b2 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/app.component.html @@ -0,0 +1,14 @@ +

DI resolution modifiers

+ +

Basic flower service: {{flower.emoji}}

+

Basic leaf service: {{leaf.emoji}}

+ + + + + + + + + + diff --git a/aio/content/examples/resolution-modifiers/src/app/app.component.ts b/aio/content/examples/resolution-modifiers/src/app/app.component.ts new file mode 100755 index 0000000000..c0dc307793 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/app.component.ts @@ -0,0 +1,13 @@ +import { Component } from '@angular/core'; +import { LeafService } from './leaf.service'; +import { FlowerService } from './flower.service'; + +@Component({ + selector: 'app-root', + templateUrl: './app.component.html', + styleUrls: [ './app.component.css' ] +}) +export class AppComponent { + name = 'Angular'; + constructor(public flower: FlowerService, public leaf: LeafService) {} +} diff --git a/aio/content/examples/resolution-modifiers/src/app/app.module.ts b/aio/content/examples/resolution-modifiers/src/app/app.module.ts new file mode 100755 index 0000000000..dea2cd72a4 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/app.module.ts @@ -0,0 +1,33 @@ +; +import { OptionalComponent } from './optional/optional.component'; +import { NgModule } from '@angular/core'; +import { BrowserModule } from '@angular/platform-browser'; +import { FormsModule } from '@angular/forms'; + +import { AppComponent } from './app.component'; +import { SelfNoDataComponent } from './self-no-data/self-no-data.component'; +import { HostComponent } from './host/host.component'; +import { SelfComponent } from './self/self.component'; +import { SkipselfComponent } from './skipself/skipself.component'; +import { HostParentComponent } from './host-parent/host-parent.component'; +import { HostChildComponent } from './host-child/host-child.component'; + +@NgModule({ + imports: [ + BrowserModule, + FormsModule + ], + declarations: [ + AppComponent, + OptionalComponent, + SelfComponent, + SelfNoDataComponent, + HostComponent, + SkipselfComponent, + HostParentComponent, + HostChildComponent + ], + bootstrap: [AppComponent], + providers: [] +}) +export class AppModule { } diff --git a/aio/content/examples/resolution-modifiers/src/app/flower.service.ts b/aio/content/examples/resolution-modifiers/src/app/flower.service.ts new file mode 100755 index 0000000000..6c1eb7ff31 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/flower.service.ts @@ -0,0 +1,9 @@ +import { Injectable } from '@angular/core'; + +@Injectable({ + providedIn: 'root' // provide this service in the root ModuleInjector + +}) +export class FlowerService { + emoji = '🌸'; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.css b/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.html b/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.html new file mode 100755 index 0000000000..019e2d0e38 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.html @@ -0,0 +1,4 @@ +
+

Child of @Host() Component

+

Flower emoji: {{flower.emoji}}

+
diff --git a/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.ts b/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.ts new file mode 100755 index 0000000000..f0030b9518 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host-child/host-child.component.ts @@ -0,0 +1,11 @@ +import { Component } from '@angular/core'; +import { FlowerService } from '../flower.service'; + +@Component({ + selector: 'app-host-child', + templateUrl: './host-child.component.html', + styleUrls: ['./host-child.component.css'] +}) +export class HostChildComponent { + constructor(public flower: FlowerService) { } +} diff --git a/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.css b/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.html b/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.html new file mode 100755 index 0000000000..6a60002e12 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.html @@ -0,0 +1,5 @@ +
+

Parent of @Host() Component

+

Flower emoji: {{flower.emoji}}

+ +
diff --git a/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.ts b/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.ts new file mode 100755 index 0000000000..e35de55130 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host-parent/host-parent.component.ts @@ -0,0 +1,16 @@ +import { Component } from '@angular/core'; +import { FlowerService } from '../flower.service'; + + +@Component({ + selector: 'app-host-parent', + templateUrl: './host-parent.component.html', + styleUrls: ['./host-parent.component.css'], + providers: [{ provide: FlowerService, useValue: { emoji: '🌺' } }] + +}) +export class HostParentComponent { + + constructor(public flower: FlowerService) { } + +} diff --git a/aio/content/examples/resolution-modifiers/src/app/host/host.component.css b/aio/content/examples/resolution-modifiers/src/app/host/host.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host/host.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/host/host.component.html b/aio/content/examples/resolution-modifiers/src/app/host/host.component.html new file mode 100755 index 0000000000..b38f843af9 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host/host.component.html @@ -0,0 +1,6 @@ +
+

@Host() Component

+

Flower emoji: {{flower.emoji}}

+

(@Host() stops it here)

+ +
diff --git a/aio/content/examples/resolution-modifiers/src/app/host/host.component.ts b/aio/content/examples/resolution-modifiers/src/app/host/host.component.ts new file mode 100755 index 0000000000..7727bcd5a9 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/host/host.component.ts @@ -0,0 +1,21 @@ +import { Component, Host, Optional } from '@angular/core'; +import { FlowerService } from '../flower.service'; + +// #docregion host-component +@Component({ + selector: 'app-host', + templateUrl: './host.component.html', + styleUrls: ['./host.component.css'], + // provide the service + providers: [{ provide: FlowerService, useValue: { emoji: '🌼' } }] +}) +export class HostComponent { + // use @Host() in the constructor when injecting the service + constructor(@Host() @Optional() public flower: FlowerService) { } + +} +// #enddocregion host-component + +// if you take out @Host() and the providers array, flower will be red hibiscus + + diff --git a/aio/content/examples/resolution-modifiers/src/app/leaf.service.ts b/aio/content/examples/resolution-modifiers/src/app/leaf.service.ts new file mode 100755 index 0000000000..01673173b2 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/leaf.service.ts @@ -0,0 +1,11 @@ +import { Injectable } from '@angular/core'; + +@Injectable({ + providedIn: 'root' +}) +// #docregion leafservice +export class LeafService { + emoji = '🌿'; +} +// #enddocregion leafservice + diff --git a/aio/content/examples/resolution-modifiers/src/app/optional.service.ts b/aio/content/examples/resolution-modifiers/src/app/optional.service.ts new file mode 100755 index 0000000000..c536830551 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/optional.service.ts @@ -0,0 +1,7 @@ +import { Injectable } from '@angular/core'; + +@Injectable() +export class OptionalService { +} + +// This service isn't provided anywhere. diff --git a/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.css b/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.html b/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.html new file mode 100755 index 0000000000..f50285291a --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.html @@ -0,0 +1,4 @@ +
+

@Optional() Component

+

This component still works even though the OptionalService (notice @Optional() in the consturctor isn't provided or configured anywhere. Angular goes through tree and visibilty rules, and if it doesn't find the requested service, returns null.

+
diff --git a/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.ts b/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.ts new file mode 100755 index 0000000000..5f82713692 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/optional/optional.component.ts @@ -0,0 +1,21 @@ +import { Component, Optional } from '@angular/core'; +import { OptionalService } from '../optional.service'; + +@Component({ + selector: 'app-optional', + templateUrl: './optional.component.html', + styleUrls: ['./optional.component.css'] +}) + +// #docregion optional-component +export class OptionalComponent { + constructor(@Optional() public optional: OptionalService) {} +} +// #enddocregion optional-component + +// The OptionalService isn't provided here, in the @Injectable() +// providers array, or in the NgModule. If you remove @Optional() +// from the constructor, you'll get an error. + + + diff --git a/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.css b/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.html b/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.html new file mode 100755 index 0000000000..97d9f1ab4e --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.html @@ -0,0 +1,4 @@ +
+

@Self() Component (without a provider)

+

Leaf emoji: {{leaf?.emoji}}

+
diff --git a/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.ts b/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.ts new file mode 100755 index 0000000000..b4b508655f --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/self-no-data/self-no-data.component.ts @@ -0,0 +1,18 @@ +import { Component, Self, Optional } from '@angular/core'; +import { LeafService } from '../leaf.service'; + +// #docregion self-no-data-component +@Component({ + selector: 'app-self-no-data', + templateUrl: './self-no-data.component.html', + styleUrls: ['./self-no-data.component.css'] +}) +export class SelfNoDataComponent { + constructor(@Self() @Optional() public leaf: LeafService) { } +} + +// #enddocregion self-no-data-component + +// The app doesn't break because the value being available at self is optional. +// If you remove @Optional(), the app breaks. + diff --git a/aio/content/examples/resolution-modifiers/src/app/self/self.component.css b/aio/content/examples/resolution-modifiers/src/app/self/self.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/self/self.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/self/self.component.html b/aio/content/examples/resolution-modifiers/src/app/self/self.component.html new file mode 100755 index 0000000000..eda31cd7a4 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/self/self.component.html @@ -0,0 +1,4 @@ +
+

@Self() Component

+

Flower emoji: {{flower?.emoji}}

+
diff --git a/aio/content/examples/resolution-modifiers/src/app/self/self.component.ts b/aio/content/examples/resolution-modifiers/src/app/self/self.component.ts new file mode 100755 index 0000000000..6eae1681e6 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/self/self.component.ts @@ -0,0 +1,19 @@ +import { Component, Self } from '@angular/core'; +import { FlowerService } from '../flower.service'; + +// #docregion self-component +@Component({ + selector: 'app-self', + templateUrl: './self.component.html', + styleUrls: ['./self.component.css'], + providers: [{ provide: FlowerService, useValue: { emoji: '🌼' } }] + +}) +export class SelfComponent { + constructor(@Self() public flower: FlowerService) {} +} +// #enddocregion self-component + +// This component provides the FlowerService so the injector +// doesn't have to look further up the injector tree + diff --git a/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.css b/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.css new file mode 100755 index 0000000000..78336a3905 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.css @@ -0,0 +1,5 @@ +.section { + border: 2px solid #369; + padding: 1rem; + margin: 1rem 0; +} diff --git a/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.html b/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.html new file mode 100755 index 0000000000..282d5f826e --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.html @@ -0,0 +1,4 @@ +
+

@SkipSelf() Component

+

Leaf emoji: {{leaf.emoji}}

+
diff --git a/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.ts b/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.ts new file mode 100755 index 0000000000..c02115131a --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/app/skipself/skipself.component.ts @@ -0,0 +1,18 @@ +import { Component, SkipSelf } from '@angular/core'; +import { LeafService } from '../leaf.service'; + +// #docregion skipself-component +@Component({ + selector: 'app-skipself', + templateUrl: './skipself.component.html', + styleUrls: ['./skipself.component.css'], + // Angular would ignore this LeafService instance + providers: [{ provide: LeafService, useValue: { emoji: '🍁' } }] +}) +export class SkipselfComponent { + // Use @SkipSelf() in the constructor + constructor(@SkipSelf() public leaf: LeafService) { } +} +// #enddocregion skipself-component + +// @SkipSelf(): Specifies that the dependency resolution should start from the parent injector, not here. diff --git a/aio/content/examples/resolution-modifiers/src/index.html b/aio/content/examples/resolution-modifiers/src/index.html new file mode 100644 index 0000000000..bec136a975 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/index.html @@ -0,0 +1,14 @@ + + + + + DI Resolution Modifiers Example + + + + + + + Loading... + + diff --git a/aio/content/examples/resolution-modifiers/src/main.ts b/aio/content/examples/resolution-modifiers/src/main.ts new file mode 100644 index 0000000000..a9ca1caf8c --- /dev/null +++ b/aio/content/examples/resolution-modifiers/src/main.ts @@ -0,0 +1,11 @@ +import { enableProdMode } from '@angular/core'; +import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; + +import { AppModule } from './app/app.module'; +import { environment } from './environments/environment'; + +if (environment.production) { + enableProdMode(); +} + +platformBrowserDynamic().bootstrapModule(AppModule); diff --git a/aio/content/examples/resolution-modifiers/stackblitz.json b/aio/content/examples/resolution-modifiers/stackblitz.json new file mode 100644 index 0000000000..6bc4252b82 --- /dev/null +++ b/aio/content/examples/resolution-modifiers/stackblitz.json @@ -0,0 +1,10 @@ +{ + "description": "NgModules", + "files": [ + "!**/*.d.ts", + "!**/*.js", + "!**/*.[1,2].*" + ], + "file": "src/app/app.component.ts", + "tags": ["NgModules"] +} diff --git a/aio/content/guide/dependency-injection.md b/aio/content/guide/dependency-injection.md index 79f30ea22b..9be9c1797d 100644 --- a/aio/content/guide/dependency-injection.md +++ b/aio/content/guide/dependency-injection.md @@ -134,7 +134,7 @@ The `@NgModule()` and `@Component()` decorators have the `providers` metadata op Components are directives, and the `providers` option is inherited from `@Directive()`. You can also configure providers for directives and pipes at the same level as the component. -Learn more about [where to configure providers](guide/hierarchical-dependency-injection#where-to-register). +Learn more about [where to configure providers](guide/hierarchical-dependency-injection). diff --git a/aio/content/guide/hierarchical-dependency-injection.md b/aio/content/guide/hierarchical-dependency-injection.md index 4531f86584..1506ca8567 100644 --- a/aio/content/guide/hierarchical-dependency-injection.md +++ b/aio/content/guide/hierarchical-dependency-injection.md @@ -1,196 +1,1046 @@ -# Hierarchical Dependency Injectors +# Hierarchical injectors -The Angular dependency injection system is _hierarchical_. -There is a tree of injectors that parallels an app's component tree. -You can reconfigure the injectors at any level of that component tree. +Injectors in Angular have rules that you can leverage to +achieve the desired visibility in your apps. +By understanding these rules, you can determine in which +provider you should declare a provider. -This guide explores this system and how to use it to your advantage. -It uses examples based on this . +## Two injector hierarchies -{@a ngmodule-vs-comp} -{@a where-to-register} - -## Where to configure providers - -You can configure providers for different injectors in the injector hierarchy. -An internal platform-level injector is shared by all running apps. -The `AppModule` injector is the root of an app-wide injector hierarchy, and within -an NgModule, directive-level injectors follow the structure of the component hierarchy. - -The choices you make about where to configure providers lead to differences in the final bundle size, service _scope_, and service _lifetime_. - -When you specify providers in the `@Injectable()` decorator of the service itself (typically at the app root level), optimization tools such as those used by the CLI's production builds can perform *tree shaking*, which removes services that aren't used by your app. Tree shaking results in smaller bundle sizes. - -* Learn more about [tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers). - -You're likely to inject `UserService` in many places throughout the app and will want to inject the same service instance every time. Providing `UserService` through the `root` injector is a good choice, and is the default that the [Angular CLI](cli) uses when you generate a service for your app. - -
-
Platform injector
- -When you use `providedIn:'root'`, you are configuring the root injector for the _app_, which is the injector for `AppModule`. -The actual root of the entire injector hierarchy is a _platform injector_ that is the parent of app-root injectors. -This allows multiple apps to share a platform configuration. For example, a browser has only one URL bar, no matter how many apps you have running. - -The platform injector is used internally during bootstrap, to configure platform-specific dependencies. You can configure additional platform-specific providers at the platform level by supplying `extraProviders` using the `platformBrowser()` function. - -Learn more about dependency resolution through the injector hierarchy: -[What you always wanted to know about Angular Dependency Injection tree](https://blog.angularindepth.com/angular-dependency-injection-and-tree-shakeable-tokens-4588a8f70d5d) - - -
- -*NgModule-level* providers can be specified with `@NgModule()` `providers` metadata option, or in the `@Injectable()` `providedIn` option (with some module other than the root `AppModule`). - -Use the `@NgModule()` `providers` option if a module is [lazy loaded](guide/lazy-loading-ngmodules). The module's own injector is configured with the provider when that module is loaded, and Angular can inject the corresponding services in any class it creates in that module. If you use the `@Injectable()` option `providedIn: MyLazyloadModule`, the provider could be shaken out at compile time, if it is not used anywhere else in the app. - -* Learn more about [tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers). - -For both root-level and module-level injectors, a service instance lives for the life of the app or module, and Angular injects this one service instance in every class that needs it. - -*Component-level* providers configure each component instance's own injector. -Angular can only inject the corresponding services in that component instance or one of its descendant component instances. -Angular can't inject the same service instance anywhere else. - -A component-provided service may have a limited lifetime. -Each new instance of the component gets its own instance of the service. -When the component instance is destroyed, so is that service instance. - -In our sample app, `HeroComponent` is created when the application starts -and is never destroyed, -so the `HeroService` instance created for `HeroComponent` lives for the life of the app. -If you want to restrict `HeroService` access to `HeroComponent` and its nested -`HeroListComponent`, provide `HeroService` at the component level, in `HeroComponent` metadata. - -* See more [examples of component-level injection](#component-injectors) below. +There are two injector hierarchies in Angular: +1. `ModuleInjector` hierarchy—configure a `ModuleInjector` +in this hierarchy using an `@NgModule()` or `@Injectable()` annotation. +1. `ElementInjector` hierarchy—created implicitly at each +DOM element. An `ElementInjector` is empty by default +unless you configure it in the `providers` property on +`@Directive()` or `@Component()`. {@a register-providers-injectable} -### @Injectable-level configuration +### `ModuleInjector` -The `@Injectable()` decorator identifies every service class. The `providedIn` metadata option for a service class configures a specific injector (typically `root`) -to use the decorated class as a provider of the service. -When an injectable class provides its own service to the `root` injector, the service is available anywhere the class is imported. +The `ModuleInjector` can be configured in one of two ways: -The following example configures a provider for `HeroService` using the `@Injectable()` decorator on the class. +* Using the `@Injectable()` `providedIn` property to +refer to `@NgModule()`, or `root`. +* Using the `@NgModule()` `providers` array. - +
-This configuration tells Angular that the app's root injector is responsible for creating an -instance of `HeroService` by invoking its constructor, -and for making that instance available across the application. +

Tree-shaking and @Injectable()

-Providing a service with the app's root injector is a typical case, -and the CLI sets up this kind of a provider automatically for you -when generating a new service. -However, you might not always want to provide your service at the root level. -You might, for instance, want users to explicitly opt-in to using the service. +Using the `@Injectable()` `providedIn` property is preferable +to the `@NgModule()` `providers` +array because with `@Injectable()` `providedIn`, optimization +tools can perform +tree-shaking, which removes services that your app isn't +using and results in smaller bundle sizes. -Instead of specifying the `root` injector, you can set `providedIn` to a specific NgModule. - -For example, in the following excerpt, the `@Injectable()` decorator configures a provider -that is available in any injector that includes the `HeroModule`. - - - -This is generally no different from configuring the injector of the NgModule itself, -except that the service is tree-shakable if the NgModule doesn't use it. -It can be useful for a library that offers a particular service that some -components *might* want to inject optionally, -and leave it up to the app whether to provide the service. - -* Learn more about [tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers). - - -### @NgModule-level injectors - -You can configure a provider at the module level using the `providers` metadata option for a non-root NgModule, in order to limit the scope of the provider to that module. -This is the equivalent of specifying the non-root module in the `@Injectable()` metadata, except that the service provided via `providers` is not tree-shakable. - -You generally don't need to specify `AppModule` with `providedIn`, because the app's `root` injector is the `AppModule` injector. -However, if you configure a app-wide provider in the `@NgModule()` metadata for `AppModule`, -it overrides one configured for `root` in the `@Injectable()` metadata. -You can do this to configure a non-default provider of a service that is shared with multiple apps. - -Here is an example of the case where the component router configuration includes -a non-default [location strategy](guide/router#location-strategy) by listing its provider -in the `providers` list of the `AppModule`. - - - - -{@a register-providers-component} - -### @Component-level injectors - -Individual components within an NgModule have their own injectors. -You can limit the scope of a provider to a component and its children -by configuring the provider at the component level using the `@Component` metadata. - -The following example is a revised `HeroesComponent` that specifies `HeroService` in its `providers` array. `HeroService` can provide heroes to instances of this component, or to any child component instances. - - - -### Element injectors - -An injector does not actually belong to a component, but rather to the component instance's anchor element in the DOM. A different component instance on a different DOM element uses a different injector. - -Components are a special type of directive, and the `providers` property of -`@Component()` is inherited from `@Directive()`. -Directives can also have dependencies, and you can configure providers -in their `@Directive()` metadata. -When you configure a provider for a component or directive using the `providers` property, that provider belongs to the injector for the anchor DOM element. Components and directives on the same element share an injector. - - - -* Learn more about [Element Injectors in Angular](https://blog.angularindepth.com/a-curios-case-of-the-host-decorator-and-element-injectors-in-angular-582562abcf0a). - - - -## Injector bubbling - -Consider this guide's variation on the Tour of Heroes application. -At the top is the `AppComponent` which has some subcomponents, such as the `HeroesListComponent`. -The `HeroesListComponent` holds and manages multiple instances of the `HeroTaxReturnComponent`. -The following diagram represents the state of this three-level component tree when there are three instances of `HeroTaxReturnComponent` open simultaneously. - -
- injector tree -
- -When a component requests a dependency, Angular tries to satisfy that dependency with a provider registered in that component's own injector. -If the component's injector lacks the provider, it passes the request up to its parent component's injector. -If that injector can't satisfy the request, it passes the request along to the next parent injector up the tree. -The requests keep bubbling up until Angular finds an injector that can handle the request or runs out of ancestor injectors. -If it runs out of ancestors, Angular throws an error. - -If you have registered a provider for the same DI token at different levels, the first one Angular encounters is the one it uses to provide the dependency. If, for example, a provider is registered locally in the component that needs a service, Angular doesn't look for another provider of the same service. - - -
- -You can cap the bubbling by adding the `@Host()` parameter decorator on the dependant-service parameter -in a component's constructor. -The hunt for providers stops at the injector for the host element of the component. - -* See an [example](guide/dependency-injection-in-action#qualify-dependency-lookup) of using `@Host` together with `@Optional`, another parameter decorator that lets you handle the null case if no provider is found. - -* Learn more about the [`@Host` decorator and Element Injectors](https://blog.angularindepth.com/a-curios-case-of-the-host-decorator-and-element-injectors-in-angular-582562abcf0a). +Tree-shaking is especially useful for a library +because the application which uses the library may not have +a need to inject it. Read more +about [tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers) +in [DI Providers](guide/dependency-injection-providers).
-If you only register providers with the root injector at the top level (typically the root `AppModule`), the tree of injectors appears to be flat. -All requests bubble up to the root injector, whether you configured it with the `bootstrapModule` method, or registered all providers with `root` in their own services. +`ModuleInjector` is configured by the `@NgModule.providers` and +`NgModule.imports` property. `ModuleInjector` is a flattening of +all of the providers arrays which can be reached by following the +`NgModule.imports` recursively. + +Child `ModuleInjector`s are created when lazy loading other `@NgModules`. + +Provide services with the `providedIn` property of `@Injectable()` as follows: + +```ts + +import { Injectable } from '@angular/core'; + +@Injectable({ + providedIn: 'root' // <--provides this service in the root ModuleInjector +}) +export class ItemService { + name = 'telephone'; +} + +``` + +The `@Injectable()` decorator identifies a service class. +The `providedIn` property configures a specific `ModuleInjector`, +here `root`, which makes the service available in the `root` `ModuleInjector`. + +#### Platform injector + +There are two more injectors above `root`, an +additional `ModuleInjector` and `NullInjector()`. + +Consider how Angular bootstraps the app with the +following in `main.ts`: + +```javascript +platformBrowserDynamic().bootstrapModule(AppModule).then(ref => {...}) +``` + +The `bootstrapModule()` method creates a child injector of +the platform injector which is configured by the `AppModule`. +This is the `root` `ModuleInjector`. + +The `platformBrowserDynamic()` method creates an injector +configured by a `PlatformModule`, which contains platform-specific +dependencies. This allows multiple apps to share a platform +configuration. +For example, a browser has only one URL bar, no matter how +many apps you have running. +You can configure additional platform-specific providers at the +platform level by supplying `extraProviders` using the `platformBrowser()` function. + +The next parent injector in the hierarchy is the `NullInjector()`, +which is the top of the tree. If you've gone so far up the tree +that you are looking for a service in the `NullInjector()`, you'll +get an error unless you've used `@Optional()` because ultimately, +everything ends at the `NullInjector()` and it returns an error or, +in the case of `@Optional()`, `null`. For more information on +`@Optional()`, see the [`@Optional()` section](guide/hierarchical-dependency-injection#optional) of this guide. + +The following diagram represents the relationship between the +`root` `ModuleInjector` and its parent injectors as the +previous paragraphs describe. + +
+ NullInjector, ModuleInjector, root injector +
+ +While the name `root` is a special alias, other `ModuleInjector`s +don't have aliases. You have the option to create `ModuleInjector`s +whenever a dynamically loaded component is created, such as with +the Router, which will create child `ModuleInjector`s. + +All requests forward up to the root injector, whether you configured it +with the `bootstrapModule()` method, or registered all providers +with `root` in their own services. + +
+ +

@Injectable() vs. @NgModule()

+ +If you configure an app-wide provider in the `@NgModule()` of +`AppModule`, it overrides one configured for `root` in the +`@Injectable()` metadata. You can do this to configure a +non-default provider of a service that is shared with multiple apps. + +Here is an example of the case where the component router +configuration includes +a non-default [location strategy](guide/router#location-strategy) +by listing its provider +in the `providers` list of the `AppModule`. + + + + + +
+ +### `ElementInjector` + +Angular creates `ElementInjector`s implicitly for each DOM element. + +
+ +**Note:** Specifically, `ElementInjector` is more nunaced +in that they are created _sparsely_. For a mental model +though, assume that each DOM element gets an `ElementInjector`. + +
+ +Providing a service in the `@Component()` decorator using +its `providers` or `viewProviders` +property configures an `ElementInjector`. +For example, the following `TestComponent` configures the `ElementInjector` +by providing the service as follows: + +```ts +@Component({ + ... + providers: [{ provide: ItemService, useValue: { name: 'lamp' } }] +}) +export class TestComponent + +``` + +
+ +**Note:** `ModuleInjector` is not a parent of `ElementInjector`. +In theory, each element can have a different `ModuleInjector`. +Think of it as `ModuleInjector` is plan-b when the +`ElementInjector` hierarchy can't resolve it. + +
+ + +When you provide services in a component, that service is available via +the `ElementInjector` at that component instance. +It may also be visible at +child component/directives based on visibility rules described in the [resolution rules](guide/hierarchical-dependency-injection#resolution-rules) section. + +When the component instance is destroyed, so is that service instance. + +#### `@Directive()` and `@Component()` + +A component is a special type of directive, which means that +just as `@Directive()` has a `providers` property, `@Component()` does too. +This means that directives as well as components can configure +providers, using the `providers` property. +When you configure a provider for a component or directive +using the `providers` property, +that provider belongs to the `ElementInjector` of that component or +directive. +Components and directives on the same element share an injector. + + +{@a resolution-rules} + +## Resolution rules + +When resolving a token for a component/directive, Angular +resolves it in two phases: + +1. Against the `ElementInjector` hierarchy (its parents) +1. Against the `ModuleInjector` hierarchy (its parents) + +When a component declares a dependency, Angular tries to satisfy that +dependency with its own `ElementInjector`. +If the component's injector lacks the provider, it passes the request +up to its parent component's `ElementInjector`. + +The requests keep forwarding up until Angular finds an injector that can +handle the request or runs out of ancestor `ElementInjector`s. + +If Angular doesn't find the provider in any `ElementInjector`s, +it goes back to the element where the request originated and looks +in the `ModuleInjector` hierarchy. +If Angular still doesn't find the provider, it throws an error. + +If you have registered a provider for the same DI token at +different levels, the first one Angular encounters is the one +it uses to resolve the dependency. If, for example, a provider +is registered locally in the component that needs a service, +Angular doesn't look for another provider of the same service. + + +## Resolution modifiers + +Angular's resolution behavior can be modified with `@Optional()`, `@Self()`, +`@SkipSelf()` and `@Host()`. Import each of them from `@angular/core` +and use each in the component class constructor when you inject your service. + +For a working app showcasing the resolution modifiers that +this section covers, see the resolution modifiers example. + +### Types of modifiers + +Resolution modifiers fall into three categories: + +1. What to do if Angular doesn't find what you're +looking for, that is `@Optional()` +2. Where to start looking, that is `@SkipSelf()` +3. Where to stop looking, `@Host()` and `@Self()` + +By default, Angular always starts at the current `Injector` and keeps +searching all the way up. Modifiers allow you to change the starting +(self) or ending location. + +Additionally, you can combine all of the modifiers except `@Host()` and `@Self()` and of course `@Skipself()` and `@Self()`. + +{@a optional} + +### `@Optional()` + +`@Optional()` allows Angular to consider a service you inject to be optional. +This way, if it can't be resolved at runtime, Angular simply +resolves the service as `null`, rather than throwing an error. In +the following example, the service, `OptionalService`, isn't provided in +the service, `@NgModule()`, or component class, so it isn't available +anywhere in the app. + + + + + + +### `@Self()` + +Use `@Self()` so that Angular will only look at the `ElementInjector` for the current component or directive. + +A good use case for `@Self()` is to inject a service but only if it is +available on the current host element. To avoid errors in this situation, +combine `@Self()` with `@Optional()`. + +For example, in the following `SelfComponent`, notice +the injected `LeafService` in +the constructor. + + + + + +In this example, there is a parent provider and injecting the +service will return the value, however, injecting the service +with `@Self()` and `@Optional()` will return `null` because +`@Self()` tells the injector to stop searching in the current +host element. + +Another example shows the component class with a provider +for `FlowerService`. In this case, the injector looks no further +than the current `ElementInjector` because it finds the `FlowerService` and returns the yellow flower 🌼. + + + + + + +### `@SkipSelf()` + +`@SkipSelf()` is the opposite of `@Self()`. With `@SkipSelf()`, Angular +starts its search for a service in the parent `ElementInjector`, rather than +in the current one. So if the parent `ElementInjector` were using the value `🌿` (fern) +for `emoji` , but you had `🍁` (maple leaf) in the component's `providers` array, +Angular would ignore `🍁` (maple leaf) and use `🌿` (fern). + +To see this in code, assume that the following value for `emoji` is what the parent component were using, as in this service: + + + + + +Imagine that in the child component, you had a different value, `🍁` (maple leaf) but you wanted to use the parent's value instead. This is when you'd use `@SkipSelf()`: + + + + + +In this case, the value you'd get for `emoji` would be `🌿` (fern), not `🍁` (maple leaf). + +#### `@SkipSelf()` with `@Optional()` + +Use `@SkipSelf()` with `@Optional()` to prevent an error if the value is `null`. In the following example, the `Person` service is injected in the constructor. `@SkipSelf()` tells Angular to skip the current injector and `@Optional()` will prevent an error should the `Person` service be `null`. + +``` ts +class Person { + constructor(@Optional() @SkipSelf() parent: Person) {} +} +``` + +### `@Host()` + +`@Host()` lets you designate a component as the last stop in the injector tree when searching for providers. Even if there is a service instance further up the tree, Angular won't continue looking. Use `@Host()` as follows: + + + + + + +Since `HostComponent` has `@Host()` in its constructor, no +matter what the parent of `HostComponent` might have as a +`flower.emoji` value, +the `HostComponent` will use `🌼` (yellow flower). + + +## Logical structure of the template + +When you provide services in the component class, services are +visible within the `ElementInjector` tree relative to where +and how you provide those services. + +Understanding the underlying logical structure of the Angular +template will give you a foundation for configuring services +and in turn control their visibility. + +Components are used in your templates, as in the following example: + +``` + + + +``` + +
+ +**Note:** Usually, you declare the components and their +templates in separate files. For the purposes of understanding +how the injection system works, it is useful to look at them +from the point of view of a combined logical tree. The term +logical distinguishes it from the render tree (your application +DOM tree). To mark the locations of where the component +templates are located, this guide uses the `<#VIEW>` +pseudo element, which doesn't actually exist in the render tree +and is present for mental model purposes only. + +
+ +The following is an example of how the `` and `` view trees are combined into a single logical tree: + +``` + + <#VIEW> + + <#VIEW> + ...content goes here... + + + <#VIEW> + + ``` + +Understanding the idea of the `<#VIEW>` demarcation is especially significant when you configure services in the component class. + +## Providing services in `@Component()` + +How you provide services via an `@Component()` (or `@Directive()`) +decorator determines their visibility. The following sections +demonstrate `providers` and `viewProviders` along with ways to +modify service visibility with `@SkipSelf()` and `@Host()`. + +A component class can provide services in two ways: + +1. with a `providers` array + +```typescript= +@Component({ + ... + providers: [ + {provide: FlowerService, useValue: {emoji: '🌺'}} + ] +}) +``` + +2. with a `viewProviders` array + +```typescript= +@Component({ + ... + viewProviders: [ + {provide: AnimalService, useValue: {emoji: '🐢'}} + ] +}) +``` + +To understand how the `providers` and `viewProviders` influence service +visibility differently, the following sections build +a +step-by-step and compare the use of `providers` and `viewProviders` +in code and a logical tree. + +
+ +**NOTE:** In the logical tree, you'll see `@Provide`, `@Inject`, and +`@NgModule`, which are not real HTML attributes but are here to demonstrate +what is going on under the hood. + +- `@Inject(Token)=>Value` demonstrates that if `Token` is injected at +this location in the logical tree its value would be `Value`. +- `@Provide(Token=Value)` demonstrates that there is a declaration of +`Token` provider with value `Value` at this location in the logical tree. +- `@NgModule(Token)` demonstrates that a fallback `NgModule` injector +should be used at this location. + +
+ + +### Example app structure + +The example app has a `FlowerService` provided in `root` with an `emoji` +value of `🌺` (red hibiscus). + + + + + +Consider a simple app with only an `AppComponent` and a `ChildComponent`. +The most basic rendered view would look like nested HTML elements such as +the following: + +``` + + + + +``` + +However, behind the scenes, Angular uses a logical view +representation as follows when resolving injection requests: + +``` + + <#VIEW> + + <#VIEW> + + + + + ``` + +The `<#VIEW>` here represents an instance of a template. +Notice that each component has its own `<#VIEW>`. + +Knowledge of this structure can inform how you provide and +inject your services, and give you complete control of service visibility. + +Now, consider that `` simply injects the `FlowerService`: + + + + + + +Add a binding to the `` template to visualize the result: + + + + + + +The output in the view would be: + +``` +Emoji from FlowerService: 🌺 +``` + +In the logical tree, this would be represented as follows: + +``` +"🌺"> + <#VIEW> +

Emoji from FlowerService: {{flower.emoji}} (🌺)

+ + <#VIEW> + + + + +``` + +When `` requests the `FlowerService`, it is the injector's job +to resolve the `FlowerService` token. The resolution of the token happens +in two phases: + +1. The injector determines the starting location in the logical tree and +an ending location of the search. The injector begins with the starting +location and looks for the token at each level in the logical tree. If +the token is found it is returned. +2. If the token is not found, the injector looks for the closest +parent `@NgModule()` to delegate the request to. + +In the example case, the constraints are: + +1. Start with `<#VIEW>` belonging to `` and end with ``. + + - Normally the starting point for search is at the point + of injection. However, in this case `` `@Component`s + are special in that they also include their own `viewProviders`, + which is why the search starts at `<#VIEW>` belonging to ``. + (This would not be the case for a directive matched at the same location). + - The ending location just happens to be the same as the component + itself, because it is the topmost component in this application. + +2. The `MyAppModule` acts as the fallback injector when the +injection token can't be found in the `ElementInjector`s. + +### Using the `providers` array + +Now, in the `ChildComponent` class, add a provider for `FlowerService` +to demonstrate more complex resolution rules in the upcoming sections: + + + + + +Now that the `FlowerService` is provided in the `@Component()` decorator, +when the `` requests the service, the injector has only to look +as far as the ``'s own `ElementInjector`. It won't have to +continue the search any further through the injector tree. + +The next step is to add a binding to the `ChildComponent` template. + + + + + +To render the new values, add `` to the bottom of +the`MyAppComponent` template so the view also displays the sunflower: + +``` +Child Component +Emoji from FlowerService: 🌻 +``` + +In the logical tree, this would be represented as follows: + +``` +"🌺"> + <#VIEW> +

Emoji from FlowerService: {{flower.emoji}} (🌺)

+ "🌻"> + <#VIEW> +

Parent Component

+

Emoji from FlowerService: {{flower.emoji}} (🌻)

+ + + + +``` + +When `` requests the `FlowerService`, the injector begins +its search at the `<#VIEW>` belonging to `` (`<#VIEW>` is +included because it is injected from `@Component()`) and ends with +``. In this case, the `FlowerService` is resolved in the +``'s `providers` array with sunflower 🌻. The injector doesn't +have to look any further in the injector tree. It stops as soon as it as it +finds the `FlowerService` and never sees the 🌺 (red hibiscus). + + +{@a use-view-providers} + +### Using the `viewProviders` array + +Use the `viewProviders` array as another way to provide services in the +`@Component()` decorator. Using `viewProviders` makes services +visibile in the `<#VIEW>`. + +
+ +The steps are the same as using the `providers` array, +with the exception of using the `viewProviders` array instead. + +For step-by-step instructions, continue with this section. If you can +set it up on your own, skip ahead to [Modifying service availability](guide/hierarchical-dependency-injection#modify-visibility). + +
+ + +The example app features a second service, the `AnimalService` to +demonstrate `viewProviders`. + +First, create an `AnimalService` with an `emoji` property of whale 🐳: + + + + + + +Following the same pattern as with the `FlowerService`, inject the +`AnimalService` in the `AppComponent` class: + + + + + +
+ +**Note:** You can leave all the `FlowerService` related code in place +as it will allow a comparison with the `AnimalService`. + +
+ +Add a `viewProviders` array and inject the `AnimalService` in the +`` class, too, but give `emoji` a different value. Here, +it has a value of 🐢 (puppy). + + + + + + +Add bindings to the `ChildComponent` and the `MyAppComponent` templates. +In the `ChildComponent` template, add the following binding: + + + + + +Additionally, add the same to the `AppComponent` template: + + + + + +Now you should see both values in the browser: + +``` +AppComponent +Emoji from AnimalService: 🐳 + +Child Component +Emoji from AnimalService: 🐢 + +``` + +The logic tree for this example of `viewProviders` is as follows: + + +``` +"🐳"> + <#VIEW> + + <#VIEW + @Provide(AnimalService="🐢") + @Inject(AnimalService=>"🐢")> + +

Emoji from AnimalService: {{animal.emoji}} (🐢)

+ + + + +``` + +Just as with the `FlowerService` example, the `AnimalService` is provided +in the `` `@Component()` decorator. This means that since the +injector first looks in the `ElementInjector` of the component, it finds the +`AnimalService` value of 🐢 (puppy). It doesn't need to continue searching the +`ElementInjector` tree, nor does it need to search the `ModuleInjector`. + +### `providers` vs. `viewProviders` + +To see the difference between using `providers` and `viewProviders`, add +another component to the example and call it `InspectorComponent`. +`InspectorComponent` will be a child of the `ChildComponent`. In +`inspector.component.ts`, inject the `FlowerService` and `AnimalService` in +the constructor: + + + + + + +You do not need a `providers` or `viewProviders` array. Next, in +`inspector.component.html`, add the same markup from previous components: + + + + + +Remember to add the `InspectorComponent` to the `AppModule` `declarations` array. + + + + + + +Next, make sure your `child.component.html` contains the following: + + + + + +The first two lines, with the bindings, are there from previous steps. The +new parts are `` and ``. `` allows +you to project content, and `` inside the `ChildComponent` + template makes the `InspectorComponent` a child component of + `ChildComponent`. + +Next, add the following to `app.component.html` to take advantage of content projection. + + + + + +The browser now renders the following, omitting the previous examples +for brevity: + +``` + +//...Omitting previous examples. The following applies to this section. + +Content projection: This is coming from content. Doesn't get to see +puppy because the puppy is declared inside the view only. + +Emoji from FlowerService: 🌻 +Emoji from AnimalService: 🐳 + +Emoji from FlowerService: 🌻 +Emoji from AnimalService: 🐢 + +``` + +These four bindings demonstrate the difference between `providers` +and `viewProviders`. Since the 🐢 (puppy) is declared inside the <#VIEW>, +it isn't visible to the projected content. Instead, the projected +content sees the 🐳 (whale). + +The next section though, where `InspectorComponent` is a child component +of `ChildComponent`, `InspectorComponent` is inside the `<#VIEW>`, so +when it asks for the `AnimalService`, it sees the 🐢 (puppy). + +The `AnimalService` in the logical tree would look like this: + +``` +"🐳"> + <#VIEW> + + <#VIEW + @Provide(AnimalService="🐢") + @Inject(AnimalService=>"🐢")> + +

Emoji from AnimalService: {{animal.emoji}} (🐢)

+ +

Emoji from AnimalService: {{animal.emoji}} (🐢)

+ + + + <#VIEW> +

Emoji from AnimalService: {{animal.emoji}} (🐳)

+ + + + + +``` + +The projected content of `` sees the whale 🐳, not +the 🐢 (puppy), because the +🐢 (puppy) is inside the `` `<#VIEW>`. The `` can +only see the 🐢 (puppy) +if it is also within the `<#VIEW>`. + +{@a modify-visibility} + +## Modifying service visibility + +This section describes how to limit the scope of the beginning and +ending `ElementInjector` using the visibility decorators `@Host()`, +`@Self()`, and `@SkipSelf()`. + +### Visibility of provided tokens + +Visibility decorators influence where the search for the injection +token begins and ends in the logic tree. To do this, place +visibility decorators at the point of injection, that is, the +`constructor()`, rather than at a point of declaration. + +To alter where the injector starts looking for `FlowerService`, add +`@SkipSelf()` to the `` `@Inject` declaration for the +`FlowerService`. This declaration is in the `` constructor +as shown in `child.component.ts`: + +```typescript= + constructor(@SkipSelf() public flower : FlowerService) { } +``` + +With `@SkipSelf()`, the `` injector doesn't look to itself for +the `FlowerService`. Instead, the injector starts looking for the +`FlowerService` at the ``'s `ElementInjector`, where it finds +nothing. Then, it goes back to the `` `ModuleInjector` and finds +the 🌺 (red hibiscus) value, which is available because the `` +`ModuleInjector` and the `` `ModuleInjector` are flattened into one + `ModuleInjector`. Thus, the UI renders the following: + +``` +Emoji from FlowerService: 🌺 +``` + +In a logical tree, this same idea might look like this: + +``` +"🌺"> + <#VIEW> + + <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺"> + + + + + +``` + +Though `` provides the 🌻 (sunflower), the app renders +the 🌺 (red hibiscus) because `@SkipSelf()` causes the current +injector to skip +itself and look to its parent. + +If you now add `@Host()` (in addition to the `@SkipSelf()`) to the +`@Inject` of the `FlowerService`, the result will be `null`. This is +because `@Host()` limits the upper bound of the search to the +`<#VIEW>`. Here's the idea in the logical tree: + +``` +"🌺"> + <#VIEW> + + <#VIEW @Inject(FlowerService, @SkipSelf, @Host, @Optional)=>null> + + + + +``` + +Here, the services and their values are the same, but `@Host()` +stops the injector from looking any further than the `<#VIEW>` +for `FlowerService`, so it doesn't find it and returns `null`. + +
+ +**Note:** The example app uses `@Optional()` so the app does +not throw an error, but the principles are the same. + +
+ +### `@SkipSelf()` and `viewProviders` + +The `` currently provides the `AnimalService` in +the `viewProviders` array with the value of 🐢 (puppy). Because +the injector has only to look at the ``'s `ElementInjector` +for the `AnimalService`, it never sees the 🐳 (whale). + +Just as in the `FlowerService` example, if you add `@SkipSelf()` +to the constructor for the `AnimalService`, the injector won't +look in the current ``'s `ElementInjector` for the +`AnimalService`. + +```typescript= +export class ChildComponent { + +// add @SkipSelf() + constructor(@SkipSelf() public animal : AnimalService) { } + +} +``` + +Instead, the injector will begin at the `` +`ElementInjector`. Remember that the `` class +provides the `AnimalService` in the `viewProviders` array +with a value of 🐢 (puppy): + +```ts +@Component({ + selector: 'app-child', + ... + viewProviders: + [{ provide: AnimalService, useValue: { emoji: '🐢' } }] +}) +``` + +The logical tree looks like this with `@SkipSelf()` in ``: + +``` + "🐳")> + <#VIEW> + + <#VIEW + @Provide(AnimalService="🐢") + @Inject(AnimalService, SkipSelf=>"🐳")> + + + + + +``` + +With `@SkipSelf()` in the ``, the injector begins its +search for the `AnimalService` in the `` `ElementInjector` +and finds 🐳 (whale). + +### `@Host()` and `viewProviders` + +If you add `@Host()` to the constructor for `AnimalService`, the +result is 🐢 (puppy) because the injector finds the `AnimalService` +in the `` `<#VIEW>`. Here is the `viewProviders` array +in the `` class and `@Host()` in the constructor: + +```typescript= +@Component({ + selector: 'app-child', + ... + viewProviders: + [{ provide: AnimalService, useValue: { emoji: '🐢' } }] + +}) +export class ChildComponent { + constructor(@Host() public animal : AnimalService) { } +} +``` + +`@Host()` causes the injector to look until it encounters the edge of the `<#VIEW>`. + +``` + "🐳")> + <#VIEW> + + <#VIEW + @Provide(AnimalService="🐢") + @Inject(AnimalService, @Host=>"🐢")> + + + + +``` + +However, if you use `@Host()` and `@SkipSelf()` for the `AnimalService` +as follows, you'll get 🐢 (puppy) because that's the value in the +``. Here are `@Host()` and `@SkipSelf()` in the `` +constructor : + +```ts +export class ChildComponent { + + constructor( + @Host() @SkipSelf() public animal : AnimalService) { } + +} +``` + +When `@Host()` and `SkipSelf()` were applied to the `FlowerService`, +which is in the `providers` array, the result was `null` because +`@SkipSelf()` starts its search in the `` injector, but +`@Host()` stops searching at `<#VIEW>`—where there is no +`FlowerService`. In the logical tree, you can see that the +`FlowerService` is visible in ``, not its `<#VIEW>`. + +However, the `AnimalService`, which is provided in the +`ParentComponent` `viewProviders` array, is visible. + +The logical tree representation shows why this is: + +```html +"🐳")> + <#VIEW> + + + <#VIEW @Provide(AnimalService="🐢") + @Inject(AnimalService, @SkipSelf, @Host, @Optional)=>"🐢"> + + + + + +``` + +`@SkipSelf()`, causes the injector to start its search for +the `AnimalService` at the ``, not the ``, +where the request originates, and `@Host()` stops the search +at the `` `<#VIEW>`. Since `AnimalService` is +provided via the `viewProviders` array, the injector finds 🐢 +(puppy) in the `<#VIEW>`. + {@a component-injectors} -## Component injectors +## `ElementInjector` use case examples -The ability to configure one or more providers at different levels opens up interesting and useful possibilities. -The guide sample offers some scenarios where you might want to do so. +The ability to configure one or more providers at different levels +opens up useful possibilities. +For a look at the following scenarios in a working app, see the heroes use case examples. ### Scenario: service isolation @@ -198,19 +1048,30 @@ Architectural reasons may lead you to restrict access to a service to the applic For example, the guide sample includes a `VillainsListComponent` that displays a list of villains. It gets those villains from a `VillainsService`. -If you provide `VillainsService` in the root `AppModule` (where you registered the `HeroesService`), -that would make the `VillainsService` available everywhere in the application, including the _Hero_ workflows. If you later modified the `VillainsService`, you could break something in a hero component somewhere. Providing the service in the root `AppModule` creates that risk. +If you provided `VillainsService` in the root `AppModule` +(where you registered the `HeroesService`), +that would make the `VillainsService` visible everywhere in the +application, including the _Hero_ workflows. If you later +modified the `VillainsService`, you could break something in a +hero component somewhere. Instead, you can provide the `VillainsService` in the `providers` metadata of the `VillainsListComponent` like this: - + + + By providing `VillainsService` in the `VillainsListComponent` metadata and nowhere else, the service becomes available only in the `VillainsListComponent` and its sub-component tree. -It's still a singleton, but it's a singleton that exist solely in the _villain_ domain. -Now you know that a hero component can't access it. You've reduced your exposure to error. +`VillainService` is a singleton with respect to `VillainsListComponent` +because that is where it is declared. As long as `VillainsListComponent` +does not get destroyed it will be the same instance of `VillainService` +but if there are multilple instances of `VillainsListComponent`, then each +instance of `VillainsListComponent` will have its own instance of `VillainService`. + + ### Scenario: multiple edit sessions @@ -235,13 +1096,12 @@ Each tax return component has the following characteristics: Heroes in action -Suppose that the `HeroTaxReturnComponent` has logic to manage and restore changes. +Suppose that the `HeroTaxReturnComponent` had logic to manage and restore changes. That would be a pretty easy task for a simple hero tax return. In the real world, with a rich tax return data model, the change management would be tricky. You could delegate that management to a helper service, as this example does. -Here is the `HeroTaxReturnService`. -It caches a single `HeroTaxReturn`, tracks changes to that return, and can save or restore it. +The `HeroTaxReturnService` caches a single `HeroTaxReturn`, tracks changes to that return, and can save or restore it. It also delegates to the application-wide singleton `HeroService`, which it gets by injection. @@ -249,7 +1109,7 @@ It also delegates to the application-wide singleton `HeroService`, which it gets -Here is the `HeroTaxReturnComponent` that makes use of it. +Here is the `HeroTaxReturnComponent` that makes use of `HeroTaxReturnService`. @@ -257,7 +1117,7 @@ Here is the `HeroTaxReturnComponent` that makes use of it. -The _tax-return-to-edit_ arrives via the input property which is implemented with getters and setters. +The _tax-return-to-edit_ arrives via the `@Input()` property, which is implemented with getters and setters. The setter initializes the component's own instance of the `HeroTaxReturnService` with the incoming return. The getter always returns what that service says is the current state of the hero. The component also asks the service to save and restore this tax return. @@ -265,10 +1125,13 @@ The component also asks the service to save and restore this tax return. This won't work if the service is an application-wide singleton. Every component would share the same service instance, and each component would overwrite the tax return that belonged to another hero. -To prevent this, we configure the component-level injector of `HeroTaxReturnComponent` to provide the service, using the `providers` property in the component metadata. +To prevent this, configure the component-level injector of `HeroTaxReturnComponent` to provide the service, using the `providers` property in the component metadata. - + + + + The `HeroTaxReturnComponent` has its own provider of the `HeroTaxReturnService`. Recall that every component _instance_ has its own injector. @@ -277,11 +1140,9 @@ Providing the service at the component level ensures that _every_ instance of th
- The rest of the scenario code relies on other Angular features and techniques that you can learn about elsewhere in the documentation. You can review it and download it from the . -
@@ -318,11 +1179,8 @@ its injector produces an instance of `Car` resolved by injector (C) with an `Eng +
-
+## More on dependency injection - -The code for this _cars_ scenario is in the `car.components.ts` and `car.services.ts` files of the sample -which you can review and download from the . - -
+For more information on Angular dependency injection, see the [DI Providers](guide/dependency-injection-providers) and [DI in Action](guide/dependency-injection-in-action) guides. diff --git a/aio/content/images/guide/dependency-injection/injectors.svg b/aio/content/images/guide/dependency-injection/injectors.svg new file mode 100644 index 0000000000..96df04afba --- /dev/null +++ b/aio/content/images/guide/dependency-injection/injectors.svg @@ -0,0 +1 @@ +NullInjector()always throws an error unlessyou use @Optional()ModuleInjector(configured by PlatformModule)has special things like DomSanitizer => platformBrowser()rootModuleInjector(configured by YourAppModule)has things for your app  => bootstrapModule(YourAppModule) \ No newline at end of file