include ../_util-fns :marked # Routing Around the App We received new requirements for our Tour of Heroes application: * add a *Dashboard* view. * navigate between the *Heroes* and *Dashboard* views. * clicking on a hero in either view navigates to a detail view of the selected hero. * clicking a *deep link* in an email opens the detail view for a particular hero; When we’re done, users will be able to navigate the app like this: figure.image-display img(src='/resources/images/devguide/toh/nav-diagram.png' alt="View navigations") :marked We'll add Angular’s *Component Router* to our app to satisfy these requirements. .l-sub-section :marked The [Routing and Navigation](../guide/router.html) chapter covers the router in more detail than we will in this tour. :marked [Run the live example](/resources/live-examples/toh-5/ts/plnkr.html). .l-sub-section img(src='/resources/images/devguide/plunker-separate-window-button.png' alt="pop out the window" align="right" style="margin-right:-20px") :marked To see the URL changes in the browser address bar, pop out the preview window by clicking the blue 'X' button in the upper right corner: .l-main-section :marked ## Where We Left Off Before we continue with our Tour of Heroes, let’s verify that we have the following structure after adding our hero service and hero detail component. If not, we’ll need to go back and follow the previous chapters. .filetree .file angular2-tour-of-heroes .children .file lib .children .file app_component.dart .file hero.dart .file hero_detail_component.dart .file hero_service.dart .file mock_heroes.dart .file web .children .file index.html .file main.dart .file styles.css .file pubspec.yaml :marked ### Run the app Open a terminal/console window and enter the following command to start the server: code-example(format="." language="bash"). pub serve :marked The application runs by default on `localhost:8080`. ## Action plan Here's our plan * turn `AppComponent` into an application shell that only handles navigation. * relocate the *Heroes* concerns within the current `AppComponent` to a separate `HeroesComponent` * add routing * create a new `DashboardComponent` * tie the *Dashboard* into the navigation structure. .l-sub-section :marked *Routing* is another name for *navigation*. The *router* is the mechanism for navigating from view to view. .l-main-section :marked ## Splitting the *AppComponent* Our current app loads `AppComponent` and immediately displays the list of heroes. Our revised app should present a shell with a choice of views (*Dashboard* and *Heroes*) and then default to one of them. The `AppComponent` should only handle navigation. Let's move the display of *Heroes* out of `AppComponent` and into its own `HeroesComponent`. ### *HeroesComponent* `AppComponent` is already dedicated to *Heroes*. Instead of moving anything out of `AppComponent`, we'll just rename it `HeroesComponent` and create a new `AppComponent` shell separately. The steps are: * rename `app_component.dart` file to `heroes_component.dart`. * rename the `AppComponent` class to `HeroesComponent`. * rename the selector `my-app` to `my-heroes`. :marked +makeExample('toh-5/dart/lib/heroes_component.dart', 'heroes-component-renaming', 'lib/heroes_component.dart (renaming)')(format=".") :marked ## Create *AppComponent* The new `AppComponent` will be the application shell. It will have some navigation links at the top and a display area below for the pages we navigate to. The initial steps are: * create a new file named `app_component.dart`. * define an `AppComponent` class. * expose an application `title` property. * add the `@Component` metadata decorator above the class with a `my-app` selector. * add a template with `

