docs(aio): add NgModule docs (#20306)

PR Close #20306

aio/content/examples/ngmodule-faq/src/app/app-routing.module.3.ts

@@ -0,0 +1,19 @@
+import { NgModule } from '@angular/core';
+import { Routes, RouterModule } from '@angular/router';
+
+import { ContactModule } from './contact/contact.module.3';
+
+const routes: Routes = [
+  { path: '', redirectTo: 'contact', pathMatch: 'full'},
+  { path: 'crisis', loadChildren: 'app/crisis/crisis.module#CrisisModule' },
+  { path: 'heroes', loadChildren: 'app/hero/hero.module.3#HeroModule' }
+];
+
+@NgModule({
+  imports: [
+    ContactModule,
+    RouterModule.forRoot(routes)
+  ],
+  exports: [RouterModule]
+})
+export class AppRoutingModule {}

aio/content/examples/ngmodule-faq/src/app/app-routing.module.ts

@@ -0,0 +1,30 @@
+// #docregion
+import { NgModule }             from '@angular/core';
+import { Routes, RouterModule } from '@angular/router';
+
+import { ContactModule }    from './contact/contact.module';
+
+// #docregion routes
+const routes: Routes = [
+  { path: '', redirectTo: 'contact', pathMatch: 'full'},
+  // #docregion lazy-routes
+  { path: 'crisis', loadChildren: 'app/crisis/crisis.module#CrisisModule' },
+  { path: 'heroes', loadChildren: 'app/hero/hero.module#HeroModule' }
+  // #enddocregion lazy-routes
+];
+// #enddocregion routes
+
+@NgModule({
+  // #docregion imports
+  imports: [
+    ContactModule,
+    // #docregion forRoot
+    RouterModule.forRoot(routes),
+    // #enddocregion forRoot
+  ],
+  // #enddocregion imports
+  // #docregion exports
+  exports: [RouterModule]
+  // #enddocregion exports
+})
+export class AppRoutingModule {}

aio/content/examples/ngmodule-faq/src/app/app.component.0.ts

@@ -0,0 +1,10 @@
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  template: '<h1>{{title}}</h1>',
+})
+export class AppComponent {
+  title = 'Angular Modules';
+}

aio/content/examples/ngmodule-faq/src/app/app.component.1.ts

@@ -0,0 +1,17 @@
+// #docplaster
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+// #enddocregion
+  /*
+  // #docregion template
+  template: '<h1 highlight>{{title}}</h1>'
+  // #enddocregion template
+  */
+// #docregion
+  template: '<app-title></app-title>'
+})
+export class AppComponent {}
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/app.component.1b.ts

@@ -0,0 +1,13 @@
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  // #docregion template
+  template: `
+    <app-title></app-title>
+    <app-contact></app-contact>
+  `
+  // #enddocregion template
+})
+export class AppComponent {}

aio/content/examples/ngmodule-faq/src/app/app.component.2.ts

@@ -0,0 +1,10 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <app-title></app-title>
+    <app-contact></app-contact>
+  `
+})
+export class AppComponent {}

aio/content/examples/ngmodule-faq/src/app/app.component.3.ts

@@ -0,0 +1,17 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  // #docregion template
+  template: `
+    <app-title></app-title>
+    <nav>
+      <a routerLink="contact" routerLinkActive="active">Contact</a>
+      <a routerLink="crisis"  routerLinkActive="active">Crisis Center</a>
+      <a routerLink="heroes"  routerLinkActive="active">Heroes</a>
+    </nav>
+    <router-outlet></router-outlet>
+  `
+  // #enddocregion template
+})
+export class AppComponent {}

aio/content/examples/ngmodule-faq/src/app/app.component.ts

@@ -0,0 +1,17 @@
+// #docplaster
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <app-title></app-title>
+    <nav>
+      <a routerLink="contact" routerLinkActive="active">Contact</a>
+      <a routerLink="crisis"  routerLinkActive="active">Crisis Center</a>
+      <a routerLink="heroes"  routerLinkActive="active">Heroes</a>
+    </nav>
+    <router-outlet></router-outlet>
+  `
+})
+export class AppComponent {}

aio/content/examples/ngmodule-faq/src/app/app.module.0.ts

@@ -0,0 +1,13 @@
+import { NgModule }      from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+
+import { AppComponent }  from './app.component.0';
+
+@NgModule({
+// #docregion imports
+  imports: [ BrowserModule ],
+// #enddocregion imports
+  declarations: [ AppComponent ],
+  bootstrap:    [ AppComponent ]
+})
+export class AppModule { }

aio/content/examples/ngmodule-faq/src/app/app.module.1.ts

@@ -0,0 +1,52 @@
+// #docplaster
+// #docregion
+/* Angular Imports */
+import { NgModule }           from '@angular/core';
+import { BrowserModule }      from '@angular/platform-browser';
+
+/* App Imports */
+// #enddocregion
+import { AppComponent }       from './app.component.1';
+/*
+// #docregion
+import { AppComponent }       from './app.component';
+// #enddocregion
+*/
+// #docregion
+import { HighlightDirective } from './highlight.directive';
+import { TitleComponent }     from './title.component';
+import { UserService }        from './user.service';
+
+/* Contact Related Imports */
+import { FormsModule }        from '@angular/forms';
+
+import { AwesomePipe }        from './contact/awesome.pipe';
+import { ContactComponent }   from './contact/contact.component.3';
+import {
+  ContactHighlightDirective as ContactHighlightDirective
+} from './contact/contact-highlight.directive';
+
+@NgModule({
+// #docregion imports
+  imports: [ BrowserModule, FormsModule ],
+// #enddocregion imports
+// #docregion declarations, directive, component
+  declarations: [
+    AppComponent,
+    HighlightDirective,
+// #enddocregion directive
+    TitleComponent,
+// #enddocregion component
+
+    AwesomePipe,
+    ContactComponent,
+    ContactHighlightDirective
+// #docregion directive, component
+  ],
+// #enddocregion declarations, directive, component
+// #docregion providers
+  providers: [ UserService ],
+// #enddocregion providers
+  bootstrap: [ AppComponent ]
+})
+export class AppModule { }

