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

PR Close #20306

aio/content/examples/ngmodules/src/app/app-routing.module.ts

@@ -0,0 +1,14 @@
+import { NgModule }             from '@angular/core';
+import { Routes, RouterModule } from '@angular/router';
+
+export const routes: Routes = [
+  { path: '', redirectTo: 'contact', pathMatch: 'full'},
+  { path: 'items', loadChildren: 'app/items/items.module#ItemsModule' },
+  { path: 'customers', loadChildren: 'app/customers/customers.module#CustomersModule' }
+];
+
+@NgModule({
+  imports: [RouterModule.forRoot(routes)],
+  exports: [RouterModule]
+})
+export class AppRoutingModule {}

aio/content/examples/ngmodules/src/app/app.component.html

@@ -0,0 +1,3 @@
+<h1>
+  {{title}}
+</h1>

aio/content/examples/ngmodules/src/app/app.component.spec.ts

@@ -0,0 +1,32 @@
+import { TestBed, async } from '@angular/core/testing';
+import { AppComponent } from './app.component';
+
+describe('AppComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      declarations: [
+        AppComponent
+      ],
+    });
+    TestBed.compileComponents();
+  });
+
+  it('should create the app', async(() => {
+    const fixture = TestBed.createComponent(AppComponent);
+    const app = fixture.debugElement.componentInstance;
+    expect(app).toBeTruthy();
+  }));
+
+  it(`should have as title 'app works!'`, async(() => {
+    const fixture = TestBed.createComponent(AppComponent);
+    const app = fixture.debugElement.componentInstance;
+    expect(app.title).toEqual('app works!');
+  }));
+
+  it('should render title in a h1 tag', async(() => {
+    const fixture = TestBed.createComponent(AppComponent);
+    fixture.detectChanges();
+    const compiled = fixture.debugElement.nativeElement;
+    expect(compiled.querySelector('h1').textContent).toContain('app works!');
+  }));
+});

aio/content/examples/ngmodules/src/app/app.component.ts

