add phonecat dual router prose

Author: filipesilva

public/docs/_examples/upgrade-phonecat-3-router/ts/app/app-routing.module.ts

@@ -3,23 +3,19 @@ import { NgModule } from '@angular/core';
 import { Routes, RouterModule, UrlHandlingStrategy, UrlTree } from '@angular/router';
 import { APP_BASE_HREF, HashLocationStrategy, LocationStrategy } from '@angular/common';
 
-import { PhoneDetailComponent } from './phone-detail/phone-detail.component';
 import { PhoneListComponent }   from './phone-list/phone-list.component';
 
 export class Ng1Ng2UrlHandlingStrategy implements UrlHandlingStrategy {
-  // shouldProcessUrl(url: UrlTree) { return false; }
   shouldProcessUrl(url: UrlTree) {
-    return url.toString().startsWith('/phones')
-            || url.toString() === '/';
+    return url.toString() === '/' || url.toString() === '/phones';
   }
   extract(url: UrlTree) { return url; }
   merge(url: UrlTree, whole: UrlTree) { return url; }
 }
 
 const routes: Routes = [
   { path: '', redirectTo: 'phones', pathMatch: 'full' },
-  { path: 'phones',          component: PhoneListComponent },
-  { path: 'phones/:phoneId', component: PhoneDetailComponent }
+  { path: 'phones', component: PhoneListComponent }
 ];
 
 @NgModule({

public/docs/_examples/upgrade-phonecat-3-router/ts/app/app.config.ts

@@ -3,7 +3,14 @@
 angular.
   module('phonecatApp').
   config(['$locationProvider', '$routeProvider',
-    function config($locationProvider: angular.ILocationProvider) {
+    function config($locationProvider: angular.ILocationProvider,
+                    $routeProvider: angular.route.IRouteProvider) {
       $locationProvider.hashPrefix('!');
+      // #docregion ng1-routes
+      $routeProvider
+        .when('/phones/:phoneId', {
+          template: '<phone-detail></phone-detail>'
+        });
+      // #enddocregion ng1-routes
     }
   ]);

public/docs/_examples/upgrade-phonecat-3-router/ts/app/phone-detail/phone-detail.component.ts

@@ -1,9 +1,8 @@
+// #docplaster
 // #docregion
 declare var angular: angular.IAngularStatic;
 import { downgradeComponent } from '@angular/upgrade/static';
-
-import { Component } from '@angular/core';
-import { ActivatedRoute } from '@angular/router';
+import { Component, Inject } from '@angular/core';
 
 import { Phone, PhoneData } from '../core/phone/phone.service';
 
@@ -15,12 +14,11 @@ export class PhoneDetailComponent {
   phone: PhoneData;
   mainImageUrl: string;
 
-  constructor(activatedRoute: ActivatedRoute, phone: Phone) {
-    phone.get(activatedRoute.snapshot.params['phoneId'])
-      .subscribe((p: PhoneData) => {
-        this.phone = p;
-        this.setImage(p.images[0]);
-      });
+  constructor(@Inject('$routeParams') $routeParams: any, phone: Phone) {
+    phone.get($routeParams['phoneId']).subscribe(phone => {
+      this.phone = phone;
+      this.setImage(phone.images[0]);
+    });
   }
 
   setImage(imageUrl: string) {

public/docs/_examples/upgrade-phonecat-3-router/ts/app/phone-list/phone-list.template.html

@@ -3,7 +3,6 @@
     <div class="col-md-2">
       <!--Sidebar content-->
 
-      <!-- #docregion controls -->
       <p>
         Search:
         <input [(ngModel)]="query" />
@@ -16,7 +15,6 @@
           <option value="age">Newest</option>
         </select>
       </p>
-      <!-- #enddocregion controls -->
 
     </div>
     <div class="col-md-10">

public/docs/_examples/upgrade-phonecat-3-router/ts/index.html

@@ -25,19 +25,13 @@
     <script src="phone-list/phone-list.module.js"></script>
     <script src="phone-detail/phone-detail.module.js"></script>
 
-    <!-- #docregion ng2 -->
     <script src="/node_modules/core-js/client/shim.min.js"></script>
     <script src="/node_modules/zone.js/dist/zone.min.js"></script>
     <script src="/node_modules/reflect-metadata/Reflect.js"></script>
     <script src="/node_modules/systemjs/dist/system.src.js"></script>
-    <!-- #enddocregion ng2 -->
+
     <script src="/systemjs.config.1.js"></script>
-    <!-- #docregion ng2
-    <script src="/systemjs.config.js"></script>
-    <script>
-      System.import('/app');
-    </script>
-    <!-- #enddocregion ng2 -->
+
     <script>
       System.import('/app');
     </script>

public/docs/ts/latest/guide/upgrade.jade

@@ -45,7 +45,7 @@ include ../_util-fns
       4. [Upgrading the Phone service](#upgrading-the-phone-service)
       5. [Upgrading Components](#upgrading-components)
       6. [AoT compile the hybrid app](#aot-compile-the-hybrid-app)
-      7. [Switching To The Angular 2 Router And Bootstrap](#switching-to-the-angular-2-router-and-bootstrap)
+      7. [Adding The Angular 2 Router And Bootstrap](#adding-the-angular-2-router-and-bootstrap)
       8. [Say Goodbye to Angular 1](#say-goodbye-to-angular-1)
   3. [Appendix: Upgrading PhoneCat Tests](#appendix-upgrading-phonecat-tests)
 
@@ -1457,31 +1457,33 @@ code-example(format="").
   And that's all you need to use AoT while upgrading your app!
 
 :marked
-  ### Switching To The Angular 2 Router And Bootstrap
+  ### Adding The Angular 2 Router And Bootstrap
 
   At this point we've replaced all Angular 1 application components with
-  their Angular 2 counterparts. 
-  
-  The application is still bootstrapped as a hybrid app.
-  There's no need for that anymore.
-  It's time to remove the last remnants of Angular 1 in two final steps:
-  1. Switch to the Angular 2 router.
-  1. Bootstrap as a pure Angular 2 app.
+  their Angular 2 counterparts, even though we're still serving them from the Angular 1 router.
+
+  Most Angular 1 apps have more than a couple of routes though, and it's very helpful to migrate
+  one route at a time.
+
+  Let's start by migrating the initial `/` and `/phones` routes to Angular 2, 
+  while keeping `/phones/:phoneId` in the Angular 1 router.
+
+  #### Add the Angular 2 router
 
-  #### Switch to the Angular 2 router
   Angular 2 has an [all-new router](router.html).
 
   Like all routers, it needs a place in the UI to display routed views.
-  The Angular 2 that's the `<router-outlet>` and it belongs in a *root component*
+  For Angular 2 that's the `<router-outlet>` and it belongs in a *root component*
   at the top of the applications component tree. 
 
   We don't yet have such a root component, because the app is still managed as an Angular 1 app.
   Create a new `app.component.ts` file with the following `AppComponent` class:
 
-+makeExample('upgrade-phonecat-4-final/ts/app/app.component.ts', null, 'app/app.component.ts')(format='.')
++makeExample('upgrade-phonecat-3-router/ts/app/app.component.ts', null, 'app/app.component.ts')(format='.')
 
 :marked
-  It has a simple template that only includes the `<router-outlet>`.
+  It has a simple template that only includes the `<router-outlet>` for Angular 2 routes
+  and `ng-view` for Angular 1 routes.
   This component just renders the contents of the active route and nothing else.
 
   The selector tells Angular 2 to plug this root component into the `<phonecat-app>` 
@@ -1490,65 +1492,80 @@ code-example(format="").
   Add this `<phonecat-app>` element to the `index.html`.
   It replaces the old Angular 1 `ng-view` directive:
 
-+makeExample('upgrade-phonecat-4-final/ts/index.html', 'appcomponent', 'index.html (body)')(format='.')
++makeExample('upgrade-phonecat-3-router/ts/index.html', 'appcomponent', 'index.html (body)')(format='.')
 
 :marked
   #### Create the _Routing Module_
   A router needs configuration whether it's the Angular 1 or Angular 2 or any other router.
 
   The details of Angular 2 router configuration are best left to the [Routing documentation](router.html) 
   which recommends that you create a `NgModule` dedicated to router configuration
-  (called a _Routing Module_):
+  (called a _Routing Module_).
 
-+makeExample('upgrade-phonecat-4-final/ts/app/app-routing.module.ts', null, 'app/app-routing.module.ts')
++makeExample('upgrade-phonecat-3-router/ts/app/app-routing.module.ts', null, 'app/app-routing.module.ts')
 
 :marked
-  This module defines a `routes` object with two routes to the two phone components
+  This module defines a `routes` object with one route to the phone list component
   and a default route for the empty path. 
   It passes the `routes` to the `RouterModule.forRoot` method which does the rest.
 
-  A couple of extra providers enable routing with "hash" URLs such as `#!/phones` instead of the default  "push state" strategy.
+  A couple of extra providers enable routing with "hash" URLs such as `#!/phones` 
+  instead of the default  "push state" strategy.
+
+  There's a twist to our Routing Module though: we're also adding a custom `UrlHandlingStrategy`
+  that tells the Angular 2 router to only process the `/` and `/phones` routes.
 
   Now update the `AppModule` to import this `AppRoutingModule` and also the
-  declare the root `AppComponent`:
+  declare the root `AppComponent` as the bootstrap component.
+  That tells Angular 2 that it should bootstrap the app with the _root_ `AppComponent` and 
+  insert it's view into the host web page.
 
-+makeExample('upgrade-phonecat-4-final/ts/app/app.module.ts', null, 'app/app.module.ts')
+  We can also remove the `ngDoBootstrap()` override from `app.module.ts` since we are now
+  bootstrapping from Angular 2.
+
++makeExample('upgrade-phonecat-3-router/ts/app/app.module.ts', null, 'app/app.module.ts')
 
 :marked
-  The Angular 2 router passes route parameters differently.
-  Correct the `PhoneDetail` component constructor to expect an injected `ActivatedRoute` object.
-  Extract the `phoneId` from the `ActivatedRoute.snapshot.params` and fetch the phone data as before:
+  Now we need to tell the Angular 1 router to only process the `/phones/:phoneId` route:
 
-+makeExample('upgrade-phonecat-4-final/ts/app/phone-detail/phone-detail.component.ts', null, 'app/phone-detail/phone-detail.component.ts')
++makeExample('upgrade-phonecat-3-router/ts/app/app.config.ts', 'ng1-routes', 'app/app.config.ts (route config)')
 :marked
   #### Generate links for each phone
 
   We no longer have to hardcode the links to phone details in the phone list. 
-  We can generate them data binding each phone's `id` to the `routerLink` directive
+  We can generate data bindings for each phone's `id` to the `routerLink` directive
   and let that directive construct the appropriate URL to the `PhoneDetailComponent`:
 
-+makeExample('upgrade-phonecat-4-final/ts/app/phone-list/phone-list.template.html', 'list', 'app/phone-list/phone-list.template.html (list with links)')(format='.')
++makeExample('upgrade-phonecat-3-router/ts/app/phone-list/phone-list.template.html', 'list', 'app/phone-list/phone-list.template.html (list with links)')(format='.')
 .l-sub-section
   :marked
     See the [Routing](router.html) page for details.
 
 :marked
-  #### Bootstrap as an Angular 2 app
+  We are now running both routers at the same time!
+  Angular 2 is handling the initial `/` url, redirecting to `/phones`.
+  Meanwhile when we click a link to the phone detail, Angular 1 takes over.
+
+  This way we can incrementally upgrade our app, reducing the risk of a massive one step router
+  swap.
+
+  The next step is to migrate the `/phones/:phoneId` route.
 
-  You may have noticed one extra `bootstrap` metadata property added to the `AppModule`
-+makeExample('upgrade-phonecat-4-final/ts/app/app.module.ts', 'bootstrap', 'app/app.module.ts (bootstrap)')(format='.')
 :marked
-  That tells Angular 2 that it should bootstrap the app with the _root_ `AppComponent` and 
-  insert it's view into the host web page.
+  The Angular 2 router passes route parameters differently.
+  Correct the `PhoneDetail` component constructor to expect an injected `ActivatedRoute` object.
+  Extract the `phoneId` from the `ActivatedRoute.snapshot.params` and fetch the phone data as before:
 
-  Now switch the bootstrap method of the application from the `UpgradeAdapter` 
-  to the Angular 2 way. 
++makeExample('upgrade-phonecat-4-final/ts/app/phone-detail/phone-detail.component.ts', null, 'app/phone-detail/phone-detail.component.ts')
 
-  Now we can drop `upgrade.bootstrap` from our application bootstrap, and remove the 
-  `ngDoBootstrap()` override from `app.module.ts`
+:marked
+  Since this was the last route we want to migrate over, we can also now delete the last 
+  route config from `app/app.config.ts`, and add it to the Angular 2 router configuration.
+  
+  We don't need our `UrlHandlingStrategy` anymore either, since now Angular 2 is processing all
+  routes. 
 
-+makeExample('upgrade-phonecat-4-final/ts/app/main.ts', null, 'main.ts')
-+makeExample('upgrade-phonecat-4-final/ts/app/app.module.ts', null, 'app.module.ts')
++makeExample('upgrade-phonecat-4-final/ts/app/app-routing.module.ts', null, 'app/app-routing.module.ts')
 
 :marked
   You are now running a pure Angular 2 application!
@@ -1559,10 +1576,22 @@ code-example(format="").
   its new life as a pure, shiny Angular 2 app. The remaining tasks all have to
   do with removing code - which of course is every programmer's favorite task!
 
+  The application is still bootstrapped as a hybrid app.
+  There's no need for that anymore.
+
+  Switch the bootstrap method of the application from the `UpgradeAdapter` 
+  to the Angular 2 way. 
+
++makeExample('upgrade-phonecat-4-final/ts/app/main.ts', null, 'main.ts')
+
+:marked
   If you haven't already, remove all references to the `UpgradeModule` from `app.module.ts`, 
   as well as any [Factory provider](#making-angular-1-dependencies-injectable-to-angular-2) for Angular 1 services.
-  Also remove any `downgradeComponent()` you find, together with the associated Angular 1 
-  directive declarations.
+  
+  Also remove any `downgradeInjectable` or `downgradeComponent()` you find, 
+  together with the associated Angular 1 factory or directive declarations.
+
++makeExample('upgrade-phonecat-4-final/ts/app/app.module.ts', null, 'app.module.ts')  
 
 :marked
   You may also completely remove the following files. They are Angular 1