aio/content/examples/ngmodule-faq/src/app/app.module.1b.ts

@@ -0,0 +1,46 @@
+// #docplaster
+// #docregion
+/* Angular Imports */
+import { NgModule }           from '@angular/core';
+import { BrowserModule }      from '@angular/platform-browser';
+import { FormsModule }        from '@angular/forms';
+
+/* App Imports */
+// #enddocregion
+import { AppComponent }       from './app.component.1b';
+/*
+// #docregion
+import { AppComponent }       from './app.component';
+// #enddocregion
+*/
+// #docregion
+import { HighlightDirective } from './highlight.directive';
+import { TitleComponent }     from './title.component';
+import { UserService }        from './user.service';
+
+/* Contact Imports */
+// #enddocregion
+import { ContactComponent } from './contact/contact.component.3';
+/*
+// #docregion
+import { ContactComponent } from './contact/contact.component';
+// #enddocregion
+*/
+// #docregion
+import { AwesomePipe } from './contact/awesome.pipe';
+import { ContactService } from './contact/contact.service';
+import { ContactHighlightDirective } from './contact/contact-highlight.directive';
+
+@NgModule({
+  imports: [ BrowserModule,  FormsModule ],
+// #docregion declarations
+  declarations: [
+    AppComponent, HighlightDirective, TitleComponent,
+    AwesomePipe, ContactComponent, ContactHighlightDirective
+  ],
+// #docregion providers
+  providers: [ ContactService, UserService ],
+// #enddocregion providers
+  bootstrap: [ AppComponent ]
+})
+export class AppModule { }

aio/content/examples/ngmodule-faq/src/app/app.module.2.ts

@@ -0,0 +1,36 @@
+// #docplaster
+// #docregion
+/* Angular Imports */
+import { NgModule }           from '@angular/core';
+import { BrowserModule }      from '@angular/platform-browser';
+
+/* App Imports */
+// #enddocregion
+import { AppComponent }       from './app.component.2';
+/*
+// #docregion
+import { AppComponent }       from './app.component';
+// #enddocregion
+*/
+// #docregion
+import { HighlightDirective } from './highlight.directive';
+import { TitleComponent }     from './title.component';
+import { UserService }        from './user.service';
+
+/* Contact Imports */
+// #enddocregion
+import { ContactModule }      from './contact/contact.module.2';
+/*
+// #docregion
+import { ContactModule }      from './contact/contact.module';
+// #enddocregion
+*/
+// #docregion
+
+@NgModule({
+  imports:      [ BrowserModule, ContactModule ],
+  declarations: [ AppComponent, HighlightDirective, TitleComponent ],
+  providers:    [ UserService ],
+  bootstrap:    [ AppComponent ],
+})
+export class AppModule { }

aio/content/examples/ngmodule-faq/src/app/app.module.3.ts

@@ -0,0 +1,41 @@
+// #docplaster
+// #docregion
+/* Angular Imports */
+import { NgModule }           from '@angular/core';
+import { BrowserModule }      from '@angular/platform-browser';
+
+/* App Imports */
+// #enddocregion
+import { AppComponent }       from './app.component.3';
+/*
+// #docregion
+import { AppComponent }       from './app.component';
+// #enddocregion
+*/
+// #docregion
+import { HighlightDirective } from './highlight.directive';
+import { TitleComponent }     from './title.component';
+import { UserService }        from './user.service';
+
+/* Routing Module */
+// #enddocregion
+import { AppRoutingModule }   from './app-routing.module.3';
+/*
+// #docregion
+import { AppRoutingModule }   from './app-routing.module';
+// #enddocregion
+*/
+// #docregion
+
+@NgModule({
+// #docregion imports
+  imports:      [
+    BrowserModule,
+    AppRoutingModule
+  ],
+// #enddocregion imports
+  providers:    [ UserService ],
+  declarations: [ AppComponent, HighlightDirective, TitleComponent ],
+  bootstrap:    [ AppComponent ]
+})
+export class AppModule { }

aio/content/examples/ngmodule-faq/src/app/app.module.ts

@@ -0,0 +1,39 @@
+// #docplaster
+// #docregion
+// #docregion v4
+/* Angular Imports */
+import { NgModule }       from '@angular/core';
+import { BrowserModule }  from '@angular/platform-browser';
+
+/* App Imports */
+import { AppComponent }   from './app.component';
+
+/* Core Modules */
+import { CoreModule }       from './core/core.module';
+
+/* Routing Module */
+import { AppRoutingModule } from './app-routing.module';
+
+@NgModule({
+  // #docregion import-for-root
+  imports: [
+    BrowserModule,
+// #enddocregion v4
+// #enddocregion import-for-root
+/*
+// #docregion v4
+    CoreModule,
+// #enddocregion v4
+*/
+// #docregion import-for-root
+    CoreModule.forRoot({userName: 'Miss Marple'}),
+// #docregion v4
+    AppRoutingModule
+  ],
+  // #enddocregion import-for-root
+  declarations: [ AppComponent ],
+  bootstrap:    [ AppComponent ]
+})
+export class AppModule { }
+// #enddocregion v4
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/contact/awesome.pipe.ts