@@ -0,0 +1,16 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <app-title></app-title>
+    <nav>
+      <a routerLink="contact" routerLinkActive="active">Contact</a>
+      <a routerLink="items" routerLinkActive="active">Items</a>
+      <a routerLink="customers" routerLinkActive="active">Customers</a>
+    </nav>
+    <router-outlet></router-outlet>
+  `
+})
+export class AppComponent {
+}

aio/content/examples/ngmodules/src/app/app.module.ts

@@ -0,0 +1,33 @@
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HttpModule } from '@angular/http';
+
+/* App Root */
+import { AppComponent }   from './app.component';
+
+/* Feature Modules */
+import { ContactModule }    from './contact/contact.module';
+import { CoreModule }       from './core/core.module';
+
+/* Routing Module */
+import { AppRoutingModule } from './app-routing.module';
+
+
+
+@NgModule({
+  declarations: [
+    AppComponent
+  ],
+  // #docregion import-for-root
+  imports: [
+    BrowserModule,
+    ContactModule,
+    CoreModule.forRoot({userName: 'Miss Marple'}),
+    AppRoutingModule
+  ],
+  // #enddocregion import-for-root
+  providers: [],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }

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

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

aio/content/examples/ngmodules/src/app/contact/contact.component.html

@@ -0,0 +1,32 @@
+
+<h2>Contact of {{userName}}</h2>
+<div *ngIf="msg" class="msg">{{msg}}</div>
+
+<form *ngIf="contacts" (ngSubmit)="onSubmit()" #contactForm="ngForm">
+  <h3 highlight>{{ contact.name | awesome }}</h3>
+
+  <div class="form-group">
+    <label for="name">Name</label>
+
+    <input type="text" class="form-control" required
+    [(ngModel)]="contact.name"
+    name="name"  #name="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>

aio/content/examples/ngmodules/src/app/contact/contact.component.spec.ts

@@ -0,0 +1,25 @@
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { ContactComponent } from './contact.component';
+
+describe('ContactComponent', () => {
+  let component: ContactComponent;
+  let fixture: ComponentFixture<ContactComponent>;
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      declarations: [ ContactComponent ]
+    })
+    .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(ContactComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

aio/content/examples/ngmodules/src/app/contact/contact.component.ts

@@ -0,0 +1,54 @@
+// Exact copy except import UserService from core
+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/ngmodules/src/app/contact/contact.module.ts

@@ -0,0 +1,16 @@
+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';
+
+@NgModule({
+  imports: [
+    SharedModule,
+    ContactRoutingModule
+  ],
+  declarations: [ ContactComponent ],
+  providers:    [ ContactService ]
+})
+export class ContactModule { }

aio/content/examples/ngmodules/src/app/contact/contact.service.ts

@@ -0,0 +1,36 @@
+import { Injectable, OnDestroy } from '@angular/core';
+
+import { Observable } from 'rxjs/Observable';
+import { of }         from 'rxjs/observable/of';
+import { delay }      from 'rxjs/operator/delay';
+
+export class Contact {
+  constructor(public id: number, public name: string) { }
+}
+
+const CONTACTS: Contact[] = [
+  new Contact(21, 'Yasha'),
+  new Contact(22, 'Iulia'),
+  new Contact(23, 'Karina')
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves contacts from a server */
+@Injectable()
+export class ContactService implements OnDestroy {
+
+  constructor() { console.log('ContactService instance created.'); }
+  ngOnDestroy() { console.log('ContactService instance destroyed.'); }
+
+  getContacts(): Observable<Contact[]>  {
+    return delay.call(of(CONTACTS), FETCH_LATENCY);
+  }
+
+  getContact(id: number | string): Observable<Contact> {
+    const contact$ = of(CONTACTS.find(contact => contact.id === +id));
+    return delay.call(contact$, FETCH_LATENCY);
+  }
+}
+
+

aio/content/examples/ngmodules/src/app/core/core.module.ts

@@ -0,0 +1,44 @@
+/* tslint:disable:member-ordering no-unused-variable */
+ // #docregion whole-core-module
+import {
+  ModuleWithProviders, NgModule,
+  Optional, SkipSelf }       from '@angular/core';
+
+import { CommonModule }      from '@angular/common';
+
+import { TitleComponent }    from './title.component';
+import { UserService }       from './user.service';
+import { UserServiceConfig } from './user.service';
+
+@NgModule({
+  imports:      [ CommonModule ],
+  declarations: [ TitleComponent ],
+  exports:      [ TitleComponent ],
+  providers:    [ UserService ]
+})
+export class CoreModule {
+ // #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
+}
+
+// #enddocregion whole-core-module
+

aio/content/examples/ngmodules/src/app/core/title.component.html

@@ -0,0 +1,4 @@
+<h1>{{title}}</h1>
+<p *ngIf="user">
+  <i>Welcome, {{user}}</i>
+<p>

aio/content/examples/ngmodules/src/app/core/title.component.ts

@@ -0,0 +1,15 @@
+import { Component, Input } from '@angular/core';
+import { UserService }      from '../core/user.service';
+
+@Component({
+  selector: 'app-title',
+  templateUrl: './title.component.html',
+})
+export class TitleComponent {
+  title = 'NgModules';
+  user = '';
+
+  constructor(userService: UserService) {
+    this.user = userService.userName;
+  }
+}

aio/content/examples/ngmodules/src/app/core/user.service.ts

@@ -0,0 +1,31 @@
+// 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/ngmodules/src/app/customers/customers-detail.component.ts

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

aio/content/examples/ngmodules/src/app/customers/customers-list.component.ts

@@ -0,0 +1,22 @@
+import { Component, OnInit } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+
+import { Customer,
+         CustomersService } from './customers.service';
+
+@Component({
+  template: `
+    <h3 highlight>Customer List</h3>
+    <div *ngFor='let customer of customers | async'>
+      <a routerLink="{{customer.id}}">{{customer.id}} - {{customer.name}}</a>
+    </div>
+  `
+})
+
+export class CustomersListComponent {
+  customers: Observable<Customer[]>;
+  constructor(private customersService: CustomersService) {
+    this.customers = this.customersService.getCustomers();
+  }
+}
+

aio/content/examples/ngmodules/src/app/customers/customers-routing.module.ts

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

aio/content/examples/ngmodules/src/app/customers/customers.component.ts

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

aio/content/examples/ngmodules/src/app/customers/customers.module.ts

@@ -0,0 +1,19 @@
+import { NgModule }            from '@angular/core';
+
+import { SharedModule }        from '../shared/shared.module';
+
+import { CustomersComponent }       from './customers.component';
+import { CustomersDetailComponent } from './customers-detail.component';
+import { CustomersListComponent }   from './customers-list.component';
+import { CustomersRoutingModule }   from './customers-routing.module';
+import { CustomersService }   from './customers.service';
+
+
+@NgModule({
+  imports: [ SharedModule, CustomersRoutingModule ],
+  declarations: [
+    CustomersComponent, CustomersDetailComponent, CustomersListComponent,
+  ],
+  providers: [CustomersService]
+})
+export class CustomersModule { }

aio/content/examples/ngmodules/src/app/customers/customers.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/operator/delay';
+
+export class Customer {
+  constructor(public id: number, public name: string) { }
+}
+
+const CUSTOMERS: Customer[] = [
+  new Customer(11, 'Julian'),
+  new Customer(12, 'Eric'),
+  new Customer(13, 'Momi'),
+  new Customer(14, 'Madeleine'),
+  new Customer(15, 'Seth'),
+  new Customer(16, 'Teresa')
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves heroes from a server */
+@Injectable()
+export class CustomersService implements OnDestroy {
+
+  constructor() { console.log('CustomersService instance created.'); }
+  ngOnDestroy() { console.log('CustomersService instance destroyed.'); }
+
+  getCustomers(): Observable<Customer[]>  {
+    return delay.call(of(CUSTOMERS), FETCH_LATENCY);
+  }
+
+  getCustomer(id: number | string): Observable<Customer> {
+    const customer$ = of(CUSTOMERS.find(customer => customer.id === +id));
+    return delay.call(customer$, FETCH_LATENCY);
+  }
+}

aio/content/examples/ngmodules/src/app/items/items-detail.component.ts

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

aio/content/examples/ngmodules/src/app/items/items-list.component.ts

@@ -0,0 +1,23 @@
+import { Component, OnInit } from '@angular/core';
+import { Observable }from 'rxjs/Observable';
+
+import { Item,
+         ItemService }     from './items.service';
+
+@Component({
+  template: `
+    <h3 highlight>Items List</h3>
+    <div *ngFor='let item of items | async'>
+      <a routerLink="{{'../' + item.id}}">{{item.id}} - {{item.name}}</a>
+    </div>
+  `
+})
+export class ItemsListComponent {
+  items: Observable<Item[]>;
+
+  constructor(private itemService: ItemService) {
+    this.items = this.itemService.getItems();
+  }
+
+}
+

aio/content/examples/ngmodules/src/app/items/items-routing.module.ts

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

aio/content/examples/ngmodules/src/app/items/items.component.html

@@ -0,0 +1,3 @@
+<p>
+  items works!
+</p>

aio/content/examples/ngmodules/src/app/items/items.component.spec.ts

@@ -0,0 +1,25 @@
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { ItemsComponent } from './items.component';
+
+describe('ItemsComponent', () => {
+  let component: ItemsComponent;
+  let fixture: ComponentFixture<ItemsComponent>;
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      declarations: [ ItemsComponent ]
+    })
+    .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(ItemsComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

aio/content/examples/ngmodules/src/app/items/items.component.ts

@@ -0,0 +1,15 @@
+import { Component, OnInit } from '@angular/core';
+
+@Component({
+  selector: 'app-items',
+  templateUrl: './items.component.html',
+  styleUrls: ['./items.component.css']
+})
+export class ItemsComponent implements OnInit {
+
+  constructor() { }
+
+  ngOnInit() {
+  }
+
+}

aio/content/examples/ngmodules/src/app/items/items.module.ts

@@ -0,0 +1,14 @@
+import { NgModule }      from '@angular/core';
+import { CommonModule }  from '@angular/common';
+
+import { ItemsListComponent }    from './items-list.component';
+import { ItemsDetailComponent }  from './items-detail.component';
+import { ItemService }          from './items.service';
+import { ItemsRoutingModule }    from './items-routing.module';
+
+@NgModule({
+  imports:      [ CommonModule, ItemsRoutingModule ],
+  declarations: [ ItemsDetailComponent, ItemsListComponent ],
+  providers:    [ ItemService ]
+})
+export class ItemsModule {}

aio/content/examples/ngmodules/src/app/items/items.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/operator/delay';
+
+export class Item {
+  constructor(public id: number, public name: string) { }
+}
+
+const ITEMS: Item[] = [
+  new Item(1, 'Sticky notes'),
+  new Item(2, 'Dry erase markers'),
+  new Item(3, 'Erasers'),
+  new Item(4, 'Whiteboard cleaner'),
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves crises from a server */
+@Injectable()
+export class ItemService implements OnDestroy {
+
+  constructor() { console.log('ItemService instance created.'); }
+  ngOnDestroy() { console.log('ItemService instance destroyed.'); }
+
+  getItems(): Observable<Item[]>  {
+    return delay.call(of(ITEMS), FETCH_LATENCY);
+  }
+
+  getItem(id: number | string): Observable<Item> {
+    const item$ = of(ITEMS.find(item => item.id === +id));
+    return delay.call(item$, FETCH_LATENCY);
+  }
+}
+
+

aio/content/examples/ngmodules/src/app/shared/awesome.pipe.ts

@@ -0,0 +1,9 @@
+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/ngmodules/src/app/shared/highlight.directive.ts

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

aio/content/examples/ngmodules/src/app/shared/shared.module.ts

@@ -0,0 +1,14 @@
+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';
+
+@NgModule({
+  imports:      [ CommonModule ],
+  declarations: [ AwesomePipe, HighlightDirective ],
+  exports:      [ AwesomePipe, HighlightDirective,
+                  CommonModule, FormsModule ]
+})
+export class SharedModule { }