docs: clarify hierarchical injectors (#28700)

PR Close #28700

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('🌻');
+  });
+
+});
+

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

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

aio/content/examples/providers-viewproviders/src/app/app.component.html

@@ -0,0 +1,15 @@
+
+<h2>From AppComponent:</h2>
+<!-- #docregion binding-flower -->
+<p>Emoji from FlowerService: {{flower.emoji}}</p>
+<!-- #enddocregion binding-flower -->
+<!-- #docregion binding-animal -->
+<p>Emoji from AnimalService: {{animal.emoji}}</p>
+<!-- #enddocregion binding-animal -->
+
+<hr />
+
+<h2>From ChildComponent:</h2>
+<!-- #docregion content-projection -->
+<app-child><app-inspector></app-inspector></app-child>
+<!-- #enddocregion content-projection -->

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

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

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
+

aio/content/examples/providers-viewproviders/src/app/child/child.component.css

@@ -0,0 +1,4 @@
+.container {
+  border: 1px solid darkblue;
+  padding: 1rem;
+}

aio/content/examples/providers-viewproviders/src/app/child/child.component.html

@@ -0,0 +1,24 @@
+<!-- #docplaster -->
+<!-- #docregion child-component -->
+<!-- #docregion flower-binding -->
+<p>Emoji from FlowerService: {{flower.emoji}}</p>
+<!-- #enddocregion flower-binding -->
+<!-- #docregion animal-binding -->
+<p>Emoji from AnimalService: {{animal.emoji}}</p>
+<!-- #enddocregion animal-binding -->
+
+<div class="container">
+  <h3>Content projection</h3>
+  <!-- #enddocregion child-component -->
+  <p>The following is coming from content. It doesn't get to see the puppy because the puppy is declared inside the view only.</p>
+  <!-- #docregion child-component -->
+	<ng-content></ng-content>
+</div>
+
+<h3>Inside the view</h3>
+<!-- #enddocregion child-component -->
+<p>The following is inside the view so it does see the puppy.</p>
+<!-- #docregion child-component -->
+<app-inspector></app-inspector>
+<!-- #enddocregion child-component -->
+

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
+

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
+

aio/content/examples/providers-viewproviders/src/app/inspector/inspector.component.html

@@ -0,0 +1,4 @@
+ <!-- #docregion binding -->
+<p>Emoji from FlowerService: {{flower.emoji}}</p>
+<p>Emoji from AnimalService: {{animal.emoji}}</p>
+ <!-- #enddocregion binding -->

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

aio/content/examples/providers-viewproviders/src/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>providers vs. viewProviders</title>
+  <base href="/">
+
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="icon" type="image/x-icon" href="favicon.ico">
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>

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));

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"]
+}