@@ -0,0 +1,10 @@
+// #docregion
+import { Pipe, PipeTransform } from '@angular/core';
+
+@Pipe({ name: 'awesome' })
+/** Precede the input string with the word "Awesome " */
+export class AwesomePipe implements PipeTransform {
+  transform(phrase: string) {
+    return phrase ? 'Awesome ' + phrase : '';
+  }
+}

aio/content/examples/ngmodule-faq/src/app/contact/contact-highlight.directive.ts

@@ -0,0 +1,20 @@
+// #docplaster
+// Same directive name and selector as
+// HighlightDirective in parent AppModule
+// It selects for both input boxes and  'highlight' attr
+// and it highlights in blue instead of gold
+
+// #docregion
+import { Directive, ElementRef } from '@angular/core';
+
+// Highlight the host element or any InputElement in blue
+@Directive({ selector: '[highlight], input' })
+export class ContactHighlightDirective {
+  constructor(el: ElementRef) {
+    el.nativeElement.style.backgroundColor = 'powderblue';
+    // #enddocregion
+    console.log(`* Contact highlight called for ${el.nativeElement.tagName}`);
+    // #docregion
+  }
+}
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/contact/contact-routing.module.3.ts

@@ -0,0 +1,14 @@
+import { NgModule }            from '@angular/core';
+import { RouterModule }        from '@angular/router';
+
+import { ContactComponent }    from './contact.component.3';
+
+const routes = [
+  { path: 'contact', component: ContactComponent}
+];
+
+@NgModule({
+  imports: [ RouterModule.forChild(routes) ],
+  exports: [ RouterModule ]
+})
+export class ContactRoutingModule {}

aio/content/examples/ngmodule-faq/src/app/contact/contact-routing.module.ts

@@ -0,0 +1,16 @@
+import { NgModule }            from '@angular/core';
+import { RouterModule }        from '@angular/router';
+
+import { ContactComponent }    from './contact.component';
+
+// #docregion routing
+const routes = [
+  { path: 'contact', component: ContactComponent}
+];
+
+@NgModule({
+  imports: [ RouterModule.forChild(routes) ],
+  exports: [ RouterModule ]
+})
+export class ContactRoutingModule {}
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/contact/contact.component.3.ts

@@ -0,0 +1,53 @@
+// #docregion
+import { Component, OnInit }      from '@angular/core';
+
+import { Contact, ContactService } from './contact.service';
+import { UserService }    from '../user.service';
+
+@Component({
+  selector: 'app-contact',
+  templateUrl: './contact.component.html',
+  styleUrls: [ './contact.component.css' ]
+})
+export class ContactComponent implements OnInit {
+  contact:  Contact;
+  contacts: Contact[];
+
+  msg = 'Loading contacts ...';
+  userName = '';
+
+  constructor(private contactService: ContactService, userService: UserService) {
+    this.userName = userService.userName;
+  }
+
+  ngOnInit() {
+    this.contactService.getContacts().subscribe(contacts => {
+      this.msg = '';
+      this.contacts = contacts;
+      this.contact = contacts[0];
+    });
+  }
+
+  next() {
+    let ix = 1 + this.contacts.indexOf(this.contact);
+    if (ix >= this.contacts.length) { ix = 0; }
+    this.contact = this.contacts[ix];
+  }
+
+  onSubmit() {
+    // POST-DEMO TODO: do something like save it
+    this.displayMessage('Saved ' + this.contact.name);
+  }
+
+  newContact() {
+    this.displayMessage('New contact');
+    this.contact = {id: 42, name: ''};
+    this.contacts.push(this.contact);
+  }
+
+  /** Display a message briefly, then remove it. */
+  displayMessage(msg: string) {
+    this.msg = msg;
+    setTimeout(() => this.msg = '', 1500);
+  }
+}

aio/content/examples/ngmodule-faq/src/app/contact/contact.component.css

@@ -0,0 +1,32 @@
+/* #docregion */
+.ng-valid[required] {
+  border-left: 5px solid #42A948; /* green */
+}
+
+.ng-invalid {
+  border-left: 5px solid #a94442; /* red */
+}
+
+.alert {
+  padding: 15px;
+  margin: 8px 0;
+  border: 1px solid transparent;
+  border-radius: 4px;
+}
+.alert-danger {
+  color: #a94442;
+  background-color: #f2dede;
+  border-color: #ebccd1;
+}
+
+.msg {
+  color: blue;
+  background-color: whitesmoke;
+  border: 1px solid transparent;
+  border-radius: 4px;
+  margin-bottom: 20px;
+}
+
+.button-group {
+  padding-top: 12px;
+}

aio/content/examples/ngmodule-faq/src/app/contact/contact.component.html

@@ -0,0 +1,37 @@
+<!-- #docregion -->
+<h2>Contact of {{userName}}</h2>
+<div *ngIf="msg" class="msg">{{msg}}</div>
+
+<form *ngIf="contacts" (ngSubmit)="onSubmit()" #contactForm="ngForm">
+  <!-- #docregion awesome -->
+  <h3 highlight>{{ contact.name | awesome }}</h3>
+  <!-- #enddocregion awesome -->
+
+  <div class="form-group">
+    <label for="name">Name</label>
+
+    <!-- #docregion ngModel -->
+    <input type="text" class="form-control" required
+      [(ngModel)]="contact.name"
+      name="name"  #name="ngModel" >
+    <!-- #enddocregion ngModel -->
+
+    <div [hidden]="name.valid" class="alert alert-danger">
+      Name is required
+    </div>
+  </div>
+
+  <div class="button-group">
+    <button type="submit" class="btn btn-default"
+    [disabled]="!contactForm.form.valid">
+    Save</button>
+
+    <button type="button" class="btn" (click)="next()"
+    [disabled]="!contactForm.form.valid">
+    Next Contact</button>
+
+    <button type="button" class="btn" (click)="newContact()">
+    New Contact</button>
+  </div>
+</form>
+<!-- #enddocregion -->