` tags surrounding a binding to the `title` property. * add the `` tags to the template so we still see the heroes. * add the `HeroesComponent` to the `directives` array so Angular recognizes the `` tags. * add the `HeroService` to the `providers` array because we'll need it in every other view. * add the supporting `import` statements. Our first draft looks like this: +makeExample('toh-5/dart/lib/app_component_1.dart', null, 'lib/app_component.dart (v1)') :marked .callout.is-critical header Remove HeroService from the HeroesComponent providers :marked Go back to the `HeroesComponent` and **remove the `HeroService`** from its `providers` array. We are *promoting* this service from the `HeroesComponent` to the `AppComponent`. We ***do not want two copies*** of this service at two different levels of our app. :marked The app still runs and still displays heroes. Our refactoring of `AppComponent` into a new `AppComponent` and a `HeroesComponent` worked! We have done no harm. :marked ## Add Routing We're ready to take the next step. Instead of displaying heroes automatically, we'd like to show them *after* the user clicks a button. In other words, we'd like to navigate to the list of heroes. We'll need the Angular *Component Router*. ### Include the Router Library Not all apps need routing which is why the Angular *Component Router* is in a separate, optional module library. // Our Tour of Heroes needs routing, // so we load the library in the `index.html` in a script tag immediately *after* the angular script itself. //makeExample('toh-5/dart/web/index.html', 'router', 'index.html (router)')(format=".") :marked While we're in `index.html`, we add `` at the top of the `` section. +makeExample('toh-5/dart/web/index.html', 'base-href', 'index.html (base href)')(format=".") .callout.is-important header base href is essential :marked See the *base href* section of the [Router](../guide/router.html#!#base-href) chapter to learn why this matters. :marked ### Make the router available. The *Component Router* is a service. Like any service, we have to import it and make it available to the application by adding it to the `providers` array. The Angular router is a combination of multiple services (`ROUTER_PROVIDERS`), multiple directives (`ROUTER_DIRECTIVES`), and a configuration decorator (`RouteConfig`). We'll import them all together: +makeExample('toh-5/dart/lib/app_component_2.dart', 'import-router', 'app_component.dart (router imports)')(format=".") :marked Next we update the `directives` and `providers` metadata arrays to *include* the router assets. +makeExample('toh-5/dart/lib/app_component_2.dart', 'directives-and-providers', 'app_component.dart (directives and providers)')(format=".") :marked Notice that we also removed the `HeroesComponent` from the `directives` array. `AppComponent` no longer shows heroes; that will be the router's job. We'll soon remove `` from the template too. ### Add and configure the router The `AppComponent` doesn't have a router yet. We'll use the `@RouteConfig` decorator to simultaneously (a) assign a router to the component and (b) configure that router with *routes*. *Routes* tell the router which views to display when a user clicks a link or pastes a URL into the browser address bar. Let's define our first route, a route to the `HeroesComponent`. +makeExample('toh-5/dart/lib/app_component_2.dart', 'route-config', 'app_component.dart (RouteConfig for heroes)')(format=".") :marked `@RouteConfig` takes an array of *Route* definitions. We have only one route definition at the moment but rest assured, we'll add more. This *route definition* has three parts: * **path**: the router matches this route's path to the URL in the browser address bar (`/heroes`). * **name**: the official name of the route; it *must* begin with a capital letter to avoid confusion with the *path* (`Heroes`). * **component**: the component that the router should create when navigating to this route (`HeroesComponent`). .l-sub-section :marked Learn more about defining routes with @RouteConfig in the [Routing](../guide/router.html) chapter. :marked ### Router Outlet If we paste the path, `/heroes`, into the browser address bar, the router should match it to the `'Heroes'` route and display the `HeroesComponent`. But where? We have to ***tell it where*** by adding `` marker tags to the bottom of the template. `RouterOutlet` is one of the `ROUTER_DIRECTIVES`. The router displays each component immediately below the `` as we navigate through the application. ### Router Links We don't really expect users to paste a route URL into the address bar. We add an anchor tag to the template which, when clicked, triggers navigation to the `HeroesComponent`. The revised template looks like this: +makeExample('toh-5/dart/lib/app_component_2.dart', 'template', 'app_component.dart (template for Heroes)')(format=".") :marked Notice the `[routerLink]` binding in the anchor tag. We bind the `RouterLink` directive (another of the `ROUTER_DIRECTIVES`) to an array that tells the router where to navigate when the user clicks the link. We define a *routing instruction* with a *link parameters array*. The array only has one element in our little sample, the quoted ***name* of the route** to follow. Looking back at the route configuration, we confirm that `'Heroes'` is the name of the route to the `HeroesComponent`. .l-sub-section :marked Learn about the *link parameters array* in the [Routing](../guide/router.html#link-parameters-array) chapter. :marked Refresh the browser. We see only the app title. We don't see the heroes list. .l-sub-section :marked The browser's address bar shows `/`. The route path to `HeroesComponent` is `/heroes`, not `/`. We don't have a route that matches the path `/`, so there is nothing to show. That's something we'll want to fix. :marked We click the "Heroes" navigation link, the browser bar updates to `/heroes`, and now we see the list of heroes. We are navigating at last! At this stage, our `AppComponent` looks like this. +makeExample('toh-5/dart/lib/app_component_2.dart',null, 'lib/app_component.dart (v2)') :marked The *AppComponent* is now attached to a router and displaying routed views. For this reason and to distinguish it from other kinds of components, we call this type of component a *Router Component*. :marked ## Add a *Dashboard* Routing only makes sense when we have multiple views. We need another view. Create a placeholder `DashboardComponent` that gives us something to navigate to and from. +makeExample('toh-5/dart/lib/dashboard_component_1.dart',null, 'lib/dashboard_component.dart (v1)')(format=".") :marked We’ll come back and make it more useful later. ### Configure the dashboard route Go back to `app_component.dart` and teach it to navigate to the dashboard. Import the `DashboardComponent` so we can reference it in the dashboard route definition. Add the following `'Dashboard'` route definition to the `@RouteConfig` array of definitions. +makeExample('toh-5/dart/lib/app_component.dart','dashboard-route', 'app_component.dart (Dashboard Route)')(format=".") .l-sub-section :marked **useAsDefault** We want the app to show the dashboard when it starts and we want to see a nice URL in the browser address bar that says `/dashboard`. Remember that the browser launches with `/` in the address bar. We don't have a route for that path and we'd rather not create one. Fortunately we can add the `useAsDefault: true` property to the *route definition* and the router will display the dashboard when the browser URL doesn't match an existing route. :marked Finally, add a dashboard navigation link to the template, just above the *Heroes* link. +makeExample('toh-5/dart/lib/app_component.dart','template', 'app_component.dart (template)')(format=".") .l-sub-section :marked We nestled the two links within `