From 1ad9d7bcb62b54836b37b6b61ae733912ad6da53 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 12 Aug 2016 13:27:32 -0700 Subject: [PATCH 1/2] toh-pt5: cached version before new router was introduced --- public/docs/ts/_cache/tutorial/toh-pt5.jade | 710 ++++++++++++++++++++ 1 file changed, 710 insertions(+) create mode 100644 public/docs/ts/_cache/tutorial/toh-pt5.jade diff --git a/public/docs/ts/_cache/tutorial/toh-pt5.jade b/public/docs/ts/_cache/tutorial/toh-pt5.jade new file mode 100644 index 0000000000..9500cc490f --- /dev/null +++ b/public/docs/ts/_cache/tutorial/toh-pt5.jade @@ -0,0 +1,710 @@ +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-deprecated.html) chapter covers the router in more detail + than we will in this tutorial. + +p Run the #[+liveExampleLink2('', 'toh-5')] for this part. + +.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 app + .children + .file app.component.ts + .file hero.ts + .file hero-detail.component.ts + .file hero.service.ts + .file main.ts + .file mock-heroes.ts + .file node_modules ... + .file typings ... + .file index.html + .file package.json + .file styles.css + .file systemjs.config.js + .file tsconfig.json + .file typings.json +:marked + ### Keep the app transpiling and running + Open a terminal/console window and enter the following command to + start the TypeScript compiler, start the server, and watch for changes: + +code-example(language="bash"). + npm start + +:marked + The application runs and updates automatically as we continue to build the Tour of Heroes. + + ## 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 to rename: + * `app.component.ts` file to `heroes.component.ts` + * `AppComponent` class to `HeroesComponent` + * Selector `my-app` to `my-heroes` + +:marked ++makeExample('toh-5/ts/app/heroes.component.ts', 'heroes-component-renaming', 'app/heroes.component.ts (showing renamings only)')(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.ts`. + * define an `AppComponent` class. + * `export` it so we can reference it during bootstrapping in `main.ts`. + * 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/ts/app/app.component.1.ts', null, 'app/app.component.ts (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*. + + ### Set the base tag + Open the `index.html` and add `` at the top of the `` section. ++makeExample('toh-5/ts/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-deprecated.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/ts/app/app.component.2.ts', 'import-router', 'app/app.component.ts (router imports)')(format=".") +:marked + Next we update the `directives` and `providers` metadata arrays to *include* the router assets. ++makeExample('toh-5/ts/app/app.component.2.ts', 'directives-and-providers', 'app/app.component.ts (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/ts/app/app.component.2.ts', 'route-config', 'app/app.component.ts (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-deprecated.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/ts/app/app.component.2.ts', 'template', 'app/app.component.ts (template v1)')(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-deprecated.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/ts/app/app.component.2.ts',null, 'app/app.component.ts (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/ts/app/dashboard.component.1.ts',null, 'app/dashboard.component.ts (v1)')(format=".") +:marked + We’ll come back and make it more useful later. + + ### Configure the dashboard route + Go back to `app.component.ts` 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/ts/app/app.component.ts','dashboard-route', 'app/app.component.ts (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/ts/app/app.component.ts','template', 'app/app.component.ts (template)')(format=".") +.l-sub-section + :marked + We nestled the two links within `