aio/content/examples/ngmodule-faq/src/app/contact/contact.component.ts

@@ -0,0 +1,54 @@
+// Exact copy except import UserService from core
+// #docregion
+import { Component, OnInit }      from '@angular/core';
+
+import { Contact, ContactService } from './contact.service';
+import { UserService }             from '../core/user.service';
+
+@Component({
+  selector: 'app-contact',
+  templateUrl: './contact.component.html',
+  styleUrls: [ './contact.component.css' ]
+})
+export class ContactComponent implements OnInit {
+  contact:  Contact;
+  contacts: Contact[];
+
+  msg = 'Loading contacts ...';
+  userName = '';
+
+  constructor(private contactService: ContactService, userService: UserService) {
+    this.userName = userService.userName;
+  }
+
+  ngOnInit() {
+    this.contactService.getContacts().subscribe(contacts => {
+      this.msg = '';
+      this.contacts = contacts;
+      this.contact = contacts[0];
+    });
+  }
+
+  next() {
+    let ix = 1 + this.contacts.indexOf(this.contact);
+    if (ix >= this.contacts.length) { ix = 0; }
+    this.contact = this.contacts[ix];
+  }
+
+  onSubmit() {
+    // POST-DEMO TODO: do something like save it
+    this.displayMessage('Saved ' + this.contact.name);
+  }
+
+  newContact() {
+    this.displayMessage('New contact');
+    this.contact = {id: 42, name: ''};
+    this.contacts.push(this.contact);
+  }
+
+  /** Display a message briefly, then remove it. */
+  displayMessage(msg: string) {
+    this.msg = msg;
+    setTimeout(() => this.msg = '', 1500);
+  }
+}

aio/content/examples/ngmodule-faq/src/app/contact/contact.module.0.ts

@@ -0,0 +1,11 @@
+// #docregion
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+@NgModule({
+  imports: [
+    CommonModule
+  ],
+  declarations: []
+})
+export class ContactModule { }

aio/content/examples/ngmodule-faq/src/app/contact/contact.module.2.ts

@@ -0,0 +1,37 @@
+// #docplaster
+// #docregion
+import { NgModule }           from '@angular/core';
+import { CommonModule }       from '@angular/common';
+import { FormsModule }        from '@angular/forms';
+
+import { AwesomePipe }        from './awesome.pipe';
+// #enddocregion
+import { ContactComponent }   from './contact.component.3';
+/*
+// #docregion
+import { ContactComponent }   from './contact.component';
+// #enddocregion
+*/
+// #docregion
+import { ContactHighlightDirective } from './contact-highlight.directive';
+import { ContactService }     from './contact.service';
+
+// #docregion class
+@NgModule({
+  imports: [
+    CommonModule,
+    FormsModule
+  ],
+  declarations: [
+    AwesomePipe,
+    ContactComponent,
+    ContactHighlightDirective
+  ],
+  // #docregion exports
+  exports:   [ ContactComponent ],
+  // #enddocregion exports
+  providers: [ ContactService ]
+})
+export class ContactModule { }
+// #enddocregion class
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/contact/contact.module.3.ts

@@ -0,0 +1,44 @@
+// #docplaster
+// #docregion
+import { NgModule }           from '@angular/core';
+import { CommonModule }       from '@angular/common';
+import { FormsModule }        from '@angular/forms';
+
+import { AwesomePipe }        from './awesome.pipe';
+// #enddocregion
+import { ContactComponent }   from './contact.component.3';
+/*
+// #docregion
+import { ContactComponent }   from './contact.component';
+// #enddocregion
+*/
+// #docregion
+import { ContactHighlightDirective } from './contact-highlight.directive';
+import { ContactService }     from './contact.service';
+
+// #enddocregion
+import { ContactRoutingModule }   from './contact-routing.module.3';
+/*
+// #docregion
+import { ContactRoutingModule }   from './contact-routing.module';
+// #enddocregion
+*/
+// #docregion
+
+// #docregion class
+@NgModule({
+  imports: [
+    CommonModule,
+    FormsModule,
+    ContactRoutingModule
+  ],
+  declarations: [
+    AwesomePipe,
+    ContactComponent,
+    ContactHighlightDirective
+  ],
+  providers: [ ContactService ]
+})
+export class ContactModule { }
+// #enddocregion class
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/contact/contact.module.ts

@@ -0,0 +1,19 @@
+// #docregion
+import { NgModule }           from '@angular/core';
+import { SharedModule }       from '../shared/shared.module';
+
+import { ContactComponent }     from './contact.component';
+import { ContactService }       from './contact.service';
+import { ContactRoutingModule } from './contact-routing.module';
+
+// #docregion class
+@NgModule({
+  imports: [
+    SharedModule,
+    ContactRoutingModule
+  ],
+  declarations: [ ContactComponent ],
+  providers:    [ ContactService ]
+})
+export class ContactModule { }
+// #enddocregion class

aio/content/examples/ngmodule-faq/src/app/contact/contact.service.ts

