diff --git a/aio/content/tutorial/toh-pt5.en.md b/aio/content/tutorial/toh-pt5.en.md new file mode 100644 index 0000000000..81e500e629 --- /dev/null +++ b/aio/content/tutorial/toh-pt5.en.md @@ -0,0 +1,573 @@ +# Add in-app navigation with routing + +There are new requirements for the Tour of Heroes app: + +* Add a *Dashboard* view. +* Add the ability to navigate between the *Heroes* and *Dashboard* views. +* When users click a hero name in either view, navigate to a detail view of the selected hero. +* When users click a *deep link* in an email, open the detail view for a particular hero. + +
+ + For the sample app that this page describes, see the . + +
+ +When you’re done, users will be able to navigate the app like this: + +
+ View navigations +
+ +## Add the `AppRoutingModule` + +In Angular, the best practice is to load and configure the router in a separate, top-level module +that is dedicated to routing and imported by the root `AppModule`. + +By convention, the module class name is `AppRoutingModule` and it belongs in the `app-routing.module.ts` in the `src/app` folder. + +Use the CLI to generate it. + + + ng generate module app-routing --flat --module=app + + +
+ +`--flat` puts the file in `src/app` instead of its own folder.
+`--module=app` tells the CLI to register it in the `imports` array of the `AppModule`. +
+ +The generated file looks like this: + + + + +Replace it with the following: + + + + +First, `AppRoutingModule` imports `RouterModule` and `Routes` so the app can have routing functionality. The next import, `HeroesComponent`, will give the Router somewhere to go once you configure the routes. + +Notice that the `CommonModule` references and `declarations` array are unnecessary, so are no +longer part of `AppRoutingModule`. The following sections explain the rest of the `AppRoutingModule` in more detail. + + +### Routes + +The next part of the file is where you configure your routes. +*Routes* tell the Router which view to display when a user clicks a link or +pastes a URL into the browser address bar. + +Since `AppRoutingModule` already imports `HeroesComponent`, you can use it in the `routes` array: + + + + +A typical Angular `Route` has two properties: + +* `path`: a string that matches the URL in the browser address bar. +* `component`: the component that the router should create when navigating to this route. + +This tells the router to match that URL to `path: 'heroes'` +and display the `HeroesComponent` when the URL is something like `localhost:4200/heroes`. + +### `RouterModule.forRoot()` + +The `@NgModule` metadata initializes the router and starts it listening for browser location changes. + +The following line adds the `RouterModule` to the `AppRoutingModule` `imports` array and +configures it with the `routes` in one step by calling +`RouterModule.forRoot()`: + + + + +
+ + The method is called `forRoot()` because you configure the router at the application's root level. + The `forRoot()` method supplies the service providers and directives needed for routing, + and performs the initial navigation based on the current browser URL. + +
+ +Next, `AppRoutingModule` exports `RouterModule` so it will be available throughout the app. + + + + +## Add `RouterOutlet` + +Open the `AppComponent` template and replace the `` element with a `` element. + + + + +The `AppComponent` template no longer needs `` because the app will only display the `HeroesComponent` when the user navigates to it. + +The `` tells the router where to display routed views. + +
+ +The `RouterOutlet` is one of the router directives that became available to the `AppComponent` +because `AppModule` imports `AppRoutingModule` which exported `RouterModule`. The `ng generate` command you ran at the start of this tutorial added this import because of the `--module=app` flag. If you manually created `app-routing.module.ts` or used a tool other than the CLI to do so, you'll need to import `AppRoutingModule` into `app.module.ts` and add it to the `imports` array of the `NgModule`. + +
+ +#### Try it + +You should still be running with this CLI command. + + + ng serve + + +The browser should refresh and display the app title but not the list of heroes. + +Look at the browser's address bar. +The URL ends in `/`. +The route path to `HeroesComponent` is `/heroes`. + +Append `/heroes` to the URL in the browser address bar. +You should see the familiar heroes master/detail view. + +{@a routerlink} + +## Add a navigation link (`routerLink`) + +Ideally, users should be able to click a link to navigate rather +than pasting a route URL into the address bar. + +Add a `