@@ -0,0 +1,38 @@
+// #docplaster
+// #docregion
+import { Injectable, OnDestroy } from '@angular/core';
+
+import { Observable } from 'rxjs/Observable';
+import { of }         from 'rxjs/observable/of';
+import { delay }      from 'rxjs/operators';
+
+export class Contact {
+  constructor(public id: number, public name: string) { }
+}
+
+const CONTACTS: Contact[] = [
+  new Contact(21, 'Sam Spade'),
+  new Contact(22, 'Nick Danger'),
+  new Contact(23, 'Nancy Drew')
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves contacts from a server */
+@Injectable()
+export class ContactService implements OnDestroy {
+// #enddocregion
+  constructor() { console.log('ContactService instance created.'); }
+  ngOnDestroy() { console.log('ContactService instance destroyed.'); }
+
+// #docregion
+  getContacts(): Observable<Contact[]> {
+    return of(CONTACTS).pipe(delay(FETCH_LATENCY));
+  }
+
+  getContact(id: number | string): Observable<Contact> {
+    return of(CONTACTS.find(contact => contact.id === +id))
+      .pipe(delay(FETCH_LATENCY));
+  }
+}
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/core/core.module.ts

@@ -0,0 +1,48 @@
+/* tslint:disable:member-ordering no-unused-variable */
+// #docplaster
+// #docregion
+// #docregion v4
+import {
+  ModuleWithProviders, NgModule,
+  Optional, SkipSelf }       from '@angular/core';
+
+import { CommonModule }      from '@angular/common';
+
+import { TitleComponent }    from './title.component';
+import { UserService }       from './user.service';
+// #enddocregion
+import { UserServiceConfig } from './user.service';
+
+// #docregion v4
+@NgModule({
+  imports:      [ CommonModule ],
+  declarations: [ TitleComponent ],
+  exports:      [ TitleComponent ],
+  providers:    [ UserService ]
+})
+export class CoreModule {
+// #enddocregion v4
+
+  // #docregion ctor
+  constructor (@Optional() @SkipSelf() parentModule: CoreModule) {
+    if (parentModule) {
+      throw new Error(
+        'CoreModule is already loaded. Import it in the AppModule only');
+    }
+  }
+  // #enddocregion ctor
+
+  // #docregion for-root
+  static forRoot(config: UserServiceConfig): ModuleWithProviders {
+    return {
+      ngModule: CoreModule,
+      providers: [
+        {provide: UserServiceConfig, useValue: config }
+      ]
+    };
+  }
+  // #enddocregion for-root
+// #docregion v4
+}
+// #enddocregion v4
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/core/title.component.html

@@ -0,0 +1,6 @@
+<!-- Exact copy from earlier app.component.html -->
+<h1 highlight>{{title}}</h1>
+<p *ngIf="user">
+  <i>Welcome, {{user}}</i>
+<p>
+

aio/content/examples/ngmodule-faq/src/app/core/title.component.ts

@@ -0,0 +1,16 @@
+// Exact copy of app/title.component.ts except import UserService from shared
+import { Component, Input } from '@angular/core';
+import { UserService }      from '../core/user.service';
+
+@Component({
+  selector: 'app-title',
+  templateUrl: './title.component.html',
+})
+export class TitleComponent {
+  title = 'Angular Modules';
+  user = '';
+
+  constructor(userService: UserService) {
+    this.user = userService.userName;
+  }
+}

aio/content/examples/ngmodule-faq/src/app/core/user.service.ts

@@ -0,0 +1,32 @@
+// Crazy copy of the app/user.service
+// Proves that UserService is an app-wide singleton and only instantiated once
+// IFF shared.module follows the `forRoot` pattern
+//
+// If it didn't, a new instance of UserService would be created
+// after each lazy load and the userName would double up.
+
+import { Injectable, Optional } from '@angular/core';
+
+let nextId = 1;
+
+export class UserServiceConfig {
+  userName = 'Philip Marlowe';
+}
+
+@Injectable()
+export class UserService {
+  id = nextId++;
+  private _userName = 'Sherlock Holmes';
+
+  // #docregion ctor
+  constructor(@Optional() config: UserServiceConfig) {
+    if (config) { this._userName = config.userName; }
+  }
+  // #enddocregion ctor
+
+  get userName() {
+    // Demo: add a suffix if this service has been created more than once
+    const suffix = this.id > 1 ? ` times ${this.id}` : '';
+    return this._userName + suffix;
+  }
+}

aio/content/examples/ngmodule-faq/src/app/crisis/crisis-detail.component.ts

@@ -0,0 +1,19 @@
+import { Component, OnInit } from '@angular/core';
+import { ActivatedRoute }    from '@angular/router';
+
+@Component({
+  template: `
+    <h3 highlight>Crisis Detail</h3>
+    <div>Crisis id: {{id}}</div>
+    <br>
+    <a routerLink="../list">Crisis List</a>
+  `
+})
+export class CrisisDetailComponent implements OnInit {
+  id: number;
+  constructor(private route: ActivatedRoute) {  }
+
+  ngOnInit() {
+    this.id = parseInt(this.route.snapshot.paramMap.get('id'), 10);
+  }
+}

aio/content/examples/ngmodule-faq/src/app/crisis/crisis-list.component.ts

@@ -0,0 +1,21 @@
+import { Component } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+
+import { Crisis,
+         CrisisService } from './crisis.service';
+
+@Component({
+  template: `
+    <h3 highlight>Crisis List</h3>
+    <div *ngFor='let crisis of crises | async'>
+      <a routerLink="{{'../' + crisis.id}}">{{crisis.id}} - {{crisis.name}}</a>
+    </div>
+  `
+})
+export class CrisisListComponent {
+  crises: Observable<Crisis[]>;
+
+  constructor(private crisisService: CrisisService) {
+    this.crises = this.crisisService.getCrises();
+  }
+}

aio/content/examples/ngmodule-faq/src/app/crisis/crisis-routing.module.ts

@@ -0,0 +1,18 @@
+import { NgModule }            from '@angular/core';
+import { Routes,
+         RouterModule }        from '@angular/router';
+
+import { CrisisListComponent }    from './crisis-list.component';
+import { CrisisDetailComponent }  from './crisis-detail.component';
+
+const routes: Routes = [
+  { path: '', redirectTo: 'list', pathMatch: 'full'},
+  { path: 'list',    component: CrisisListComponent },
+  { path: ':id', component: CrisisDetailComponent }
+];
+
+@NgModule({
+  imports: [RouterModule.forChild(routes)],
+  exports: [RouterModule]
+})
+export class CrisisRoutingModule {}

aio/content/examples/ngmodule-faq/src/app/crisis/crisis.module.ts

@@ -0,0 +1,14 @@
+import { NgModule }      from '@angular/core';
+import { CommonModule }  from '@angular/common';
+
+import { CrisisListComponent }    from './crisis-list.component';
+import { CrisisDetailComponent }  from './crisis-detail.component';
+import { CrisisService }          from './crisis.service';
+import { CrisisRoutingModule }    from './crisis-routing.module';
+
+@NgModule({
+  imports:      [ CommonModule, CrisisRoutingModule ],
+  declarations: [ CrisisDetailComponent, CrisisListComponent ],
+  providers:    [ CrisisService ]
+})
+export class CrisisModule {}

aio/content/examples/ngmodule-faq/src/app/crisis/crisis.service.ts

@@ -0,0 +1,34 @@
+import { Injectable, OnDestroy } from '@angular/core';
+
+import { Observable } from 'rxjs/Observable';
+import { of }         from 'rxjs/observable/of';
+import { delay }      from 'rxjs/operators';
+
+export class Crisis {
+  constructor(public id: number, public name: string) { }
+}
+
+const CRISES: Crisis[] = [
+  new Crisis(1, 'Dragon Burning Cities'),
+  new Crisis(2, 'Sky Rains Great White Sharks'),
+  new Crisis(3, 'Giant Asteroid Heading For Earth'),
+  new Crisis(4, 'Procrastinators Meeting Delayed Again'),
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves crises from a server */
+@Injectable()
+export class CrisisService implements OnDestroy {
+  constructor() { console.log('CrisisService instance created.'); }
+  ngOnDestroy() { console.log('CrisisService instance destroyed.'); }
+
+  getCrises(): Observable<Crisis[]> {
+    return of(CRISES).pipe(delay(FETCH_LATENCY));
+  }
+
+  getCrisis(id: number | string): Observable<Crisis> {
+    return of(CRISES.find(crisis => crisis.id === +id))
+      .pipe(delay(FETCH_LATENCY));
+  }
+}

aio/content/examples/ngmodule-faq/src/app/hero/hero-detail.component.ts

@@ -0,0 +1,31 @@
+import { Component, OnInit } from '@angular/core';
+import { ActivatedRoute }    from '@angular/router';
+
+import { Hero,
+         HeroService }    from './hero.service';
+
+@Component({
+  template: `
+    <h3 highlight>Hero Detail</h3>
+    <div *ngIf="hero">
+      <div>Id: {{hero.id}}</div><br>
+      <label>Name:
+        <input [(ngModel)]="hero.name">
+      </label>
+    </div>
+    <br>
+    <a routerLink="../">Hero List</a>
+  `
+})
+export class HeroDetailComponent implements OnInit {
+  hero: Hero;
+
+  constructor(
+    private route: ActivatedRoute,
+    private heroService: HeroService) { }
+
+  ngOnInit() {
+    let id = parseInt(this.route.snapshot.paramMap.get('id'), 10);
+    this.heroService.getHero(id).subscribe(hero => this.hero = hero);
+  }
+}

aio/content/examples/ngmodule-faq/src/app/hero/hero-list.component.ts

@@ -0,0 +1,20 @@
+import { Component }  from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+
+import { Hero,
+         HeroService } from './hero.service';
+
+@Component({
+  template: `
+    <h3 highlight>Hero List</h3>
+    <div *ngFor='let hero of heroes | async'>
+      <a routerLink="{{hero.id}}">{{hero.id}} - {{hero.name}}</a>
+    </div>
+  `
+})
+export class HeroListComponent {
+  heroes: Observable<Hero[]>;
+  constructor(private heroService: HeroService) {
+    this.heroes = this.heroService.getHeroes();
+  }
+}

aio/content/examples/ngmodule-faq/src/app/hero/hero-routing.module.3.ts

@@ -0,0 +1,23 @@
+import { NgModule }     from '@angular/core';
+import { Routes,
+         RouterModule } from '@angular/router';
+
+import { HeroComponent }       from './hero.component.3';
+import { HeroListComponent }   from './hero-list.component';
+import { HeroDetailComponent } from './hero-detail.component';
+
+const routes: Routes = [
+  { path: '',
+    component: HeroComponent,
+    children: [
+      { path: '',    component: HeroListComponent },
+      { path: ':id', component: HeroDetailComponent }
+    ]
+  }
+];
+
+@NgModule({
+  imports: [RouterModule.forChild(routes)],
+  exports: [RouterModule]
+})
+export class HeroRoutingModule {}

aio/content/examples/ngmodule-faq/src/app/hero/hero-routing.module.ts

@@ -0,0 +1,23 @@
+import { NgModule }     from '@angular/core';
+import { Routes,
+         RouterModule } from '@angular/router';
+
+import { HeroComponent }       from './hero.component';
+import { HeroListComponent }   from './hero-list.component';
+import { HeroDetailComponent } from './hero-detail.component';
+
+const routes: Routes = [
+  { path: '',
+    component: HeroComponent,
+    children: [
+      { path: '',    component: HeroListComponent },
+      { path: ':id', component: HeroDetailComponent }
+    ]
+  }
+];
+
+@NgModule({
+  imports: [RouterModule.forChild(routes)],
+  exports: [RouterModule]
+})
+export class HeroRoutingModule {}

aio/content/examples/ngmodule-faq/src/app/hero/hero.component.3.ts

@@ -0,0 +1,18 @@
+import { Component }   from '@angular/core';
+
+import { HeroService } from './hero.service';
+import { UserService } from '../user.service';
+
+@Component({
+  template: `
+    <h2>Heroes of {{userName}}</h2>
+    <router-outlet></router-outlet>
+  `,
+  providers: [ HeroService ]
+})
+export class HeroComponent {
+  userName = '';
+  constructor(userService: UserService) {
+    this.userName = userService.userName;
+  }
+}

aio/content/examples/ngmodule-faq/src/app/hero/hero.component.ts

@@ -0,0 +1,19 @@
+// Exact copy except import UserService from core
+import { Component }   from '@angular/core';
+
+import { HeroService } from './hero.service';
+import { UserService } from '../core/user.service';
+
+@Component({
+  template: `
+    <h2>Heroes of {{userName}}</h2>
+    <router-outlet></router-outlet>
+  `,
+  providers: [ HeroService ]
+})
+export class HeroComponent {
+  userName = '';
+  constructor(userService: UserService) {
+    this.userName = userService.userName;
+  }
+}

aio/content/examples/ngmodule-faq/src/app/hero/hero.module.3.ts

@@ -0,0 +1,21 @@
+import { NgModule }            from '@angular/core';
+import { CommonModule }        from '@angular/common';
+import { FormsModule }         from '@angular/forms';
+
+import { HeroComponent }       from './hero.component.3';
+import { HeroDetailComponent } from './hero-detail.component';
+import { HeroListComponent }   from './hero-list.component';
+import { HeroRoutingModule }   from './hero-routing.module.3';
+
+import { HighlightDirective }  from './highlight.directive';
+
+// #docregion class
+@NgModule({
+  imports: [ CommonModule, FormsModule, HeroRoutingModule ],
+  declarations: [
+    HeroComponent, HeroDetailComponent, HeroListComponent,
+    HighlightDirective
+  ]
+})
+export class HeroModule { }
+// #enddocregion class

aio/content/examples/ngmodule-faq/src/app/hero/hero.module.ts

@@ -0,0 +1,16 @@
+import { NgModule }            from '@angular/core';
+
+import { SharedModule }        from '../shared/shared.module';
+
+import { HeroComponent }       from './hero.component';
+import { HeroDetailComponent } from './hero-detail.component';
+import { HeroListComponent }   from './hero-list.component';
+import { HeroRoutingModule }   from './hero-routing.module';
+
+@NgModule({
+  imports: [ SharedModule, HeroRoutingModule ],
+  declarations: [
+    HeroComponent, HeroDetailComponent, HeroListComponent,
+  ]
+})
+export class HeroModule { }

aio/content/examples/ngmodule-faq/src/app/hero/hero.service.ts

@@ -0,0 +1,37 @@
+import { Injectable, OnDestroy } from '@angular/core';
+
+import { Observable } from 'rxjs/Observable';
+import { of }         from 'rxjs/observable/of';
+import { delay }      from 'rxjs/operators';
+
+export class Hero {
+  constructor(public id: number, public name: string) { }
+}
+
+const HEROES: Hero[] = [
+  new Hero(11, 'Mr. Nice'),
+  new Hero(12, 'Narco'),
+  new Hero(13, 'Bombasto'),
+  new Hero(14, 'Celeritas'),
+  new Hero(15, 'Magneta'),
+  new Hero(16, 'RubberMan')
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves heroes from a server */
+@Injectable()
+export class HeroService implements OnDestroy {
+
+  constructor() { console.log('HeroService instance created.'); }
+  ngOnDestroy() { console.log('HeroService instance destroyed.'); }
+
+  getHeroes(): Observable<Hero[]> {
+    return of(HEROES).pipe(delay(FETCH_LATENCY));
+  }
+
+  getHero(id: number | string): Observable<Hero> {
+    return of(HEROES.find(hero => hero.id === +id))
+      .pipe(delay(FETCH_LATENCY));
+  }
+}

aio/content/examples/ngmodule-faq/src/app/hero/highlight.directive.ts

@@ -0,0 +1,14 @@
+// #docregion
+import { Directive, ElementRef } from '@angular/core';
+
+// Same directive name and selector as
+// HighlightDirective in parent AppRootModule
+// It selects for both input boxes and  'highlight' attr
+// and it highlights in beige instead of yellow
+@Directive({ selector: '[highlight]' })
+export class HighlightDirective {
+    constructor(el: ElementRef) {
+       el.nativeElement.style.backgroundColor = 'beige';
+       console.log(`* Hero highlight called for ${el.nativeElement.tagName}`);
+    }
+}

aio/content/examples/ngmodule-faq/src/app/highlight.directive.ts

@@ -0,0 +1,15 @@
+// #docplaster
+// #docregion
+import { Directive, ElementRef } from '@angular/core';
+
+// Highlight the host element in gold
+@Directive({ selector: '[highlight]' })
+export class HighlightDirective {
+  constructor(el: ElementRef) {
+    el.nativeElement.style.backgroundColor = 'gold';
+    // #enddocregion
+    console.log(`* AppRoot highlight called for ${el.nativeElement.tagName}`);
+    // #docregion
+  }
+}
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/shared/awesome.pipe.ts

@@ -0,0 +1,10 @@
+// Exact copy of contact.awesome.pipe
+import { Pipe, PipeTransform } from '@angular/core';
+
+@Pipe({ name: 'awesome' })
+/** Precede the input string with the word "Awesome " */
+export class AwesomePipe implements PipeTransform {
+  transform(phrase: string) {
+    return phrase ? 'Awesome ' + phrase : '';
+  }
+}

aio/content/examples/ngmodule-faq/src/app/shared/highlight.directive.ts

@@ -0,0 +1,12 @@
+// Exact copy of contact/highlight.directive except for color and message
+import { Directive, ElementRef } from '@angular/core';
+
+@Directive({ selector: '[highlight], input' })
+// Highlight the host element or any InputElement in gray
+export class HighlightDirective {
+  constructor(el: ElementRef) {
+    el.nativeElement.style.backgroundColor = 'lightgray';
+    console.log(
+      `* Shared highlight called for ${el.nativeElement.tagName}`);
+  }
+}

aio/content/examples/ngmodule-faq/src/app/shared/shared.module.ts

@@ -0,0 +1,18 @@
+// #docregion
+import { NgModule }            from '@angular/core';
+import { CommonModule }        from '@angular/common';
+import { FormsModule }         from '@angular/forms';
+
+import { AwesomePipe }         from './awesome.pipe';
+import { HighlightDirective }  from './highlight.directive';
+
+// #docregion module
+@NgModule({
+  imports:      [ CommonModule ],
+  declarations: [ AwesomePipe, HighlightDirective ],
+  exports:      [ AwesomePipe, HighlightDirective,
+                  CommonModule, FormsModule ]
+})
+export class SharedModule { }
+// #enddocregion module
+// #enddocregion

aio/content/examples/ngmodule-faq/src/app/title.component.html

@@ -0,0 +1,10 @@
+<!-- #docregion -->
+<!-- #docregion v1 -->
+<h1 highlight>{{title}}</h1>
+<!-- #enddocregion v1 -->
+<!-- #docregion ngIf -->
+<p *ngIf="user">
+  <i>Welcome, {{user}}</i>
+<p>
+<!-- #enddocregion ngIf -->
+

aio/content/examples/ngmodule-faq/src/app/title.component.ts

@@ -0,0 +1,23 @@
+// #docplaster
+// #docregion
+// #docregion v1
+import { Component } from '@angular/core';
+// #enddocregion v1
+import { UserService } from './user.service';
+// #docregion v1
+
+@Component({
+  selector: 'app-title',
+  templateUrl: './title.component.html'
+})
+export class TitleComponent {
+  title = 'Angular Modules';
+// #enddocregion v1
+  user = '';
+
+  constructor(userService: UserService) {
+    this.user = userService.userName;
+  }
+// #docregion v1
+}
+// #enddocregion v1

aio/content/examples/ngmodule-faq/src/app/user.service.ts

@@ -0,0 +1,8 @@
+// #docregion
+import { Injectable } from '@angular/core';
+
+@Injectable()
+/** Dummy version of an authenticated user service */
+export class UserService {
+  userName = 'Sherlock Holmes';
+}

aio/content/examples/ngmodule-faq/src/index.0.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <base href="/">
+    <title>NgModule Minimal</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

aio/content/examples/ngmodule-faq/src/index.1.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <base href="/">
+    <title>NgModule Minimal</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

aio/content/examples/ngmodule-faq/src/index.1b.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <base href="/">
+    <title>NgModule Minimal</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

aio/content/examples/ngmodule-faq/src/index.2.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <base href="/">
+    <title>NgModule Minimal</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

aio/content/examples/ngmodule-faq/src/index.3.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <base href="/">
+    <title>NgModule Minimal</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

aio/content/examples/ngmodule-faq/src/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <base href="/">
+    <title>NgModule Deluxe</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

aio/content/examples/ngmodule-faq/src/main-static.ts

@@ -0,0 +1,13 @@
+// #docplaster
+/*
+// #docregion
+// The browser platform without a compiler
+import { platformBrowser } from '@angular/platform-browser';
+
+// The app module factory produced by the static offline compiler
+import { AppModuleNgFactory } from './app/app.module.ngfactory';
+
+// Launch with the app module factory.
+platformBrowser().bootstrapModuleFactory(AppModuleNgFactory);
+// #enddocregion
+*/

aio/content/examples/ngmodule-faq/src/main.0.ts

@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module.0';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);

aio/content/examples/ngmodule-faq/src/main.1.ts

@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module.1';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);

aio/content/examples/ngmodule-faq/src/main.1b.ts

@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module.1b';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);

aio/content/examples/ngmodule-faq/src/main.2.ts

@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module.2';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);

aio/content/examples/ngmodule-faq/src/main.3.ts

@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module.3';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);

aio/content/examples/ngmodule-faq/src/main.ts

@@ -0,0 +1,12 @@
+// #docregion
+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);