diff --git a/aio/content/examples/router/src/app/app-routing.module.7.ts b/aio/content/examples/router/src/app/app-routing.module.7.ts new file mode 100644 index 0000000000..f64ff71829 --- /dev/null +++ b/aio/content/examples/router/src/app/app-routing.module.7.ts @@ -0,0 +1,11 @@ +import { NgModule } from '@angular/core'; +import { Routes, RouterModule } from '@angular/router'; // CLI imports router + +const routes: Routes = []; // sets up routes constant where you define your routes + +// configures NgModule imports and exports +@NgModule({ + imports: [RouterModule.forRoot(routes)], + exports: [RouterModule] +}) +export class AppRoutingModule { } diff --git a/aio/content/examples/router/src/app/app-routing.module.8.ts b/aio/content/examples/router/src/app/app-routing.module.8.ts new file mode 100644 index 0000000000..7186ced298 --- /dev/null +++ b/aio/content/examples/router/src/app/app-routing.module.8.ts @@ -0,0 +1,26 @@ +// #docplaster +import { NgModule } from '@angular/core'; +import { Routes, RouterModule } from '@angular/router'; // CLI imports router + +// #docregion routes, routes-with-wildcard, redirect +const routes: Routes = [ + { path: 'first-component', component: FirstComponent }, + { path: 'second-component', component: SecondComponent }, + // #enddocregion routes + { path: '', redirectTo: '/first-component', pathMatch: 'full' }, // redirect to `first-component` + { path: '**', component: FirstComponent }, + // #enddocregion redirect + { path: '**', component: PageNotFoundComponent }, // Wildcard route for a 404 page + // #docregion routes + // #docregion redirect +]; +// #enddocregion routes, routes-with-wildcard, redirect + + +@NgModule({ + imports: [RouterModule.forRoot(routes)], + exports: [RouterModule] +}) +export class AppRoutingModule { } + + diff --git a/aio/content/examples/router/src/app/app-routing.module.9.ts b/aio/content/examples/router/src/app/app-routing.module.9.ts new file mode 100644 index 0000000000..cd4ddd1d70 --- /dev/null +++ b/aio/content/examples/router/src/app/app-routing.module.9.ts @@ -0,0 +1,28 @@ +// #docplaster +import { NgModule } from '@angular/core'; +import { Routes, RouterModule } from '@angular/router'; // CLI imports router + +// #docregion child-routes +const routes: Routes = [ + { path: 'first-component', + component: FirstComponent, // this is the component with the in the template + children: [ + { + path: 'child-a', // child route path + component: ChildAComponent // child route component that the router renders + }, + { + path: 'child-b', + component: ChildBComponent // another child route component that the router renders + } + ] }, +// #enddocregion child-routes + + +@NgModule({ + imports: [RouterModule.forRoot(routes)], + exports: [RouterModule] +}) +export class AppRoutingModule { } + + diff --git a/aio/content/examples/router/src/app/app.component.4.ts b/aio/content/examples/router/src/app/app.component.4.ts new file mode 100644 index 0000000000..4b47a4c66f --- /dev/null +++ b/aio/content/examples/router/src/app/app.component.4.ts @@ -0,0 +1,15 @@ +import { Component } from '@angular/core'; + +@Component({ + selector: 'app-root', + templateUrl: 'app.component.html', + styleUrls: ['app.component.css'] +}) +export class AppComponent { +// #docregion relative-to + goToItems() { + this.router.navigate(['items'], { relativeTo: this.route }); + } +// #enddocregion relative-to + +} diff --git a/aio/content/examples/router/src/app/app.component.7.html b/aio/content/examples/router/src/app/app.component.7.html new file mode 100644 index 0000000000..a13d8a97d8 --- /dev/null +++ b/aio/content/examples/router/src/app/app.component.7.html @@ -0,0 +1,10 @@ +

Angular Router App

+ + + + diff --git a/aio/content/examples/router/src/app/app.component.8.html b/aio/content/examples/router/src/app/app.component.8.html new file mode 100644 index 0000000000..74791aa9cd --- /dev/null +++ b/aio/content/examples/router/src/app/app.component.8.html @@ -0,0 +1,26 @@ + +

First Component

+ + + + + + + + + +

First Component

+ + + + + diff --git a/aio/content/examples/router/src/app/app.module.8.ts b/aio/content/examples/router/src/app/app.module.8.ts new file mode 100644 index 0000000000..3f0b1c0c0b --- /dev/null +++ b/aio/content/examples/router/src/app/app.module.8.ts @@ -0,0 +1,17 @@ +import { BrowserModule } from '@angular/platform-browser'; +import { NgModule } from '@angular/core'; +import { AppRoutingModule } from './app-routing.module'; // CLI imports AppRoutingModule +import { AppComponent } from './app.component'; + +@NgModule({ + declarations: [ + AppComponent + ], + imports: [ + BrowserModule, + AppRoutingModule // CLI adds AppRoutingModule to the AppModule's imports array + ], + providers: [], + bootstrap: [AppComponent] +}) +export class AppModule { } diff --git a/aio/content/examples/router/src/app/heroes/hero-detail/hero-detail.component.ts b/aio/content/examples/router/src/app/heroes/hero-detail/hero-detail.component.ts index 720301d192..8f54532b65 100644 --- a/aio/content/examples/router/src/app/heroes/hero-detail/hero-detail.component.ts +++ b/aio/content/examples/router/src/app/heroes/hero-detail/hero-detail.component.ts @@ -2,7 +2,9 @@ // #docregion import { switchMap } from 'rxjs/operators'; import { Component, OnInit } from '@angular/core'; +// #docregion imports-route-info import { Router, ActivatedRoute, ParamMap } from '@angular/router'; +// #enddocregion imports-route-info import { Observable } from 'rxjs'; import { HeroService } from '../hero.service'; @@ -16,11 +18,16 @@ import { Hero } from '../hero'; export class HeroDetailComponent implements OnInit { hero$: Observable; + // #docregion activated-route constructor( private route: ActivatedRoute, + // #enddocregion activated-route private router: Router, private service: HeroService + // #docregion activated-route ) {} + // #enddocregion activated-route + ngOnInit() { this.hero$ = this.route.paramMap.pipe( diff --git a/aio/content/guide/ajs-quick-reference.md b/aio/content/guide/ajs-quick-reference.md index 994ffbd5d1..e0b1a512e4 100644 --- a/aio/content/guide/ajs-quick-reference.md +++ b/aio/content/guide/ajs-quick-reference.md @@ -415,8 +415,8 @@ The following are some of the key AngularJS built-in directives and their equiva - For more information on routing, see the [RouterLink binding](guide/router#router-link) - section of the [Routing & Navigation](guide/router) page. + For more information on routing, see [Defining a basic route](guide/router#basic-route) + in the [Routing & Navigation](guide/router) page. diff --git a/aio/content/guide/browser-support.md b/aio/content/guide/browser-support.md index 12e0ac0c1c..97492e33b7 100644 --- a/aio/content/guide/browser-support.md +++ b/aio/content/guide/browser-support.md @@ -303,7 +303,7 @@ Some features of Angular may require additional polyfills. [Router](guide/router) when using - [hash-based routing](guide/router#appendix-locationstrategy-and-browser-url-styles) + [hash-based routing](guide/router#location-strategy) diff --git a/aio/content/guide/deployment.md b/aio/content/guide/deployment.md index ed0ba4a182..10b1b39701 100644 --- a/aio/content/guide/deployment.md +++ b/aio/content/guide/deployment.md @@ -321,7 +321,7 @@ absolutely must be present when the app starts. Configure the Angular Router to defer loading of all other modules (and their associated code), either by [waiting until the app has launched](guide/router#preloading "Preloading") -or by [_lazy loading_](guide/router#asynchronous-routing "Lazy loading") +or by [_lazy loading_](guide/router#lazy-loading "Lazy loading") them on demand.
diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md index 880affa372..cdd80f9c61 100644 --- a/aio/content/guide/deprecations.md +++ b/aio/content/guide/deprecations.md @@ -318,6 +318,7 @@ const routes: Routes = [{ {@a activatedroute-props} + ### ActivatedRoute params and queryParams properties [ActivatedRoute](api/router/ActivatedRoute) contains two [properties](api/router/ActivatedRoute#properties) that are less capable than their replacements and may be deprecated in a future Angular version. @@ -327,7 +328,7 @@ const routes: Routes = [{ | `params` | `paramMap` | | `queryParams` | `queryParamMap` | -For more information see the [Router guide](guide/router#activated-route). +For more information see the [Getting route information](guide/router#activated-route) section of the [Router guide](guide/router). {@a reflect-metadata} diff --git a/aio/content/guide/router.md b/aio/content/guide/router.md index f8bbda36b2..a6af240ae5 100644 --- a/aio/content/guide/router.md +++ b/aio/content/guide/router.md @@ -1,734 +1,548 @@ # In-app navigation with routing -The Angular **`Router`** enables navigation from one [view](guide/glossary#view "View definition") to the next -as users perform application tasks. +You want the applications you build to be as fast and responsive as possible. +In Angular, a common best practice to improve responsiveness is to build _singe-page apps_. +With single-page apps, your users stay on a single page, but their view of that page changes depending on what the user wants to do. -This guide covers the router's primary features, illustrating them through the evolution -of a small application that you can run live in the browser. +To handle the navigation from one [view](guide/glossary#view) to the next, you use the Angular _router_. +The router enables navigation by interpreting a browser URL as an instruction to change the view. - - +To explore a sample app featuring the router's primary features, see the . +## Prerequisites -## Overview +Before creating a route, you should be familiar with the following: -The browser is a familiar model of application navigation: +* [Basics of components](guide/architecture-components) +* [Basics of templates](guide/glossary#template) +* An Angular app—you can generate a basic Angular app using the [Angular CLI](cli). -* Enter a URL in the address bar and the browser navigates to a corresponding page. -* Click links on the page and the browser navigates to a new page. -* Click the browser's back and forward buttons and the browser navigates - backward and forward through the history of pages you've seen. +For an introduction to Angular with a ready-made app, see [Getting Started](start). +For a more in-depth experience of building an Angular app, see the [Tour of Heroes](tutorial) tutorial. Both guide you through using component classes and templates. -The Angular `Router` ("the router") borrows from this model. -It can interpret a browser URL as an instruction to navigate to a client-generated view. -It can pass optional parameters along to the supporting view component that help it decide what specific content to present. -You can bind the router to links on a page and it will navigate to -the appropriate application view when the user clicks a link. -You can navigate imperatively when the user clicks a button, selects from a drop box, -or in response to some other stimulus from any source. And the router logs activity -in the browser's history journal so the back and forward buttons work as well. +
{@a basics} +## Generate an app with routing enabled -## The Basics +The following command uses the Angular CLI to generate a basic Angular app with an app routing module, called `AppRoutingModule`, which is an NgModule where you can configure your routes. +The app name in the following example is `routing-app`. -This guide proceeds in phases, marked by milestones, starting from a simple two-pager -and building toward a modular, multi-view design with child routes. + + ng new routing-app --routing + -An introduction to a few core router concepts will help orient you to the details that follow. +When generating a new app, the CLI prompts you to select CSS or a CSS preprocessor. +For this example, accept the default of `CSS`. +### Adding components for routing + +To use the Angular router, an app needs to have at least two components so that it can navigate from one to the other. To create a component using the CLI, enter the following at the command line where `first` is the name of your component: + + + ng generate component first + + +Repeat this step for a second component but give it a different name. +Here, the new name is `second`. + + + ng generate component second + + +The CLI automatically appends `Component`, so if you were to write `first-component`, your component would be `FirstComponentComponent`. {@a basics-base-href} - -### *<base href>* - -Most routing applications should add a `` element to the `index.html` as the first child in the `` tag -to tell the router how to compose navigation URLs. - -If the `app` folder is the application root, as it is for the sample application, -set the `href` value *exactly* as shown here. - - - - - - -{@a basics-router-imports} - - -### Router imports - -The Angular Router is an optional service that presents a particular component view for a given URL. -It is not part of the Angular core. It is in its own library package, `@angular/router`. -Import what you need from it as you would from any other Angular package. - - - - - -
+ #### `` + This guide works with a CLI-generated Angular app. + If you are working manually, make sure that you have `` in the `` of your index.html file. + This assumes that the `app` folder is the application root, and uses `"/"`. -You'll learn about more options in the [details below](#browser-url-styles). - +
+### Importing your new components -{@a basics-config} +To use your new components, import them into `AppRoutingModule` at the top of the file, as follows: + -### Configuration - -A routed Angular application has one singleton instance of the *`Router`* service. -When the browser's URL changes, that router looks for a corresponding `Route` -from which it can determine the component to display. - -A router has no routes until you configure it. -The following example creates five route definitions, configures the router via the `RouterModule.forRoot()` method, -and adds the result to the `AppModule`'s `imports` array. - - - - - - -{@a example-config} - - -The `appRoutes` array of *routes* describes how to navigate. -Pass it to the `RouterModule.forRoot()` method in the module `imports` to configure the router. - -Each `Route` maps a URL `path` to a component. -There are _no leading slashes_ in the _path_. -The router parses and builds the final URL for you, -allowing you to use both relative and absolute paths when navigating between application views. - -The `:id` in the second route is a token for a route parameter. In a URL such as `/hero/42`, "42" -is the value of the `id` parameter. The corresponding `HeroDetailComponent` -will use that value to find and present the hero whose `id` is 42. -You'll learn more about route parameters later in this guide. - -The `data` property in the third route is a place to store arbitrary data associated with -this specific route. The data property is accessible within each activated route. Use it to store -items such as page titles, breadcrumb text, and other read-only, _static_ data. -You'll use the [resolve guard](#resolve-guard) to retrieve _dynamic_ data later in the guide. - -The **empty path** in the fourth route represents the default path for the application, -the place to go when the path in the URL is empty, as it typically is at the start. -This default route redirects to the route for the `/heroes` URL and, therefore, will display the `HeroesListComponent`. - -The `**` path in the last route is a **wildcard**. The router will select this route -if the requested URL doesn't match any paths for routes defined earlier in the configuration. -This is useful for displaying a "404 - Not Found" page or redirecting to another route. - -**The order of the routes in the configuration matters** and this is by design. The router uses a **first-match wins** -strategy when matching routes, so more specific routes should be placed above less specific routes. -In the configuration above, routes with a static path are listed first, followed by an empty path route, -that matches the default route. -The wildcard route comes last because it matches _every URL_ and should be selected _only_ if no other routes are matched first. - -If you need to see what events are happening during the navigation lifecycle, there is the **enableTracing** option as part of the router's default configuration. This outputs each router event that took place during each navigation lifecycle to the browser console. This should only be used for _debugging_ purposes. You set the `enableTracing: true` option in the object passed as the second argument to the `RouterModule.forRoot()` method. - -{@a basics-router-outlet} - - -### Router outlet - -The `RouterOutlet` is a directive from the router library that is used like a component. -It acts as a placeholder that marks the spot in the template where the router should -display the components for that outlet. - - - - <router-outlet></router-outlet> - <!-- Routed components go here --> +import { FirstComponent } from './first/first.component'; +import { SecondComponent } from './second/second.component'; -Given the configuration above, when the browser URL for this application becomes `/heroes`, -the router matches that URL to the route path `/heroes` and displays the `HeroListComponent` -as a sibling element to the `RouterOutlet` that you've placed in the host component's template. +{@a basic-route} -{@a basics-router-links} -{@a router-link} +## Defining a basic route +There are three fundamental building blocks to creating a route. -### Router links +Import the `AppRoutingModule` into `AppModule` and add it to the `imports` array. -Now you have routes configured and a place to render them, but -how do you navigate? The URL could arrive directly from the browser address bar. -But most of the time you navigate as a result of some user action such as the click of -an anchor tag. +The Angular CLI performs this step for you. +However, if you are creating an app manually or working with an existing, non-CLI app, verify that the imports and configuration are correct. +The following is the default `AppModule` using the CLI with the `--routing` flag. -Consider the following template: + + - + 1. Import `RouterModule` and `Routes` into your routing module. -The `RouterLink` directives on the anchor tags give the router control over those elements. -The navigation paths are fixed, so you can assign a string to the `routerLink` (a "one-time" binding). + The Angular CLI performs this step automatically. + The CLI also sets up a `Routes` array for your routes and configures the `imports` and `exports` arrays for `@NgModule()`. -Had the navigation path been more dynamic, you could have bound to a template expression that -returned an array of route link parameters (the _link parameters array_). -The router resolves that array into a complete URL. + + -{@a router-link-active} +1. Define your routes in your `Routes` array. + Each route in this array is a JavaScript object that contains two properties. + The first property, `path`, defines the URL path for the route. + The second property, `component`, defines the component Angular should use for the corresponding path. -### Active router links + -The `RouterLinkActive` directive toggles css classes for active `RouterLink` bindings based on the current `RouterState`. + -On each anchor tag, you see a [property binding](guide/template-syntax#property-binding) to the `RouterLinkActive` directive that look like `routerLinkActive="..."`. + 1. Add your routes to your application. -The template expression to the right of the equals (=) contains a space-delimited string of CSS classes -that the Router will add when this link is active (and remove when the link is inactive). You set the `RouterLinkActive` -directive to a string of classes such as `[routerLinkActive]="'active fluffy'"` or bind it to a component -property that returns such a string. + Now that you have defined your routes, you can add them to your application. + First, add links to the two components. + Assign the anchor tag that you want to add the route to the `routerLink` attribute. + Set the value of the attribute to the component to show when a user clicks on each link. + Next, update your component template to include ``. + This element informs Angular to update the application view with the component for the selected route. -Active route links cascade down through each level of the route tree, so parent and child router links can be active at the same time. To override this behavior, you can bind to the `[routerLinkActiveOptions]` input binding with the `{ exact: true }` expression. By using `{ exact: true }`, a given `RouterLink` will only be active if its URL is an exact match to the current URL. + +{@a route-order} -{@a basics-router-state} +### Route order - -### Router state - -After the end of each successful navigation lifecycle, the router builds a tree of `ActivatedRoute` objects -that make up the current state of the router. You can access the current `RouterState` from anywhere in the -application using the `Router` service and the `routerState` property. - -Each `ActivatedRoute` in the `RouterState` provides methods to traverse up and down the route tree -to get information from parent, child and sibling routes. +The order of routes is important because the `Router` uses a first-match wins strategy when matching routes, so more specific routes should be placed above less specific routes. +List routes with a static path first, followed by an empty path route, which matches the default route. +The [wildcard route](guide/router#setting-up-wildcard-routes) comes last because it matches every URL and the `Router` selects it only if no other routes match first. {@a activated-route} +## Getting route information -### Activated route +Often, as a user navigates your application, you want to pass information from one component to another. +For example, consider an application that displays a shopping list of grocery items. +Each item in the list has a unique `id`. +To edit an item, users click an Edit button, which opens an `EditGroceryItem` component. +You want that component to retrieve the `id` for the grocery item so it can display the right information to the user. -The route path and parameters are available through an injected router service called the -[ActivatedRoute](api/router/ActivatedRoute). -It has a great deal of useful information including: +You can use a route to pass this type of information to your application components. +To do so, you use the [ActivatedRoute](api/router/ActivatedRoute) interface. - - - +To get information from a route: - - + 1. Import `ActivatedRoute` and `ParamMap` to your component. - - - - + * [`Router`](api/router) + * [`ActivatedRoute`](api/router/ActivatedRoute) + * [`ParamMap`](api/router/ParamMap) - - - - + 1. Update the `ngOnInit()` method to access the `ActivatedRoute` and track the `id` parameter: - - - - +{@a wildcard-route-how-to} - - - - +To set up a wildcard route, add the following code to your `routes` definition. - - - - + - - - - - - - - +To display a 404 page, set up a [wildcard route](guide/router#wildcard-route-how-to) with the `component` property set to the component you'd like to use for your 404 page as follows: - - - - +The last route with the `path` of `**` is a wildcard route. +The router selects this route if the requested URL doesn't match any of the paths earlier in the list and sends the user to the `PageNotFoundComponent`. - - - - + - - - - -
- Property - - Description -
- url - + + - An `Observable` of the route path(s), represented as an array of strings for each part of the route path. + These `import` statements add several important elements that your component needs. + To learn more about each, see the following API pages: -
- data - + 1. Inject an instance of `ActivatedRoute` by adding it to your application's constructor: - An `Observable` that contains the `data` object provided for the route. Also contains any resolved values from the [resolve guard](#resolve-guard). + + -
- paramMap - + + ngOnInit() { + this.activatedRoute.queryParams.subscribe(params => { + this.name = params['name']; + }); + } + - An `Observable` that contains a [map](api/router/ParamMap) of the required and [optional parameters](#optional-route-parameters) specific to the route. The map supports retrieving single and multiple values from the same parameter. + Note: The preceding example uses a variable, `name`, and assigns it the value based on the `name` parameter. -
- queryParamMap - +## Setting up wildcard routes - An `Observable` that contains a [map](api/router/ParamMap) of the [query parameters](#query-parameters) available to all routes. - The map supports retrieving single and multiple values from the query parameter. +A well-functioning application should gracefully handle when users attempt to navigate to a part of your application that does not exist. +To add this functionality to your application, you set up a wildcard route. +The Angular router selects this route any time the requested URL doesn't match any router paths. -
- fragment - + - An `Observable` of the URL [fragment](#fragment) available to all routes. +{ path: '**', component: } -
- outlet - - The name of the `RouterOutlet` used to render the route. For an unnamed outlet, the outlet name is _primary_. +The two asterisks, `**`, indicate to Angular that this `routes` definition is a wildcard route. +For the component property, you can define any component in your application. +Common choices include an application-specific `PageNotFoundComponent`, which you can define to [display a 404 page](guide/router#404-page-how-to) to your users; or a redirect to your application's main component. +A wildcard route is the last route because it matches any URL. +For more detail on why order matters for routes, see [Route order](guide/router#route-order). -
- routeConfig - +{@a 404-page-how-to} - The route configuration used for the route that contains the origin path. +## Displaying a 404 page -
- parent - + - The route's parent `ActivatedRoute` when this route is a [child route](#child-routing-component). + -
- firstChild - +## Setting up redirects - Contains the first `ActivatedRoute` in the list of this route's child routes. +To set up a redirect, configure a route with the `path` you want to redirect from, the `component` you want to redirect to, and a `pathMatch` value that tells the router how to match the URL. -
- children - + - Contains all the [child routes](#child-routing-component) activated under the current route. +In this example, the third route is a redirect so that the router defaults to the `first-component` route. +Notice that this redirect precedes the wildcard route. +Here, `path: ''` means to use the initial relative URL (`''`). -
+For more details on `pathMatch` see [Spotlight on `pathMatch`](guide/router#pathmatch). -
+{@a nesting-routes} -Two older properties are still available. They are less capable than their replacements, discouraged, and may be deprecated in a future Angular version. +## Nesting routes -**`params`**—An `Observable` that contains the required and [optional parameters](#optional-route-parameters) specific to the route. Use `paramMap` instead. +As your application grows more complex, you may want to create routes that are relative to a component other than your root component. +These types of nested routes are called child routes. +This means you're adding a second `` to your app, because it is in addition to the `` in `AppComponent`. -**`queryParams`**—An `Observable` that contains the [query parameters](#query-parameters) available to all routes. -Use `queryParamMap` instead. +In this example, there are two additional child components, `child-a`, and `child-b`. +Here, `FirstComponent` has its own `
+ -### Router events + -During each navigation, the `Router` emits navigation events through the `Router.events` property. These events range from when the navigation starts and ends to many points in between. The full list of navigation events is displayed in the table below. +A child route is like any other route, in that it needs both a `path` and a `component`. +The one difference is that you place child routes in a `children` array within the parent route. - - - + - - + - - - - +Relative paths allow you to define paths that are relative to the current URL segment. +The following example shows a relative route to another component, `second-component`. +`FirstComponent` and `SecondComponent` are at the same level in the tree, however, the link to `SecondComponent` is situated within the `FirstComponent`, meaning that the router has to go up a level and then into the second directory to find the `SecondComponent`. +Rather than writing out the whole path to get to `SecondComponent`, you can use the `../` notation to go up a level. - - - - +In addition to `../`, you can use `./` or no leading slash to specify the current level. - - - - +Then use `relativeTo` in your navigation method. +After the link parameters array, which here contains `items`, add an object with the `relativeTo` property set to the `ActivatedRoute`, which is `this.route`. - - - - + - - - - +Sometimes, a feature of your application requires accessing a part of a route, such as a query parameter or a fragment. The Tour of Heroes app at this stage in the tutorial uses a list view in which you can click on a hero to see details. The router uses an `id` to show the correct hero's details. - - - - +import { ActivatedRoute } from '@angular/router'; +import { Observable } from 'rxjs'; +import { switchMap } from 'rxjs/operators'; - - - - + +constructor(private route: ActivatedRoute) {} + - - - - +ngOnInit() { + this.heroes$ = this.route.paramMap.pipe( + switchMap(params => { + this.selectedId = Number(params.get('id')); + return this.service.getHeroes(); + }) + ); +} - - - - +Next, in the component that you want to navigate to, import the following members. - - - - + - - - - + - - - - + ngOnInit() { + let id = this.route.snapshot.paramMap.get('id'); + this.hero$ = this.service.getHero(id); + } - - - - +{@a lazy-loading} - - - - + - - - - +In the lazy loaded module's routing module, add a route for the component. - - - - -
- Router Event - - Description -
- NavigationStart - +{@a using-relative-paths} - An [event](api/router/NavigationStart) triggered when navigation starts. +## Using relative paths -
- RouteConfigLoadStart - + - An [event](api/router/RouteConfigLoadStart) triggered before the `Router` - [lazy loads](#asynchronous-routing) a route configuration. + -
- RouteConfigLoadEnd - +### Specifying a relative route - An [event](api/router/RouteConfigLoadEnd) triggered after a route has been lazy loaded. +To specify a relative route, use the `NavigationExtras` `relativeTo` property. +In the component class, import `NavigationExtras` from the `@angular/router`. -
- RoutesRecognized - + - An [event](api/router/RoutesRecognized) triggered when the Router parses the URL and the routes are recognized. +The `navigate()` arguments configure the router to use the current route as a basis upon which to append `items`. -
- GuardsCheckStart - +The `goToItems()` method interprets the destination URI as relative to the activated route and navigates to the `items` route. - An [event](api/router/GuardsCheckStart) triggered when the Router begins the Guards phase of routing. +## Accessing query parameters and fragments -
- ChildActivationStart - +First, import the following members in the component you want to navigate from. - An [event](api/router/ChildActivationStart) triggered when the Router begins activating a route's children. + -
- ActivationStart - + - An [event](api/router/ActivationStart) triggered when the Router begins activating a route. +Next inject the activated route service: -
- GuardsCheckEnd - +Configure the class so that you have an observable, `heroes$`, a `selectedId` to hold the `id` number of the hero, and the heroes in the `ngOnInit()`, add the following code to get the `id` of the selected hero. +This code snippet assumes that you have a heroes list, a hero service, a function to get your heroes, and the HTML to render your list and details, just as in the Tour of Heroes example. - An [event](api/router/GuardsCheckEnd) triggered when the Router finishes the Guards phase of routing successfully. + +heroes$: Observable; +selectedId: number; +heroes = HEROES; -
- ResolveStart - + - An [event](api/router/ResolveStart) triggered when the Router begins the Resolve phase of routing. -
- ResolveEnd - + - An [event](api/router/ResolveEnd) triggered when the Router finishes the Resolve phase of routing successfuly. +import { Router, ActivatedRoute, ParamMap } from '@angular/router'; +import { Observable } from 'rxjs'; -
- ChildActivationEnd - +Inject `ActivatedRoute` and `Router` in the constructor of the component class so they are available to this component: - An [event](api/router/ChildActivationEnd) triggered when the Router finishes activating a route's children. -
- ActivationEnd - + item$: Observable; - An [event](api/router/ActivationStart) triggered when the Router finishes activating a route. + constructor( + private route: ActivatedRoute, + private router: Router ) {} -
- NavigationEnd - + gotoItems(item: Item) { + let heroId = item ? hero.id : null; + // Pass along the item id if available + // so that the HeroList component can select that item. + this.router.navigate(['/heroes', { id: itemId }]); + } - An [event](api/router/NavigationEnd) triggered when navigation ends successfully. + -
- NavigationCancel - +## Lazy loading modules - An [event](api/router/NavigationCancel) triggered when navigation is canceled. - This can happen when a [Route Guard](#guards) returns false during navigation, - or redirects by returning a `UrlTree`. +To lazy load Angular modules, use `loadchildren` (instead of `component`) in your `AppRoutingModule` `routes` configuration as follows: -
- NavigationError - +const routes: Routes = [ + { + path: 'items', + loadChildren: () => import('./items/items.module').then(m => m.ItemsModule) + } +]; - An [event](api/router/NavigationError) triggered when navigation fails due to an unexpected error. + -
- Scroll - + - An [event](api/router/Scroll) that represents a scrolling event. +const routes: Routes = [ + { + path: '', + component: ItemsComponent + } +]; -
+ -These events are logged to the console when the `enableTracing` option is enabled also. For an example of filtering router navigation events, visit the [router section](guide/observables-in-angular#router) of the [Observables in Angular](guide/observables-in-angular) guide. +Also be sure to remove the `ItemsModule` from the `AppModule`. For more information on lazy loading modules see [Lazy-loading feature modules](guide/lazy-loading-ngmodules). -{@a basics-summary} +{@a preloading} -### Summary +## Preloading -The application has a configured router. -The shell component has a `RouterOutlet` where it can display views produced by the router. -It has `RouterLink`s that users can click to navigate via the router. +Preloading improves UX by loading parts of your app in the background. You can preload modules or component data. -Here are the key `Router` terms and their meanings: +### Preloading modules - +To enable preloading of all lazy loaded modules, import the `PreloadAllModules` token from the Angular `router`. - + - +import { PreloadAllModules } from '@angular/router'; - + - +Still in the `AppRoutingModule`, specify your preloading strategy in `forRoot()`. - + - +RouterModule.forRoot( + appRoutes, + { + preloadingStrategy: PreloadAllModules + } +) - + - +### Preloading component data - +You can preload component data so that all elements and data on a page render at the same time when the user activates a route. To preload component data, you can use a `resolver`. - +#### Resolvers - +Create a resolver service. With the CLI, the command to generate a service is as follows: - - + + ng generate service + - +In your service, import the following router members, implement `Resolve`, and inject the `Router` service: - + - +import { Resolve } from '@angular/router'; - +... - +export class CrisisDetailResolverService implements Resolve<> { + resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<> { + // your logic goes here + } +} - + - +Import this resolver into your module's routing module. - + - +import { YourResolverService } from './your-resolver.service'; - + - +Add a `resolve` object to the component's `route` configuration. - + +{ + path: '/your-path', + component: YourComponent, + resolve: { + crisis: YourResolverService + } +} + - - +In the component, use an observable to get the data from the `ActivatedRoute`. - - + +ngOnInit() { + this.route.data + .subscribe((your-parameters) => { + // your data-specific code goes here + }); +} + - +For more information with a working example, see the [routing tutorial section on preloading](guide/router#preloading-background-loading-of-feature-areas). - - +## Preventing unauthorized access - +Use route guards to prevent users from navigating to parts of an app without authorization. +The following route guards are available in Angular: - +* [`CanActivate`](api/router/CanActivate) +* [`CanActivateChild`](api/router/CanActivateChild) +* [`CanDeactivate`](api/router/CanDeactivate) +* [`Resolve`](api/router/Resolve) +* [`CanLoad`](api/router/CanLoad) - +To use route guards, consider using component-less routes as this facilitates guarding child routes. - +Create a service for your guard: - - + + ng generate guard your-guard + - +In your guard class, implement the guard you want to use. +The following example uses `CanActivate` to guard the route. - + +export class YourGuard implements CanActivate { + canActivate( + next: ActivatedRouteSnapshot, + state: RouterStateSnapshot): boolean { + // your logic goes here + } +} + - +In your routing module, use the appropriate property in your `routes` configuration. +Here, `canActivate` tells the router to mediate navigation to this particular route. - + +{ + path: '/your-path', + component: YourComponent, + canActivate: [YourGuard], +} + - +For more information with a working example, see the [routing tutorial section on route guards](guide/router#milestone-5-route-guards). - - +{@a router-tutorial} - +## Router tutorial: tour of heroes - +While the [Getting Started: Tour of Heroes](tutorial) tutorial introduces general Angular concepts, this [Router Tutorial](guide/router#getting-started) goes into greater detail regarding Angular's routing capabilities. +This tutorial guides you through building upon basic router configuration to create child routes, read route parameters, lazy load NgModules, guard routes, and preload data to improve the user experience. - -
- Router Part - - Meaning -
- Router - - Displays the application component for the active URL. - Manages navigation from one component to the next. -
- RouterModule - - A separate NgModule that provides the necessary service providers - and directives for navigating through application views. -
- Routes - - Defines an array of Routes, each mapping a URL path to a component. -
- Route - - Defines how the router should navigate to a component based on a URL pattern. - Most routes consist of a path and a component type. -
- RouterOutlet - - The directive (<router-outlet>) that marks where the router displays a view. -
- RouterLink - - The directive for binding a clickable HTML element to - a route. Clicking an element with a routerLink directive - that is bound to a string or a link parameters array triggers a navigation. -
- RouterLinkActive - - The directive for adding/removing classes from an HTML element when an associated - routerLink contained on or inside the element becomes active/inactive. -
- ActivatedRoute - - A service that is provided to each route component that contains route specific - information such as route parameters, static data, resolve data, global query params, and the global fragment. -
- RouterState - - The current state of the router including a tree of the currently activated - routes together with convenience methods for traversing the route tree. -
- Link parameters array - - An array that the router interprets as a routing instruction. - You can bind that array to a RouterLink or pass the array as an argument to - the Router.navigate method. -
- Routing component - - An Angular component with a RouterOutlet that displays views based on router navigations. -
+{@a router-tutorial-overview} - - - -{@a sample-app-intro} - - -## The sample application +### Router tutorial overview This guide describes development of a multi-page routed sample application. -Along the way, it highlights design decisions and describes key features of the router such as: +Along the way, it highlights key features of the router such as: * Organizing the application features into modules. * Navigating to a component (*Heroes* link to "Heroes List"). @@ -738,20 +552,19 @@ Along the way, it highlights design decisions and describes key features of the * The `CanActivateChild` guard (checking child route access). * The `CanDeactivate` guard (ask permission to discard unsaved changes). * The `Resolve` guard (pre-fetching route data). -* Lazy loading feature modules. +* Lazy loading an `NgModule`. * The `CanLoad` guard (check before loading feature module assets). -The guide proceeds as a sequence of milestones as if you were building the app step-by-step. -But, it is not a tutorial and it glosses over details of Angular application construction -that are more thoroughly covered elsewhere in the documentation. +This guide proceeds as a sequence of milestones as if you were building the app step-by-step, but assumes you are familiar with basic [Angular concepts](guide/architecture). +For a general introduction to angular, see the [Getting Started](start). For a more in-depth overview, see the [Tour of Heroes](tutorial) tutorial. -The full source for the final version of the app can be seen and downloaded from the . + +For a working example of the final version of the app, see the . ### The sample application in action -Imagine an application that helps the _Hero Employment Agency_ run its business. -Heroes need work and the agency finds crises for them to solve. +The sample application for this tutorial helps the Hero Employment Agency find crises for heroes to solve. The application has three main feature areas: @@ -761,8 +574,7 @@ The application has three main feature areas: Try it by clicking on this live example link. -Once the app warms up, you'll see a row of navigation buttons -and the *Heroes* view with its list of heroes. +The app renders with a row of navigation buttons and the *Heroes* view with its list of heroes.
@@ -783,8 +595,7 @@ Alter the name. Click the "Back" button and the app returns to the heroes list which displays the changed hero name. Notice that the name change took effect immediately. -Had you clicked the browser's back button instead of the "Back" button, -the app would have returned you to the heroes list as well. +Had you clicked the browser's back button instead of the app's "Back" button, the app would have returned you to the heroes list as well. Angular app navigation updates the browser history as normal web navigation does. Now click the *Crisis Center* link for a list of ongoing crises. @@ -794,8 +605,6 @@ Now click the *Crisis Center* link for a list of ongoing crises. Crisis Center List
- - Select a crisis and the application takes you to a crisis editing screen. The _Crisis Detail_ appears in a child component on the same page, beneath the list. @@ -808,15 +617,10 @@ Notice that the corresponding name in the crisis list does _not_ change.
- -Unlike *Hero Detail*, which updates as you type, -*Crisis Detail* changes are temporary until you either save or discard them by pressing the "Save" or "Cancel" buttons. +Unlike *Hero Detail*, which updates as you type, *Crisis Detail* changes are temporary until you either save or discard them by pressing the "Save" or "Cancel" buttons. Both buttons navigate back to the *Crisis Center* and its list of crises. -***Do not click either button yet***. -Click the browser back button or the "Heroes" link instead. - -Up pops a dialog box. +Click the browser back button or the "Heroes" link to activate a dialog.
@@ -830,16 +634,14 @@ You can say "OK" and lose your changes or click "Cancel" and continue editing. Behind this behavior is the router's `CanDeactivate` guard. The guard gives you a chance to clean-up or ask the user's permission before navigating away from the current view. -The `Admin` and `Login` buttons illustrate other router capabilities to be covered later in the guide. -This short introduction will do for now. +The `Admin` and `Login` buttons illustrate other router capabilities covered later in the guide. -Proceed to the first application milestone. {@a getting-started} ## Milestone 1: Getting started -Begin with a simple version of the app that navigates between two empty views. +Begin with a basic version of the app that navigates between two empty views.
@@ -848,7 +650,7 @@ Begin with a simple version of the app that navigates between two empty views. {@a import} -Generate a sample application to follow the walkthrough. +Generate a sample application with the Angular CLI. ng new angular-router-sample @@ -858,24 +660,19 @@ Generate a sample application to follow the walkthrough. A router must be configured with a list of route definitions. -Each definition translates to a [Route](api/router/Route) object which has two things: a -`path`, the URL path segment for this route; and a -`component`, the component associated with this route. +Each definition translates to a [Route](api/router/Route) object which has two things: a `path`, the URL path segment for this route; and a `component`, the component associated with this route. -The router draws upon its registry of definitions when the browser URL changes -or when application code tells the router to navigate along a route path. +The router draws upon its registry of definitions when the browser URL changes or when application code tells the router to navigate along a route path. -In simpler terms, you might say this of the first route: +The first route does the following: -* When the browser's location URL changes to match the path segment `/crisis-center`, then -the router activates an instance of the `CrisisListComponent` and displays its view. +* When the browser's location URL changes to match the path segment `/crisis-center`, then the router activates an instance of the `CrisisListComponent` and displays its view. -* When the application requests navigation to the path `/crisis-center`, the router -activates an instance of `CrisisListComponent`, displays its view, and updates the -browser's address location and history with the URL for that path. +* When the application requests navigation to the path `/crisis-center`, the router activates an instance of `CrisisListComponent`, displays its view, and updates the browser's address location and history with the URL for that path. -The first configuration defines an array of two routes with simple paths leading to the -`CrisisListComponent` and `HeroListComponent`. Generate the `CrisisList` and `HeroList` components. +The first configuration defines an array of two routes with minimal paths leading to the `CrisisListComponent` and `HeroListComponent`. + +Generate the `CrisisList` and `HeroList` components so that the router has something to render. ng generate component crisis-list @@ -899,40 +696,42 @@ Replace the contents of each component with the sample HTML below. -### Register Router and Routes +### Register `Router` and `Routes` -In order to use the Router, you must first register the `RouterModule` from the `@angular/router` package. Define an array of routes, `appRoutes`, and pass them to the `RouterModule.forRoot()` method. It returns a module, containing the configured `Router` service provider, plus other providers that the routing library requires. Once the application is bootstrapped, the `Router` performs the initial navigation based on the current browser URL. +In order to use the `Router`, you must first register the `RouterModule` from the `@angular/router` package. +Define an array of routes, `appRoutes`, and pass them to the `RouterModule.forRoot()` method. +The `RouterModule.forRoot()` method returns a module that containa the configured `Router` service provider, plus other providers that the routing library requires. +Once the application is bootstrapped, the `Router` performs the initial navigation based on the current browser URL.
- **Note:** The `RouterModule.forRoot` method is a pattern used to register application-wide providers. Read more about application-wide providers in the [Singleton services](guide/singleton-services#forRoot-router) guide. + **Note:** The `RouterModule.forRoot()` method is a pattern used to register application-wide providers. Read more about application-wide providers in the [Singleton services](guide/singleton-services#forRoot-router) guide.
-
-Adding the configured `RouterModule` to the `AppModule` is sufficient for simple route configurations. As the application grows, you'll want to [refactor the routing configuration](#refactor-the-routing-configuration-into-a-routing-module) into a separate file and create a **[Routing Module](#routing-module)**, a special type of `Service Module` dedicated to the purpose of routing in feature modules. +Adding the configured `RouterModule` to the `AppModule` is sufficient for minimal route configurations. +However, as the application grows, [refactor the routing configuration](#refactor-the-routing-configuration-into-a-routing-module) into a separate file and create a [Routing Module](#routing-module). +A routing module is a special type of `Service Module` dedicated to routing.
-Registering the `RouterModule.forRoot()` in the `AppModule` imports makes the `Router` service available everywhere in the application. +Registering the `RouterModule.forRoot()` in the `AppModule` `imports` array makes the `Router` service available everywhere in the application. {@a shell} - ### Add the Router Outlet -The root `AppComponent` is the application shell. It has a title, a navigation bar with two links, and a router outlet where the router swaps components on and off the page. Here's what you get: - +The root `AppComponent` is the application shell. It has a title, a navigation bar with two links, and a router outlet where the router renders components.
Shell
-The router outlet serves as a placeholder when the routed components will be rendered below it. +The router outlet serves as a placeholder where the routed components are rendered. {@a shell-template} @@ -944,29 +743,30 @@ The corresponding component template looks like this: ### Define a Wildcard route -You've created two routes in the app so far, one to `/crisis-center` and the other to `/heroes`. Any other URL causes the router to throw an error and crash the app. +You've created two routes in the app so far, one to `/crisis-center` and the other to `/heroes`. +Any other URL causes the router to throw an error and crash the app. -Add a **wildcard** route to intercept invalid URLs and handle them gracefully. -A _wildcard_ route has a path consisting of two asterisks. It matches _every_ URL. -The router will select _this_ route if it can't match a route earlier in the configuration. +Add a wildcard route to intercept invalid URLs and handle them gracefully. +A wildcard route has a path consisting of two asterisks. +It matches every URL. +Thus, the router selects this wildcard route if it can't match a route earlier in the configuration. A wildcard route can navigate to a custom "404 Not Found" component or [redirect](#redirect) to an existing route.
The router selects the route with a [_first match wins_](#example-config) strategy. -Wildcard routes are the least specific routes in the route configuration. -Be sure it is the _last_ route in the configuration. +Because a wildcard route is the least specific route, place it last in the route configuration.
-To test this feature, add a button with a `RouterLink` to the `HeroListComponent` template and set the link to `"/sidekicks"`. +To test this feature, add a button with a `RouterLink` to the `HeroListComponent` template and set the link to a non-existant route called `"/sidekicks"`. -The application will fail if the user clicks that button because you haven't defined a `"/sidekicks"` route yet. +The application fails if the user clicks that button because you haven't defined a `"/sidekicks"` route yet. -Instead of adding the `"/sidekicks"` route, define a `wildcard` route instead and have it navigate to a simple `PageNotFoundComponent`. +Instead of adding the `"/sidekicks"` route, define a `wildcard` route and have it navigate to a `PageNotFoundComponent`. @@ -985,21 +785,19 @@ The browser address bar continues to point to the invalid URL. ### Set up redirects -When the application launches, the initial URL in the browser bar is something like: +When the application launches, the initial URL in the browser bar is by default: localhost:4200 -That doesn't match any of the concrete configured routes which means -the router falls through to the wildcard route and displays the `PageNotFoundComponent`. +That doesn't match any of the hard-coded routes which means the router falls through to the wildcard route and displays the `PageNotFoundComponent`. -The application needs a **default route** to a valid page. +The application needs a default route to a valid page. The default page for this app is the list of heroes. The app should navigate there as if the user clicked the "Heroes" link or pasted `localhost:4200/heroes` into the address bar. -The preferred solution is to add a `redirect` route that translates the initial relative URL (`''`) -to the desired default path (`/heroes`). The browser address bar shows `.../heroes` as if you'd navigated there directly. +Add a `redirect` route that translates the initial relative URL (`''`) to the desired default path (`/heroes`). Add the default route somewhere _above_ the wildcard route. It's just above the wildcard route in the following excerpt showing the complete `appRoutes` for this milestone. @@ -1007,57 +805,51 @@ It's just above the wildcard route in the following excerpt showing the complete +The browser address bar shows `.../heroes` as if you'd navigated there directly. A redirect route requires a `pathMatch` property to tell the router how to match a URL to the path of a route. -The router throws an error if you don't. -In this app, the router should select the route to the `HeroListComponent` only when the *entire URL* matches `''`, -so set the `pathMatch` value to `'full'`. +In this app, the router should select the route to the `HeroListComponent` only when the *entire URL* matches `''`, so set the `pathMatch` value to `'full'`. +{@a pathmatch} -
+
+
Spotlight on pathMatch
-Technically, `pathMatch = 'full'` results in a route hit when the *remaining*, unmatched segments of the URL match `''`. -In this example, the redirect is in a top level route so the *remaining* URL and the *entire* URL are the same thing. + Technically, `pathMatch = 'full'` results in a route hit when the *remaining*, unmatched segments of the URL match `''`. + In this example, the redirect is in a top level route so the *remaining* URL and the *entire* URL are the same thing. -The other possible `pathMatch` value is `'prefix'` which tells the router -to match the redirect route when the *remaining* URL ***begins*** with the redirect route's _prefix_ path. + The other possible `pathMatch` value is `'prefix'` which tells the router to match the redirect route when the remaining URL begins with the redirect route's prefix path. + This doesn't apply to this sample app because if the `pathMatch` value were `'prefix'`, every URL would match `''`. -Don't do that here. -If the `pathMatch` value were `'prefix'`, _every_ URL would match `''`. + Try setting it to `'prefix'` and clicking the `Go to sidekicks` button. + Since that's a bad URL, you should see the "Page not found" page. + Instead, you're still on the "Heroes" page. + Enter a bad URL in the browser address bar. + You're instantly re-routed to `/heroes`. + Every URL, good or bad, that falls through to this route definition is a match. -Try setting it to `'prefix'` then click the `Go to sidekicks` button. -Remember that's a bad URL and you should see the "Page not found" page. -Instead, you're still on the "Heroes" page. -Enter a bad URL in the browser address bar. -You're instantly re-routed to `/heroes`. -_Every_ URL, good or bad, that falls through to _this_ route definition -will be a match. - -The default route should redirect to the `HeroListComponent` _only_ when the _entire_ url is `''`. -Remember to restore the redirect to `pathMatch = 'full'`. - -Learn more in Victor Savkin's -[post on redirects](http://vsavkin.tumblr.com/post/146722301646/angular-router-empty-paths-componentless-routes). + The default route should redirect to the `HeroListComponent` only when the entire url is `''`. + Remember to restore the redirect to `pathMatch = 'full'`. + Learn more in Victor Savkin's + [post on redirects](http://vsavkin.tumblr.com/post/146722301646/ angular-router-empty-paths-componentless-routes).
+### Milestone 1 wrap up -### Basics wrap up +Your sample app can switch between two views when the user clicks a link. -You've got a very basic navigating app, one that can switch between two views -when the user clicks a link. - -You've learned how to do the following: +Milestone 1 has covered how to do the following: * Load the router library. * Add a nav bar to the shell template with anchor tags, `routerLink` and `routerLinkActive` directives. -* Add a `router-outlet` to the shell template where views will be displayed. +* Add a `router-outlet` to the shell template where views are displayed. * Configure the router module with `RouterModule.forRoot()`. * Set the router to compose HTML5 browser URLs. -* handle invalid routes with a `wildcard` route. -* navigate to the default route when the app launches with an empty path. +* Handle invalid routes with a `wildcard` route. +* Navigate to the default route when the app launches with an empty path. The starter app's structure looks like this: @@ -1209,7 +1001,7 @@ The starter app's structure looks like this: -Here are the files discussed in this milestone. +Here are the files in this milestone. @@ -1245,26 +1037,23 @@ Here are the files discussed in this milestone. ## Milestone 2: *Routing module* -In the initial route configuration, you provided a simple setup with two routes used -to configure the application for routing. This is perfectly fine for simple routing. -As the application grows and you make use of more `Router` features, such as guards, -resolvers, and child routing, you'll naturally want to refactor the routing configuration into its own file. -We recommend moving the routing information into a special-purpose module called a *Routing Module*. +This milestone shows you how to configure a special-purpose module called a *Routing Module*, which holds your app's routing configuration. -The **Routing Module** has several characteristics: +The Routing Module has several characteristics: * Separates routing concerns from other application concerns. * Provides a module to replace or remove when testing the application. -* Provides a well-known location for routing service providers including guards and resolvers. -* Does **not** declare components. +* Provides a well-known location for routing service providers such as guards and resolvers. +* Does not declare components. {@a integrate-routing} ### Integrate routing with your app The sample routing application does not include routing by default. -When you use the [Angular CLI](cli) to create a project that will use routing, set the `--routing` option for the project or app, and for each NgModule. -When you create or initialize a new project (using the CLI [`ng new`](cli/new) command) or a new app (using the [`ng generate app`](cli/generate) command), specify the `--routing` option. This tells the CLI to include the `@angular/router` npm package and create a file named `app-routing.module.ts`. +When you use the [Angular CLI](cli) to create a project that does use routing, set the `--routing` option for the project or app, and for each NgModule. +When you create or initialize a new project (using the CLI [`ng new`](cli/new) command) or a new app (using the [`ng generate app`](cli/generate) command), specify the `--routing` option. +This tells the CLI to include the `@angular/router` npm package and create a file named `app-routing.module.ts`. You can then use routing in any NgModule that you add to the project or app. For example, the following command generates an NgModule that can use routing. @@ -1279,7 +1068,7 @@ The file includes an empty `Routes` object that you can fill with routes to diff {@a routing-refactor} -### Refactor the routing configuration into a _routing module_ +### Refactor the routing configuration into a routing module Create an `AppRouting` module in the `/app` folder to contain the routing configuration. @@ -1288,57 +1077,39 @@ Create an `AppRouting` module in the `/app` folder to contain the routing config Import the `CrisisListComponent`, `HeroListComponent`, and `PageNotFoundComponent` symbols -just like you did in the `app.module.ts`. Then move the `Router` imports -and routing configuration, including `RouterModule.forRoot()`, into this routing module. +just like you did in the `app.module.ts`. +Then move the `Router` imports and routing configuration, including `RouterModule.forRoot()`, into this routing module. Re-export the Angular `RouterModule` by adding it to the module `exports` array. -By re-exporting the `RouterModule` here the components declared in `AppModule` will have access to router directives such as `RouterLink` and `RouterOutlet`. +By re-exporting the `RouterModule` here, the components declared in `AppModule` have access to router directives such as `RouterLink` and `RouterOutlet`. After these steps, the file should look like this. -Next, update the `app.module.ts` file, removing `RouterModule.forRoot` in -the `imports` array. +Next, update the `app.module.ts` file by removing `RouterModule.forRoot` in the `imports` array. - -
- - -Later in this guide you will create [multiple routing modules](#heroes-functionality) and discover that -you must import those routing modules [in the correct order](#routing-module-order). - +Later, this guide shows you how to create [multiple routing modules](#heroes-functionality) and import those routing modules [in the correct order](#routing-module-order).
- - -The application continues to work just the same, and you can use `AppRoutingModule` as -the central place to maintain future routing configuration. - +The application continues to work just the same, and you can use `AppRoutingModule` as the central place to maintain future routing configuration. {@a why-routing-module} +### Benfits of a routing module -### Do you need a _Routing Module_? +The routing module, often called the `AppRoutingModule`, replaces the routing configuration in the root or feature module. -The _Routing Module_ *replaces* the routing configuration in the root or feature module. -_Either_ configure routes in the Routing Module _or_ within the module itself but not in both. +The routing module is helpful as your app growns and when the configuration includes specialized guard and resolver services. -The Routing Module is a design choice whose value is most obvious when the configuration is complex -and includes specialized guard and resolver services. -It can seem like overkill when the actual configuration is dead simple. +Some developers skip the routing module when the configuration is minimal and merge the routing configuration directly into the companion module (for example, `AppModule`). -Some developers skip the Routing Module (for example, `AppRoutingModule`) when the configuration is simple and -merge the routing configuration directly into the companion module (for example, `AppModule`). - -Choose one pattern or the other and follow that pattern consistently. - -Most developers should always implement a Routing Module for the sake of consistency. +Most apps should implement a routing module for consistency. It keeps the code clean when configuration becomes complex. It makes testing the feature module easier. Its existence calls attention to the fact that a module is routed. @@ -1348,56 +1119,44 @@ It is where developers expect to find and expand routing configuration. ## Milestone 3: Heroes feature -You've seen how to navigate using the `RouterLink` directive. -Now you'll learn the following: +This milestone covers the following: -* Organize the app and routes into *feature areas* using modules. -* Navigate imperatively from one component to another. -* Pass required and optional information in route parameters. +* Organizing the app and routes into feature areas using modules. +* Navigating imperatively from one component to another. +* Passing required and optional information in route parameters. -This example recreates the heroes feature in the "Services" episode of the -[Tour of Heroes tutorial](tutorial/toh-pt4 "Tour of Heroes: Services"), -and you'll be copying much of the code -from the . +This sample app recreates the heroes feature in the "Services" section of the [Tour of Heroes tutorial](tutorial/toh-pt4 "Tour of Heroes: Services"), and reuses much of the code from the . -Here's how the user will experience this version of the app: + + +A typical application has multiple feature areas, each dedicated to a particular business purpose with its own folder. - -A typical application has multiple *feature areas*, -each dedicated to a particular business purpose. - -While you could continue to add files to the `src/app/` folder, -that is unrealistic and ultimately not maintainable. -Most developers prefer to put each feature area in its own folder. - -You are about to break up the app into different *feature modules*, each with its own concerns. -Then you'll import into the main module and navigate among them. +This section shows you how refactor the app into different feature modules, import them into the main module and navigate among them. {@a heroes-functionality} - ### Add heroes functionality Follow these steps: -* Create a `HeroesModule` with routing in the heroes folder and register it with the root `AppModule`. This is where you'll be implementing the *hero management*. +* To manage the heroes, create a `HeroesModule` with routing in the heroes folder and register it with the root `AppModule`. ng generate module heroes/heroes --module app --flat --routing -* Move the placeholder `hero-list` folder that's in the `app` into the `heroes` folder. +* Move the placeholder `hero-list` folder that's in the `app` folder into the `heroes` folder. * Copy the contents of the `heroes/heroes.component.html` from the "Services" tutorial into the `hero-list.component.html` template. - * Relabel the `

` to `

HEROES

`. + * Re-label the `

` to `

HEROES

`. * Delete the `` component at the bottom of the template. * Copy the contents of the `heroes/heroes.component.css` from the live example into the `hero-list.component.css` file. @@ -1408,7 +1167,7 @@ Follow these steps:
- Selectors are **not required** for _routed components_ due to the components are dynamically inserted when the page is rendered, but are useful for identifying and targeting them in your HTML element tree. + Selectors are not required for routed components because components are dynamically inserted when the page is rendered. However, they are useful for identifying and targeting them in your HTML element tree.
@@ -1416,16 +1175,13 @@ Follow these steps: * Copy the `message.service.ts` into the `src/app` folder. * Update the relative path import to the `message.service` in the `hero.service.ts` file. -Next, you'll update the `HeroesModule` metadata. +Next, update the `HeroesModule` metadata. * Import and add the `HeroDetailComponent` and `HeroListComponent` to the `declarations` array in the `HeroesModule`. - - -When you're done, you'll have these *hero management* files: - +The hero management file structure is as follows:
@@ -1497,47 +1253,33 @@ When you're done, you'll have these *hero management* files:
- - -
- - {@a hero-routing-requirements} - -#### *Hero* feature routing requirements +#### Hero feature routing requirements The heroes feature has two interacting components, the hero list and the hero detail. -The list view is self-sufficient; you navigate to it, it gets a list of heroes and displays them. +When you navigate to list view, it gets a list of heroes and displays them. +When you click on a hero, the detail view has to display that particular hero. -The detail view is different. It displays a particular hero. It can't know which hero to show on its own. -That information must come from outside. - -When the user selects a hero from the list, the app should navigate to the detail view -and show that hero. You tell the detail view which hero to display by including the selected hero's id in the route URL. -Import the hero components from their new locations in the `src/app/heroes/` folder, define the two hero routes. +Import the hero components from their new locations in the `src/app/heroes/` folder and define the two hero routes. -Now that you have routes for the `Heroes` module, register them with the `Router` via the -`RouterModule` _almost_ as you did in the `AppRoutingModule`. +Now that you have routes for the `Heroes` module, register them with the `Router` via the `RouterModule` as you did in the `AppRoutingModule`, with an important difference. -There is a small but critical difference. -In the `AppRoutingModule`, you used the static **`RouterModule.forRoot()`** method to register the routes and application level service providers. -In a feature module you use the static **`forChild`** method. +In the `AppRoutingModule`, you used the static `RouterModule.forRoot()` method to register the routes and application level service providers. +In a feature module you use the static `forChild()` method.
- - Only call `RouterModule.forRoot()` in the root `AppRoutingModule` (or the `AppModule` if that's where you register top level application routes). -In any other module, you must call the **`RouterModule.forChild`** method to register additional routes. +In any other module, you must call the `RouterModule.forChild()` method to register additional routes.
@@ -1547,14 +1289,10 @@ The updated `HeroesRoutingModule` looks like this: -
- Consider giving each feature module its own route configuration file. -It may seem like overkill early when the feature routes are simple. -But routes have a tendency to grow more complex and consistency in patterns pays off over time. - +Though the feature routes are currently minimal, routes have a tendency to grow more complex even in small apps.
@@ -1564,7 +1302,7 @@ But routes have a tendency to grow more complex and consistency in patterns pays #### Remove duplicate hero routes -The hero routes are currently defined in _two_ places: in the `HeroesRoutingModule`, +The hero routes are currently defined in two places: in the `HeroesRoutingModule`, by way of the `HeroesModule`, and in the `AppRoutingModule`. Routes provided by feature modules are combined together into their imported module's routes by the router. @@ -1572,66 +1310,43 @@ This allows you to continue defining the feature module routes without modifying Remove the `HeroListComponent` import and the `/heroes` route from the `app-routing.module.ts`. -**Leave the default and the wildcard routes!** -These are concerns at the top level of the application itself. - +Leave the default and the wildcard routes as these are still in use at the top level of the application. - - {@a merge-hero-routes} - #### Remove heroes declarations -Remove the `HeroListComponent` from the `AppModule`'s `declarations` because it's now provided by the `HeroesModule`. You can evolve the hero feature with more components and different routes. That's a key benefit of creating a separate module for each feature area. +Because the `HeroesModule` now provides the `HeroListComponent`, remove it from the `AppModule`'s `declarations` array. +Now that you have a separate `HeroesModule`, you can evolve the hero feature with more components and different routes. After these steps, the `AppModule` should look like this: - - - {@a routing-module-order} +### Module import order -### Module import order matters - -Look at the module `imports` array. Notice that the `AppRoutingModule` is _last_. -Most importantly, it comes _after_ the `HeroesModule`. +Notice that in the module `imports` array, the `AppRoutingModule` is last and comes _after_ the `HeroesModule`. +The order of route configuration is important because the router accepts the first route that matches a navigation request path. -The order of route configuration matters. -The router accepts the first route that matches a navigation request path. +When all routes were in one `AppRoutingModule`, you put the default and [wildcard](#wildcard) routes last, after the `/heroes` route, so that the router had a chance to match a URL to the `/heroes` route _before_ hitting the wildcard route and navigating to "Page not found". -When all routes were in one `AppRoutingModule`, -you put the default and [wildcard](#wildcard) routes last, after the `/heroes` route, -so that the router had a chance to match a URL to the `/heroes` route _before_ -hitting the wildcard route and navigating to "Page not found". - -The routes are no longer in one file. -They are distributed across two modules, `AppRoutingModule` and `HeroesRoutingModule`. - -Each routing module augments the route configuration _in the order of import_. -If you list `AppRoutingModule` first, the wildcard route will be registered -_before_ the hero routes. -The wildcard route—which matches _every_ URL—will intercept the attempt to navigate to a hero route. +Each routing module augments the route configuration in the order of import. +If you listed `AppRoutingModule` first, the wildcard route would be registered _before_ the hero routes. +The wildcard route—which matches _every_ URL—would intercept the attempt to navigate to a hero route.
- - -Reverse the routing modules and see for yourself that -a click of the heroes link results in "Page not found". -Learn about inspecting the runtime router configuration -[below](#inspect-config "Inspect the router config"). - +Reverse the routing modules to see a click of the heroes link resulting in "Page not found". +Learn about inspecting the runtime router configuration [below](#inspect-config "Inspect the router config").
@@ -1639,22 +1354,17 @@ Learn about inspecting the runtime router configuration {@a route-def-with-parameter} - #### Route definition with a parameter Return to the `HeroesRoutingModule` and look at the route definitions again. -The route to `HeroDetailComponent` has a twist. - +The route to `HeroDetailComponent` has an `:id` token in the path. +The `:id` token creates a slot in the path for a Route Parameter. +In this case, this configuration causes the router to insert the `id` of a hero into that slot. - -Notice the `:id` token in the path. That creates a slot in the path for a **Route Parameter**. -In this case, the router will insert the `id` of a hero into that slot. - -If you tell the router to navigate to the detail component and display "Magneta", -you expect a hero id to appear in the browser URL like this: +If you tell the router to navigate to the detail component and display "Magneta", you expect a hero id to appear in the browser URL like this: @@ -1664,115 +1374,74 @@ you expect a hero id to appear in the browser URL like this: -If a user enters that URL into the browser address bar, the router should recognize the -pattern and go to the same "Magneta" detail view. +If a user enters that URL into the browser address bar, the router should recognize the pattern and go to the same "Magneta" detail view.
- -
Route parameter: Required or optional?
- - -Embedding the route parameter token, `:id`, -in the route definition path is a good choice for this scenario -because the `id` is *required* by the `HeroDetailComponent` and because -the value `15` in the path clearly distinguishes the route to "Magneta" from -a route for some other hero. - +Embedding the route parameter token, `:id`, in the route definition path is a good choice for this scenario because the `id` is *required* by the `HeroDetailComponent` and because the value `15` in the path clearly distinguishes the route to "Magneta" from a route for some other hero.
{@a route-parameters} - #### Setting the route parameters in the list view After navigating to the `HeroDetailComponent`, you expect to see the details of the selected hero. -You need *two* pieces of information: the routing path to the component and the hero's `id`. +You need two pieces of information: the routing path to the component and the hero's `id`. -Accordingly, the _link parameters array_ has *two* items: the routing _path_ and a _route parameter_ that specifies the +Accordingly, the _link parameters array_ has two items: the routing _path_ and a _route parameter_ that specifies the `id` of the selected hero. - - - -The router composes the destination URL from the array like this: -`localhost:4200/hero/15`. - - - -
- - - -How does the target `HeroDetailComponent` learn about that `id`? -Don't analyze the URL. Let the router do it. +The router composes the destination URL from the array like this: `localhost:4200/hero/15`. The router extracts the route parameter (`id:15`) from the URL and supplies it to the `HeroDetailComponent` via the `ActivatedRoute` service. -
+{@a activated-route-in-action} -{@a activated-route} - -### _Activated Route_ in action +### `Activated Route` in action Import the `Router`, `ActivatedRoute`, and `ParamMap` tokens from the router package. - - - Import the `switchMap` operator because you need it later to process the `Observable` route parameters. - - - {@a hero-detail-ctor} - -As usual, you write a constructor that asks Angular to inject services -that the component requires and reference them as private variables. - +Add the services as private variables to the constructor so that Angular injects them (makes them visible to the component). -Later, in the `ngOnInit` method, you use the `ActivatedRoute` service to retrieve the parameters for the route, -pull the hero `id` from the parameters and retrieve the hero to display. +In the `ngOnInit()` method, use the `ActivatedRoute` service to retrieve the parameters for the route, pull the hero `id` from the parameters, and retrieve the hero to display. -The `paramMap` processing is a bit tricky. When the map changes, you `get()` -the `id` parameter from the changed parameters. +When the map changes, `paramMap` gets the `id` parameter from the changed parameters. Then you tell the `HeroService` to fetch the hero with that `id` and return the result of the `HeroService` request. -You might think to use the RxJS `map` operator. -But the `HeroService` returns an `Observable`. -So you flatten the `Observable` with the `switchMap` operator instead. +The `switchMap` operator does two things. It flattens the `Observable` that `HeroService` returns and cancels previous pending requests. +If the user re-navigates to this route with a new `id` while the `HeroService` is still retrieving the old `id`, `switchMap` discards that old request and returns the hero for the new `id`. -The `switchMap` operator also cancels previous in-flight requests. If the user re-navigates to this route -with a new `id` while the `HeroService` is still retrieving the old `id`, `switchMap` discards that old request and returns the hero for the new `id`. - -The observable `Subscription` will be handled by the `AsyncPipe` and the component's `hero` property will be (re)set with the retrieved hero. +`AsyncPipe` handles the observable subscription and the component's `hero` property will be (re)set with the retrieved hero. #### _ParamMap_ API -The `ParamMap` API is inspired by the [URLSearchParams interface](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams). It provides methods -to handle parameter access for both route parameters (`paramMap`) and query parameters (`queryParamMap`). +The `ParamMap` API is inspired by the [URLSearchParams interface](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams). +It provides methods to handle parameter access for both route parameters (`paramMap`) and query parameters (`queryParamMap`). @@ -1837,88 +1506,60 @@ to handle parameter access for both route parameters (`paramMap`) and query para In this example, you retrieve the route parameter map from an `Observable`. That implies that the route parameter map can change during the lifetime of this component. -They might. By default, the router re-uses a component instance when it re-navigates to the same component type +By default, the router re-uses a component instance when it re-navigates to the same component type without visiting a different component first. The route parameters could change each time. Suppose a parent component navigation bar had "forward" and "back" buttons that scrolled through the list of heroes. Each click navigated imperatively to the `HeroDetailComponent` with the next or previous `id`. -You don't want the router to remove the current `HeroDetailComponent` instance from the DOM only to re-create it for the next `id`. -That could be visibly jarring. -Better to simply re-use the same component instance and update the parameter. +You wouldn't want the router to remove the current `HeroDetailComponent` instance from the DOM only to re-create it for the next `id` as this would re-render the view. +For better UX, the router re-uses the same component instance and updates the parameter. -Unfortunately, `ngOnInit` is only called once per component instantiation. -You need a way to detect when the route parameters change from _within the same instance_. -The observable `paramMap` property handles that beautifully. +Since `ngOnInit()` is only called once per component instantiation, you can detect when the route parameters change from _within the same instance_ using the observable `paramMap` property.
+When subscribing to an observable in a component, you almost always unsubscribe when the component is destroyed. - -When subscribing to an observable in a component, you almost always arrange to unsubscribe when the component is destroyed. - -There are a few exceptional observables where this is not necessary. -The `ActivatedRoute` observables are among the exceptions. - -The `ActivatedRoute` and its observables are insulated from the `Router` itself. -The `Router` destroys a routed component when it is no longer needed and the injected `ActivatedRoute` dies with it. - -Feel free to unsubscribe anyway. It is harmless and never a bad practice. - +However, `ActivatedRoute` observables are among the exceptions because `ActivatedRoute` and its observables are insulated from the `Router` itself. +The `Router` destroys a routed component when it is no longer needed along with the injected `ActivatedRoute`.
- - {@a snapshot} +#### `snapshot`: the no-observable alternative -#### _Snapshot_: the _no-observable_ alternative -_This_ application won't re-use the `HeroDetailComponent`. +This application won't re-use the `HeroDetailComponent`. The user always returns to the hero list to select another hero to view. -There's no way to navigate from one hero detail to another hero detail -without visiting the list component in between. +There's no way to navigate from one hero detail to another hero detail without visiting the list component in between. Therefore, the router creates a new `HeroDetailComponent` instance every time. -When you know for certain that a `HeroDetailComponent` instance will *never, never, ever* -be re-used, you can simplify the code with the *snapshot*. - -The `route.snapshot` provides the initial value of the route parameter map. -You can access the parameters directly without subscribing or adding observable operators. -It's much simpler to write and read: +When you know for certain that a `HeroDetailComponent` instance will never be re-used, you can use `snapshot`. +`route.snapshot` provides the initial value of the route parameter map. +You can access the parameters directly without subscribing or adding observable operators as in the following: - -
- - -**Remember:** you only get the _initial_ value of the parameter map with this technique. -Stick with the observable `paramMap` approach if there's even a chance that the router -could re-use the component. -This sample stays with the observable `paramMap` strategy just in case. - +`snapshot` only gets the initial value of the parameter map with this technique. +Use the observable `paramMap` approach if there's a possibility that the router could re-use the component. +This tutorial sample app uses with the observable `paramMap`.
- - {@a nav-to-list} - ### Navigating back to the list component -The `HeroDetailComponent` has a "Back" button wired to its `gotoHeroes` method that navigates imperatively -back to the `HeroListComponent`. +The `HeroDetailComponent` "Back" button uses the `gotoHeroes()` method that navigates imperatively back to the `HeroListComponent`. -The router `navigate` method takes the same one-item _link parameters array_ -that you can bind to a `[routerLink]` directive. -It holds the _path to the `HeroListComponent`_: +The router `navigate()` method takes the same one-item _link parameters array_ that you can bind to a `[routerLink]` directive. +It holds the path to the `HeroListComponent`: @@ -1928,8 +1569,8 @@ It holds the _path to the `HeroListComponent`_: #### Route Parameters: Required or optional? -Use [*route parameters*](#route-parameters) to specify a *required* parameter value *within* the route URL -as you do when navigating to the `HeroDetailComponent` in order to view the hero with *id* 15: +Use [route parameters](#route-parameters) to specify a required parameter value within the route URL +as you do when navigating to the `HeroDetailComponent` in order to view the hero with `id` 15: @@ -1939,148 +1580,94 @@ as you do when navigating to the `HeroDetailComponent` in order to view the hero -You can also add *optional* information to a route request. -For example, when returning to the hero-detail.component.ts list from the hero detail view, -it would be nice if the viewed hero was preselected in the list. - +You can also add optional information to a route request. +For example, when returning to the `hero-detail.component.ts` list from the hero detail view, it would be nice if the viewed hero were preselected in the list.
Selected hero
+You implement this feature by including the viewed hero's `id` in the URL as an optional parameter when returning from the `HeroDetailComponent`. +Optional information can also include other forms such as: -You'll implement this feature in a moment by including the viewed hero's `id` -in the URL as an optional parameter when returning from the `HeroDetailComponent`. - -Optional information takes other forms. Search criteria are often loosely structured, e.g., `name='wind*'`. -Multiple values are common—`after='12/31/2015' & before='1/1/2017'`—in no +* Loosely structured search criteria; for example, `name='wind*'`. +* Multiple values; for example, `after='12/31/2015' & before='1/1/2017'`—in no particular order—`before='1/1/2017' & after='12/31/2015'`— in a variety of formats—`during='currentYear'`. -These kinds of parameters don't fit easily in a URL *path*. Even if you could define a suitable URL token scheme, -doing so greatly complicates the pattern matching required to translate an incoming URL to a named route. - -Optional parameters are the ideal vehicle for conveying arbitrarily complex information during navigation. +As these kinds of parameters don't fit easily in a URL path, you can use optional parameters for conveying arbitrarily complex information during navigation. Optional parameters aren't involved in pattern matching and afford flexibility of expression. The router supports navigation with optional parameters as well as required route parameters. -Define _optional_ parameters in a separate object _after_ you define the required route parameters. - -In general, prefer a *required route parameter* when -the value is mandatory (for example, if necessary to distinguish one route path from another); -prefer an *optional parameter* when the value is optional, complex, and/or multivariate. +Define optional parameters in a separate object _after_ you define the required route parameters. +In general, use a required route parameter when the value is mandatory (for example, if necessary to distinguish one route path from another); and an optional parameter when the value is optional, complex, and/or multivariate. {@a optionally-selecting} - #### Heroes list: optionally selecting a hero -When navigating to the `HeroDetailComponent` you specified the _required_ `id` of the hero-to-edit in the -*route parameter* and made it the second item of the [_link parameters array_](#link-parameters-array). - +When navigating to the `HeroDetailComponent` you specified the required `id` of the hero-to-edit in the +route parameter and made it the second item of the [_link parameters array_](#link-parameters-array). - - -The router embedded the `id` value in the navigation URL because you had defined it -as a route parameter with an `:id` placeholder token in the route `path`: - +The router embedded the `id` value in the navigation URL because you had defined it as a route parameter with an `:id` placeholder token in the route `path`: - - When the user clicks the back button, the `HeroDetailComponent` constructs another _link parameters array_ which it uses to navigate back to the `HeroListComponent`. - +This array lacks a route parameter because previously you didn't need to send information to the `HeroListComponent`. - -This array lacks a route parameter because you had no reason to send information to the `HeroListComponent`. - -Now you have a reason. You'd like to send the id of the current hero with the navigation request so that the +Now, send the `id` of the current hero with the navigation request so that the `HeroListComponent` can highlight that hero in its list. -This is a _nice-to-have_ feature; the list will display perfectly well without it. -Send the `id` with an object that contains an _optional_ `id` parameter. +Send the `id` with an object that contains an optional `id` parameter. For demonstration purposes, there's an extra junk parameter (`foo`) in the object that the `HeroListComponent` should ignore. Here's the revised navigation statement: - - - The application still works. Clicking "back" returns to the hero list view. Look at the browser address bar. - It should look something like this, depending on where you run it: - localhost:4200/heroes;id=15;foo=foo - - The `id` value appears in the URL as (`;id=15;foo=foo`), not in the URL path. The path for the "Heroes" route doesn't have an `:id` token. The optional route parameters are not separated by "?" and "&" as they would be in the URL query string. -They are **separated by semicolons ";"** -This is *matrix URL* notation—something you may not have seen before. - +They are separated by semicolons ";". +This is matrix URL notation.
+Matrix URL notation is an idea first introduced in a [1996 proposal](http://www.w3.org/DesignIssues/MatrixURIs.html) by the founder of the web, Tim Berners-Lee. - -*Matrix URL* notation is an idea first introduced -in a [1996 proposal](http://www.w3.org/DesignIssues/MatrixURIs.html) by the founder of the web, Tim Berners-Lee. - -Although matrix notation never made it into the HTML standard, it is legal and -it became popular among browser routing systems as a way to isolate parameters -belonging to parent and child routes. The Router is such a system and provides -support for the matrix notation across browsers. - -The syntax may seem strange to you but users are unlikely to notice or care -as long as the URL can be emailed and pasted into a browser address bar -as this one can. +Although matrix notation never made it into the HTML standard, it is legal and it became popular among browser routing systems as a way to isolate parameters belonging to parent and child routes. +As such, the Router provides support for the matrix notation across browsers.
- - {@a route-parameters-activated-route} +### Route parameters in the `ActivatedRoute` service -### Route parameters in the *ActivatedRoute* service +In its current state of development, the list of heroes is unchanged. +No hero row is highlighted. -The list of heroes is unchanged. No hero row is highlighted. - - -
- - - -The *does* highlight the selected -row because it demonstrates the final state of the application which includes the steps you're *about* to cover. -At the moment this guide is describing the state of affairs *prior* to those steps. - -
- - - -The `HeroListComponent` isn't expecting any parameters at all and wouldn't know what to do with them. -You can change that. +The `HeroListComponent` needs code that expects parameters. Previously, when navigating from the `HeroListComponent` to the `HeroDetailComponent`, you subscribed to the route parameter map `Observable` and made it available to the `HeroDetailComponent` @@ -2089,125 +1676,101 @@ You injected that service in the constructor of the `HeroDetailComponent`. This time you'll be navigating in the opposite direction, from the `HeroDetailComponent` to the `HeroListComponent`. -First you extend the router import statement to include the `ActivatedRoute` service symbol: - +First, extend the router import statement to include the `ActivatedRoute` service symbol: - - Import the `switchMap` operator to perform an operation on the `Observable` of route parameter map. - - - -Then you inject the `ActivatedRoute` in the `HeroListComponent` constructor. - +Inject the `ActivatedRoute` in the `HeroListComponent` constructor. - - -The `ActivatedRoute.paramMap` property is an `Observable` map of route parameters. The `paramMap` emits a new map of values that includes `id` -when the user navigates to the component. In `ngOnInit` you subscribe to those values, set the `selectedId`, and get the heroes. - +The `ActivatedRoute.paramMap` property is an `Observable` map of route parameters. +The `paramMap` emits a new map of values that includes `id` when the user navigates to the component. +In `ngOnInit()` you subscribe to those values, set the `selectedId`, and get the heroes. Update the template with a [class binding](guide/template-syntax#class-binding). The binding adds the `selected` CSS class when the comparison returns `true` and removes it when `false`. Look for it within the repeated `
  • ` tag as shown here: - Add some styles to apply when the list item is selected. - - When the user navigates from the heroes list to the "Magneta" hero and back, "Magneta" appears selected:
    Selected List
    - - -The optional `foo` route parameter is harmless and continues to be ignored. - -### Adding routable animations +The optional `foo` route parameter is harmless and the router continues to ignore it. {@a route-animation} - -#### Adding animations to the routed component -The heroes feature module is almost complete, but what is a feature without some smooth transitions? +### Adding routable animations This section shows you how to add some [animations](guide/animations) to the `HeroDetailComponent`. -First import the `BrowserAnimationsModule` and add it to the `imports` array: +First, import the `BrowserAnimationsModule` and add it to the `imports` array: -Next, add a `data` object to the routes for `HeroListComponent` and `HeroDetailComponent`. Transitions are based on `states` and you'll use the `animation` data from the route to provide a named animation `state` for the transitions. +Next, add a `data` object to the routes for `HeroListComponent` and `HeroDetailComponent`. +Transitions are based on `states` and you use the `animation` data from the route to provide a named animation `state` for the transitions. - Create an `animations.ts` file in the root `src/app/` folder. The contents look like this: - This file does the following: * Imports the animation symbols that build the animation triggers, control state, and manage transitions between states. -* Exports a constant named `slideInAnimation` set to an animation trigger named *`routeAnimation`*; +* Exports a constant named `slideInAnimation` set to an animation trigger named `routeAnimation`. -* Defines one *transition* when switching back and forth from the `heroes` and `hero` routes to ease the component in from the left of the screen as it enters the application view (`:enter`), the other to animate the component to the right as it leaves the application view (`:leave`). +* Defines one transition when switching back and forth from the `heroes` and `hero` routes to ease the component in from the left of the screen as it enters the application view (`:enter`), the other to animate the component to the right as it leaves the application view (`:leave`). -You could also create more transitions for other routes. This trigger is sufficient for the current milestone. +Back in the `AppComponent`, import the `RouterOutlet` token from the `@angular/router` package and the `slideInAnimation` from `'./animations.ts`. -Back in the `AppComponent`, import the `RouterOutlet` token from the `@angular/router` package and the `slideInAnimation` from -`'./animations.ts`. - -Add an `animations` array to the `@Component` metadata's that contains the `slideInAnimation`. +Add an `animations` array to the `@Component` metadata that contains the `slideInAnimation`. -In order to use the routable animations, you'll need to wrap the `RouterOutlet` inside an element. You'll -use the `@routeAnimation` trigger and bind it to the element. +In order to use the routable animations, wrap the `RouterOutlet` inside an element, use the `@routeAnimation` trigger, and bind it to the element. -For the `@routeAnimation` transitions to key off states, you'll need to provide it with the `data` from the `ActivatedRoute`. The `RouterOutlet` is exposed as an `outlet` template variable, so you bind a reference to the router outlet. A variable of `routerOutlet` is an ideal choice. +For the `@routeAnimation` transitions to key off states, provide it with the `data` from the `ActivatedRoute`. +The `RouterOutlet` is exposed as an `outlet` template variable, so you bind a reference to the router outlet. +This example uses a variable of `routerOutlet`. -The `@routeAnimation` property is bound to the `getAnimationData` with the provided `routerOutlet` reference, so you'll need to define that function in the `AppComponent`. The `getAnimationData` function returns the animation property from the `data` provided through the `ActivatedRoute`. The `animation` property matches the `transition` names you used in the `slideInAnimation` defined in `animations.ts`. +The `@routeAnimation` property is bound to the `getAnimationData()` with the provided `routerOutlet` reference, so the next step is to define that function in the `AppComponent`. +The `getAnimationData()` function returns the animation property from the `data` provided through the `ActivatedRoute`. The `animation` property matches the `transition` names you used in the `slideInAnimation` defined in `animations.ts`. -When switching between the two routes, the `HeroDetailComponent` and `HeroListComponent` will ease in from the left when routed to and will slide to the right when navigating away. - - +When switching between the two routes, the `HeroDetailComponent` and `HeroListComponent` now ease in from the left when routed to and will slide to the right when navigating away. {@a milestone-3-wrap-up} - ### Milestone 3 wrap up -You've learned how to do the following: +This section has covered the following: -* Organize the app into *feature areas*. -* Navigate imperatively from one component to another. -* Pass information along in route parameters and subscribe to them in the component. -* Import the feature area NgModule into the `AppModule`. +* Organizing the app into feature areas. +* Navigating imperatively from one component to another. +* Passing information along in route parameters and subscribe to them in the component. +* Importing the feature area NgModule into the `AppModule`. * Applying routable animations based on the page. -After these changes, the folder structure looks like this: - +After these changes, the folder structure is as follows:
    @@ -2473,46 +2036,33 @@ Here are the relevant files for this version of the sample application. ## Milestone 4: Crisis center feature -It's time to add real features to the app's current placeholder crisis center. +This section shows you how to add child routes and use relative routing in your app. -Begin by imitating the heroes feature: +To add more features to the app's current crisis center, take similar steps as for the heroes feature: * Create a `crisis-center` subfolder in the `src/app` folder. * Copy the files and folders from `app/heroes` into the new `crisis-center` folder. * In the new files, change every mention of "hero" to "crisis", and "heroes" to "crises". * Rename the NgModule files to `crisis-center.module.ts` and `crisis-center-routing.module.ts`. -You'll use mock crises instead of mock heroes: - +Use mock crises instead of mock heroes: - -The resulting crisis center is a foundation for introducing a new concept—**child routing**. -You can leave *Heroes* in its current state as a contrast with the *Crisis Center* -and decide later if the differences are worthwhile. - +The resulting crisis center is a foundation for introducing a new concept—child routing. +You can leave Heroes in its current state as a contrast with the Crisis Center.
    - - -In keeping with the -*Separation of Concerns* principle, -changes to the *Crisis Center* won't affect the `AppModule` or -any other feature's component. +In keeping with the Separation of Concerns principle, changes to the Crisis Center don't affect the `AppModule` or any other feature's component.
    - - {@a crisis-child-routes} - ### A crisis center with child routes -This section shows you how to organize the crisis center -to conform to the following recommended pattern for Angular applications: +This section shows you how to organize the crisis center to conform to the following recommended pattern for Angular applications: * Each feature area resides in its own folder. * Each feature has its own Angular feature module. @@ -2540,25 +2090,19 @@ Generate a `CrisisCenter` component in the `crisis-center` folder: ng generate component crisis-center/crisis-center -Update the component template to look like this: +Update the component template with the following markup: The `CrisisCenterComponent` has the following in common with the `AppComponent`: -* It is the *root* of the crisis center area, -just as `AppComponent` is the root of the entire application. -* It is a *shell* for the crisis management feature area, -just as the `AppComponent` is a shell to manage the high-level workflow. - -Like most shells, the `CrisisCenterComponent` class is very simple, simpler even than `AppComponent`: -it has no business logic, and its template has no links, just a title and -`` for the crisis center child component. +* It is the root of the crisis center area, just as `AppComponent` is the root of the entire application. +* It is a shell for the crisis management feature area, just as the `AppComponent` is a shell to manage the high-level workflow. +Like most shells, the `CrisisCenterComponent` class is minimal because it has no business logic, and its template has no links, just a title and `` for the crisis center child component. {@a child-route-config} - ### Child route configuration As a host page for the "Crisis Center" feature, generate a `CrisisCenterHome` component in the `crisis-center` folder. @@ -2572,34 +2116,30 @@ Update the template with a welcome message to the `Crisis Center`. Update the `crisis-center-routing.module.ts` you renamed after copying it from `heroes-routing.module.ts` file. -This time, you define **child routes** *within* the parent `crisis-center` route. +This time, you define child routes within the parent `crisis-center` route. - -Notice that the parent `crisis-center` route has a `children` property -with a single route containing the `CrisisListComponent`. The `CrisisListComponent` route -also has a `children` array with two routes. +Notice that the parent `crisis-center` route has a `children` property with a single route containing the `CrisisListComponent`. +The `CrisisListComponent` route also has a `children` array with two routes. These two routes navigate to the crisis center child components, `CrisisCenterHomeComponent` and `CrisisDetailComponent`, respectively. -There are *important differences* in the way the router treats these _child routes_. +There are important differences in the way the router treats child routes. -The router displays the components of these routes in the `RouterOutlet` -of the `CrisisCenterComponent`, not in the `RouterOutlet` of the `AppComponent` shell. +The router displays the components of these routes in the `RouterOutlet` of the `CrisisCenterComponent`, not in the `RouterOutlet` of the `AppComponent` shell. -The `CrisisListComponent` contains the crisis list and a `RouterOutlet` to -display the `Crisis Center Home` and `Crisis Detail` route components. +The `CrisisListComponent` contains the crisis list and a `RouterOutlet` to display the `Crisis Center Home` and `Crisis Detail` route components. -The `Crisis Detail` route is a child of the `Crisis List`. The router [reuses components](#reuse) -by default, so the `Crisis Detail` component will be re-used as you select different crises. +The `Crisis Detail` route is a child of the `Crisis List`. +The router [reuses components](#reuse) by default, so the `Crisis Detail` component will be re-used as you select different crises. In contrast, back in the `Hero Detail` route, [the component was recreated](#snapshot-the-no-observable-alternative) each time you selected a different hero from the list of heroes. At the top level, paths that begin with `/` refer to the root of the application. -But child routes *extend* the path of the parent route. +But child routes extend the path of the parent route. With each step down the route tree, -you add a slash followed by the route path, unless the path is _empty_. +you add a slash followed by the route path, unless the path is empty. Apply that logic to navigation within the crisis center for which the parent path is `/crisis-center`. @@ -2608,26 +2148,20 @@ Apply that logic to navigation within the crisis center for which the parent pat * To navigate to the `CrisisDetailComponent` for a crisis with `id=2`, the full URL is `/crisis-center/2` (`/crisis-center` + `''` + `'/2'`). -The absolute URL for the latter example, including the `localhost` origin, is +The absolute URL for the latter example, including the `localhost` origin, is as follows: localhost:4200/crisis-center/2 - - Here's the complete `crisis-center-routing.module.ts` file with its imports. - - - {@a import-crisis-module} - -### Import crisis center module into the *AppModule* routes +### Import crisis center module into the `AppModule` routes As with the `HeroesModule`, you must add the `CrisisCenterModule` to the `imports` array of the `AppModule` _before_ the `AppRoutingModule`: @@ -2644,41 +2178,29 @@ _before_ the `AppRoutingModule`: -Remove the initial crisis center route from the `app-routing.module.ts`. -The feature routes are now provided by the `HeroesModule` and the `CrisisCenter` modules. +Remove the initial crisis center route from the `app-routing.module.ts` because now the `HeroesModule` and the `CrisisCenter` modules provide teh feature routes. The `app-routing.module.ts` file retains the top-level application routes such as the default and wildcard routes. - - - - {@a relative-navigation} - ### Relative navigation While building out the crisis center feature, you navigated to the -crisis detail route using an **absolute path** that begins with a _slash_. +crisis detail route using an absolute path that begins with a slash. -The router matches such _absolute_ paths to routes starting from the top of the route configuration. +The router matches such absolute paths to routes starting from the top of the route configuration. -You could continue to use absolute paths like this to navigate inside the *Crisis Center* -feature, but that pins the links to the parent routing structure. +You could continue to use absolute paths like this to navigate inside the Crisis Center feature, but that pins the links to the parent routing structure. If you changed the parent `/crisis-center` path, you would have to change the link parameters array. -You can free the links from this dependency by defining paths that are **relative** to the current URL segment. -Navigation _within_ the feature area remains intact even if you change the parent route path to the feature. - -Here's an example: - +You can free the links from this dependency by defining paths that are relative to the current URL segment. +Navigation within the feature area remains intact even if you change the parent route path to the feature.
    - - The router supports directory-like syntax in a _link parameters list_ to help guide route name lookup: `./` or `no leading slash` is relative to the current level. @@ -2689,55 +2211,38 @@ You can combine relative navigation syntax with an ancestor path. If you must navigate to a sibling route, you could use the `../` convention to go up one level, then over and down the sibling route path. -
    - - To navigate a relative path with the `Router.navigate` method, you must supply the `ActivatedRoute` to give the router knowledge of where you are in the current route tree. After the _link parameters array_, add an object with a `relativeTo` property set to the `ActivatedRoute`. The router then calculates the target URL based on the active route's location. -
    - - -**Always** specify the complete _absolute_ path when calling router's `navigateByUrl` method. - +Always specify the complete absolute path when calling router's `navigateByUrl()` method.
    - - {@a nav-to-crisis} - ### Navigate to crisis list with a relative URL You've already injected the `ActivatedRoute` that you need to compose the relative navigation path. -When using a `RouterLink` to navigate instead of the `Router` service, you'd use the _same_ -link parameters array, but you wouldn't provide the object with the `relativeTo` property. +When using a `RouterLink` to navigate instead of the `Router` service, you'd use the same link parameters array, but you wouldn't provide the object with the `relativeTo` property. The `ActivatedRoute` is implicit in a `RouterLink` directive. - -Update the `gotoCrises` method of the `CrisisDetailComponent` to navigate back to the *Crisis Center* list using relative path navigation. - +Update the `gotoCrises()` method of the `CrisisDetailComponent` to navigate back to the Crisis Center list using relative path navigation. - Notice that the path goes up a level using the `../` syntax. If the current crisis `id` is `3`, the resulting path back to the crisis list is `/crisis-center/;id=3;foo=foo`. - {@a named-outlets} - - ### Displaying multiple routes in named outlets You decide to give users a way to contact the crisis center. @@ -2747,27 +2252,21 @@ The popup should stay open, even when switching between pages in the application by sending the message or canceling. Clearly you can't put the popup in the same outlet as the other pages. -Until now, you've defined a single outlet and you've nested child routes -under that outlet to group routes together. -The router only supports one primary _unnamed_ outlet per template. +Until now, you've defined a single outlet and you've nested child routes under that outlet to group routes together. +The router only supports one primary unnamed outlet per template. -A template can also have any number of _named_ outlets. +A template can also have any number of named outlets. Each named outlet has its own set of routes with their own components. -Multiple outlets can be displaying different content, determined by different routes, all at the same time. +Multiple outlets can display different content, determined by different routes, all at the same time. Add an outlet named "popup" in the `AppComponent`, directly below the unnamed outlet. - - - That's where a popup will go, once you learn how to route a popup component to it. - {@a secondary-routes} - #### Secondary routes Named outlets are the targets of _secondary routes_. @@ -2785,19 +2284,15 @@ Generate a new component to compose the message. ng generate component compose-message -It displays a simple form with a header, an input box for the message, +It displays a short form with a header, an input box for the message, and two buttons, "Send" and "Cancel". -
    Contact popup
    - - Here's the component, its template and styles: - @@ -2814,86 +2309,59 @@ Here's the component, its template and styles: - - -It looks about the same as any other component you've seen in this guide. -There are two noteworthy differences. +It looks similar to any other component in this guide, but there are two key differences. Note that the `send()` method simulates latency by waiting a second before "sending" the message and closing the popup. -The `closePopup()` method closes the popup view by navigating to the popup outlet with a `null`. -That's a peculiarity covered [below](#clear-secondary-routes). - +The `closePopup()` method closes the popup view by navigating to the popup outlet with a `null` which the section on [clearing secondary routes](#clear-secondary-routes) covers. {@a add-secondary-route} - #### Add a secondary route Open the `AppRoutingModule` and add a new `compose` route to the `appRoutes`. - - -The `path` and `component` properties should be familiar. -There's a new property, `outlet`, set to `'popup'`. +In addition to the `path` and `component` properties, there's a new property called `outlet`, which is set to `'popup'`. This route now targets the popup outlet and the `ComposeMessageComponent` will display there. -The user needs a way to open the popup. -Open the `AppComponent` and add a "Contact" link. +To give users a way to open the popup, add a "Contact" link to the `AppComponent` template. - - -Although the `compose` route is pinned to the "popup" outlet, that's not sufficient for wiring the route to a `RouterLink` directive. +Although the `compose` route is configured to the "popup" outlet, that's not sufficient for connecting the route to a `RouterLink` directive. You have to specify the named outlet in a _link parameters array_ and bind it to the `RouterLink` with a property binding. -The _link parameters array_ contains an object with a single `outlets` property whose value -is another object keyed by one (or more) outlet names. +The _link parameters array_ contains an object with a single `outlets` property whose value is another object keyed by one (or more) outlet names. In this case there is only the "popup" outlet property and its value is another _link parameters array_ that specifies the `compose` route. -You are in effect saying, _when the user clicks this link, display the component associated with the `compose` route in the `popup` outlet_. - +In other words, when the user clicks this link, the router displays the component associated with the `compose` route in the `popup` outlet.
    +This `outlets` object within an outer object was unnecessary when there was only one route and one unnamed outlet. +The router assumed that your route specification targeted the unnamed primary outlet and created these objects for you. -This `outlets` object within an outer object was completely unnecessary -when there was only one route and one _unnamed_ outlet to think about. - -The router assumed that your route specification targeted the _unnamed_ primary outlet -and created these objects for you. - -Routing to a named outlet has revealed a previously hidden router truth: +Routing to a named outlet has revealed a router feature: you can target multiple outlets with multiple routes in the same `RouterLink` directive. -You're not actually doing that here. -But to target a named outlet, you must use the richer, more verbose syntax. - -
    - - {@a secondary-route-navigation} - #### Secondary route navigation: merging routes during navigation + Navigate to the _Crisis Center_ and click "Contact". you should see something like the following URL in the browser address bar. - http://.../crisis-center(popup:compose) - - -The interesting part of the URL follows the `...`: +The relevant part of the URL follows the `...`: * The `crisis-center` is the primary navigation. * Parentheses surround the secondary route. @@ -2901,70 +2369,59 @@ The interesting part of the URL follows the `...`: Click the _Heroes_ link and look at the URL again. - http://.../heroes(popup:compose) - - The primary navigation part has changed; the secondary route is the same. The router is keeping track of two separate branches in a navigation tree and generating a representation of that tree in the URL. -You can add many more outlets and routes, at the top level and in nested levels, creating a navigation tree with many branches. -The router will generate the URL to go with it. - -You can tell the router to navigate an entire tree at once by filling out the `outlets` object mentioned above. -Then pass that object inside a _link parameters array_ to the `router.navigate` method. - -Experiment with these possibilities at your leisure. - +You can add many more outlets and routes, at the top level and in nested levels, creating a navigation tree with many branches and the router will generate the URLs to go with it. +You can tell the router to navigate an entire tree at once by filling out the `outlets` object and then pass that object inside a _link parameters array_ to the `router.navigate` method. {@a clear-secondary-routes} - #### Clearing secondary routes -As you've learned, a component in an outlet persists until you navigate away to a new component. -Secondary outlets are no different in this regard. + +Like regular outlets, secondary outlets persists until you navigate away to a new component. Each secondary outlet has its own navigation, independent of the navigation driving the primary outlet. Changing a current route that displays in the primary outlet has no effect on the popup outlet. That's why the popup stays visible as you navigate among the crises and heroes. -Clicking the "send" or "cancel" buttons _does_ clear the popup view. -To see how, look at the `closePopup()` method again: +The `closePopup()` method again: +Clicking the "send" or "cancel" buttons clears the popup view. +The `closePopup()` function navigates imperatively with the `Router.navigate()` method, passing in a [link parameters array](#link-parameters-array). - -It navigates imperatively with the `Router.navigate()` method, passing in a [link parameters array](#link-parameters-array). - -Like the array bound to the _Contact_ `RouterLink` in the `AppComponent`, -this one includes an object with an `outlets` property. +Like the array bound to the _Contact_ `RouterLink` in the `AppComponent`, this one includes an object with an `outlets` property. The `outlets` property value is another object with outlet names for keys. The only named outlet is `'popup'`. -This time, the value of `'popup'` is `null`. That's not a route, but it is a legitimate value. -Setting the popup `RouterOutlet` to `null` clears the outlet and removes -the secondary popup route from the current URL. +This time, the value of `'popup'` is `null`. +That's not a route, but it is a legitimate value. +Setting the popup `RouterOutlet` to `null` clears the outlet and removes the secondary popup route from the current URL. {@a guards} +{@a milestone-5-route-guards} + + ## Milestone 5: Route guards -At the moment, *any* user can navigate *anywhere* in the application *anytime*. -That's not always the right thing to do. +At the moment, any user can navigate anywhere in the application anytime, but sometimes you need to control access to different parts of your app for various reasons. Some of which may include the following: * Perhaps the user is not authorized to navigate to the target component. -* Maybe the user must login (*authenticate*) first. +* Maybe the user must login (authenticate) first. * Maybe you should fetch some data before you display the target component. * You might want to save pending changes before leaving a component. * You might ask the user if it's OK to discard pending changes rather than save them. -You add _guards_ to the route configuration to handle these scenarios. +You add guards to the route configuration to handle these scenarios. A guard's return value controls the router's behavior: @@ -2972,15 +2429,14 @@ A guard's return value controls the router's behavior: * If it returns `false`, the navigation process stops and the user stays put. * If it returns a `UrlTree`, the current navigation cancels and a new navigation is initiated to the `UrlTree` returned. -
    -**Note:** The guard can also tell the router to navigate elsewhere, effectively canceling the current navigation. When -doing so inside a guard, the guard should return `false`; +**Note:** The guard can also tell the router to navigate elsewhere, effectively canceling the current navigation. +When doing so inside a guard, the guard should return `false`;
    -The guard *might* return its boolean answer synchronously. +The guard might return its boolean answer synchronously. But in many cases, the guard can't produce an answer synchronously. The guard could ask the user a question, save changes to the server, or fetch fresh data. These are all asynchronous operations. @@ -2990,7 +2446,7 @@ router will wait for the observable to resolve to `true` or `false`.
    -**Note:** The observable provided to the Router _must_ also complete. If the observable does not complete, the navigation will not continue. +**Note:** The observable provided to the `Router` must also complete. If the observable does not complete, the navigation does not continue.
    @@ -3009,18 +2465,15 @@ The router supports multiple guard interfaces: You can have multiple guards at every level of a routing hierarchy. The router checks the `CanDeactivate` and `CanActivateChild` guards first, from the deepest child route to the top. -Then it checks the `CanActivate` guards from the top down to the deepest child route. If the feature module -is loaded asynchronously, the `CanLoad` guard is checked before the module is loaded. -If _any_ guard returns false, pending guards that have not completed will be canceled, -and the entire navigation is canceled. +Then it checks the `CanActivate` guards from the top down to the deepest child route. +If the feature module is loaded asynchronously, the `CanLoad` guard is checked before the module is loaded. +If _any_ guard returns false, pending guards that have not completed will be canceled, and the entire navigation is canceled. There are several examples over the next few sections. - {@a can-activate-guard} - -### _CanActivate_: requiring authentication +### `CanActivate`: requiring authentication Applications often restrict access to a feature area based on who the user is. You could permit access only to authenticated users or to users with a specific role. @@ -3030,9 +2483,8 @@ The `CanActivate` guard is the tool to manage these navigation business rules. #### Add an admin feature module -In this next section, you'll extend the crisis center with some new *administrative* features. -Those features aren't defined yet. -But you can start by adding a new feature module named `AdminModule`. +This section guides you through extending the crisis center with some new administrative features. +Start by adding a new feature module named `AdminModule`. Generate an `admin` folder with a feature module file and a routing configuration file. @@ -3161,12 +2613,9 @@ The admin feature file structure looks like this:
    - - The admin feature module contains the `AdminComponent` used for routing within the feature module, a dashboard route and two unfinished components to manage crises and heroes. - @@ -3191,100 +2640,69 @@ feature module, a dashboard route and two unfinished components to manage crises - -
    - - -Although the admin dashboard `RouterLink` only contains a relative slash without an additional URL segment, it -is considered a match to any route within the admin feature area. You only want the `Dashboard` link to be active when the user visits that route. Adding an additional binding to the `Dashboard` routerLink,`[routerLinkActiveOptions]="{ exact: true }"`, marks the `./` link as active when the user navigates to the `/admin` URL and not when navigating to any of the child routes. - +Although the admin dashboard `RouterLink` only contains a relative slash without an additional URL segment, it is a match to any route within the admin feature area. +You only want the `Dashboard` link to be active when the user visits that route. +Adding an additional binding to the `Dashboard` routerLink,`[routerLinkActiveOptions]="{ exact: true }"`, marks the `./` link as active when the user navigates to the `/admin` URL and not when navigating to any of the child routes.
    - {@a component-less-route} - ##### Component-less route: grouping routes without a component The initial admin routing configuration: - -Looking at the child route under the `AdminComponent`, there is a `path` and a `children` -property but it's not using a `component`. -You haven't made a mistake in the configuration. -You've defined a _component-less_ route. - -The goal is to group the `Crisis Center` management routes under the `admin` path. -You don't need a component to do it. -A _component-less_ route makes it easier to [guard child routes](#can-activate-child-guard). +The child route under the `AdminComponent` has a `path` and a `children` property but it's not using a `component`. +This defines a _component-less_ route. +To group the `Crisis Center` management routes under the `admin` path a component is unnecessary. +Additionally, a _component-less_ route makes it easier to [guard child routes](#can-activate-child-guard). Next, import the `AdminModule` into `app.module.ts` and add it to the `imports` array to register the admin routes. - - - Add an "Admin" link to the `AppComponent` shell so that users can get to this feature. - - - {@a guard-admin-feature} - #### Guard the admin feature -Currently every route within the *Crisis Center* is open to everyone. -The new *admin* feature should be accessible only to authenticated users. +Currently, every route within the Crisis Center is open to everyone. +The new admin feature should be accessible only to authenticated users. -You could hide the link until the user logs in. But that's tricky and difficult to maintain. - -Instead you'll write a `canActivate()` guard method to redirect anonymous users to the +Write a `canActivate()` guard method to redirect anonymous users to the login page when they try to enter the admin area. -This is a general purpose guard—you can imagine other features -that require authenticated users—so you generate an -`AuthGuard` in the `auth` folder. +Generate an `AuthGuard` in the `auth` folder. ng generate guard auth/auth -At the moment you're interested in seeing how guards work so the first version does nothing useful. -It simply logs to console and `returns` true immediately, allowing navigation to proceed: - +To demonstrate the fundamentals, this example only logs to the console, `returns` true immediately, and allows navigation to proceed: - - Next, open `admin-routing.module.ts `, import the `AuthGuard` class, and update the admin route with a `canActivate` guard property that references it: - - - -The admin feature is now protected by the guard, albeit protected poorly. - +The admin feature is now protected by the guard, but the guard requires more customization to work fully. {@a teach-auth} +#### Authenticate with `AuthGuard` -#### Teach *AuthGuard* to authenticate - -Make the `AuthGuard` at least pretend to authenticate. +Make the `AuthGuard` mimic authentication. The `AuthGuard` should call an application service that can login a user and retain information about the current user. Generate a new `AuthService` in the `auth` folder: @@ -3296,56 +2714,44 @@ Update the `AuthService` to log in the user: - - -Although it doesn't actually log in, it has what you need for this discussion. -It has an `isLoggedIn` flag to tell you whether the user is authenticated. -Its `login` method simulates an API call to an external service by returning an -observable that resolves successfully after a short pause. +Although it doesn't actually log in, it has an `isLoggedIn` flag to tell you whether the user is authenticated. +Its `login()` method simulates an API call to an external service by returning an observable that resolves successfully after a short pause. The `redirectUrl` property stores the URL that the user wanted to access so you can navigate to it after authentication.
    -To keep things simple, this example redirects unauthenticated users to `/admin`. +To keep things minimal, this example redirects unauthenticated users to `/admin`.
    -Revise the `AuthGuard` to call it. - +Revise the `AuthGuard` to call the `AuthService`. - - -Notice that you *inject* the `AuthService` and the `Router` in the constructor. +Notice that you inject the `AuthService` and the `Router` in the constructor. You haven't provided the `AuthService` yet but it's good to know that you can inject helpful services into routing guards. This guard returns a synchronous boolean result. If the user is logged in, it returns true and the navigation continues. -The `ActivatedRouteSnapshot` contains the _future_ route that will be activated and the `RouterStateSnapshot` -contains the _future_ `RouterState` of the application, should you pass through the guard check. - -If the user is not logged in, you store the attempted URL the user came from using the `RouterStateSnapshot.url` and -tell the router to navigate to a login page—a page you haven't created yet. -This secondary navigation automatically cancels the current navigation; `checkLogin()` returns -`false` just to be clear about that. +The `ActivatedRouteSnapshot` contains the _future_ route that will be activated and the `RouterStateSnapshot` contains the _future_ `RouterState` of the application, should you pass through the guard check. +If the user is not logged in, you store the attempted URL the user came from using the `RouterStateSnapshot.url` and tell the router to redirect to a login page—a page you haven't created yet. +This secondary navigation automatically cancels the current navigation; `checkLogin()` returns `false`. {@a add-login-component} +#### Add the `LoginComponent` -#### Add the *LoginComponent* - -You need a `LoginComponent` for the user to log in to the app. After logging in, you'll redirect -to the stored URL if available, or use the default URL. -There is nothing new about this component or the way you wire it into the router configuration. +You need a `LoginComponent` for the user to log in to the app. After logging in, you'll redirect to the stored URL if available, or use the default URL. +There is nothing new about this component or the way you use it in the router configuration. ng generate component auth/login -Register a `/login` route in the `auth/auth-routing.module.ts`. In `app.module.ts`, import and add the `AuthModule` to the `AppModule` imports. +Register a `/login` route in the `auth/auth-routing.module.ts`. +In `app.module.ts`, import and add the `AuthModule` to the `AppModule` imports. @@ -3371,12 +2777,11 @@ Register a `/login` route in the `auth/auth-routing.module.ts`. In `app.module.t {@a can-activate-child-guard} - -### _CanActivateChild_: guarding child routes +### `CanActivateChild`: guarding child routes You can also protect child routes with the `CanActivateChild` guard. The `CanActivateChild` guard is similar to the `CanActivate` guard. -The key difference is that it runs _before_ any child route is activated. +The key difference is that it runs before any child route is activated. You protected the admin feature module from unauthorized access. You should also protect child routes _within_ the feature module. @@ -3384,197 +2789,136 @@ You should also protect child routes _within_ the feature module. Extend the `AuthGuard` to protect when navigating between the `admin` routes. Open `auth.guard.ts` and add the `CanActivateChild` interface to the imported tokens from the router package. -Next, implement the `canActivateChild()` method which takes the same arguments as the `canActivate()` method: -an `ActivatedRouteSnapshot` and `RouterStateSnapshot`. -The `canActivateChild()` method can return an `Observable` or `Promise` for -async checks and a `boolean` for sync checks. +Next, implement the `canActivateChild()` method which takes the same arguments as the `canActivate()` method: an `ActivatedRouteSnapshot` and `RouterStateSnapshot`. +The `canActivateChild()` method can return an `Observable` or `Promise` for async checks and a `boolean` for sync checks. This one returns a `boolean`: - - - Add the same `AuthGuard` to the `component-less` admin route to protect all other child routes at one time instead of adding the `AuthGuard` to each route individually. - - - {@a can-deactivate-guard} -### _CanDeactivate_: handling unsaved changes -Back in the "Heroes" workflow, the app accepts every change to a hero immediately without hesitation or validation. +### `CanDeactivate`: handling unsaved changes -In the real world, you might have to accumulate the users changes. -You might have to validate across fields. -You might have to validate on the server. -You might have to hold changes in a pending state until the user confirms them *as a group* or -cancels and reverts all changes. +Back in the "Heroes" workflow, the app accepts every change to a hero immediately without validation. -What do you do about unapproved, unsaved changes when the user navigates away? -You can't just leave and risk losing the user's changes; that would be a terrible experience. +In the real world, you might have to accumulate the users changes, validate across fields, validate on the server, or hold changes in a pending state until the user confirms them as a group or cancels and reverts all changes. -It's better to pause and let the user decide what to do. +When the user navigates away, you can let the user decide what to do with unsaved changes. If the user cancels, you'll stay put and allow more changes. If the user approves, the app can save. You still might delay navigation until the save succeeds. -If you let the user move to the next screen immediately and -the save were to fail (perhaps the data are ruled invalid), you would lose the context of the error. +If you let the user move to the next screen immediately and saving were to fail (perhaps the data is ruled invalid), you would lose the context of the error. -You can't block while waiting for the server—that's not possible in a browser. -You need to stop the navigation while you wait, asynchronously, for the server -to return with its answer. +You need to stop the navigation while you wait, asynchronously, for the server to return with its answer. -You need the `CanDeactivate` guard. +The `CanDeactivate` guard helps you decide what to do with unsaved changes and how to proceed. {@a cancel-save} - #### Cancel and save -The sample application doesn't talk to a server. -Fortunately, you have another way to demonstrate an asynchronous router hook. - Users update crisis information in the `CrisisDetailComponent`. Unlike the `HeroDetailComponent`, the user changes do not update the crisis entity immediately. -Instead, the app updates the entity when the user presses the *Save* button and -discards the changes when the user presses the *Cancel* button. +Instead, the app updates the entity when the user presses the Save button and discards the changes when the user presses the Cancel button. Both buttons navigate back to the crisis list after save or cancel. - +In this scenario, the user could click the heroes link, cancel, push the browser back button, or navigate away without saving. - -What if the user tries to navigate away without saving or canceling? -The user could push the browser back button or click the heroes link. -Both actions trigger a navigation. -Should the app save or cancel automatically? - -This demo does neither. Instead, it asks the user to make that choice explicitly -in a confirmation dialog box that *waits asynchronously for the user's -answer*. +This example app asks the user to be explicit with a confirmation dialog box that waits asynchronously for the user's +response.
    - - -You could wait for the user's answer with synchronous, blocking code. -The app will be more responsive—and can do other work—by -waiting for the user's answer asynchronously. Waiting for the user asynchronously -is like waiting for the server asynchronously. +You could wait for the user's answer with synchronous, blocking code, however, the app is more responsive—and can do other work—by waiting for the user's answer asynchronously.
    - - Generate a `Dialog` service to handle user confirmation. ng generate service dialog -Add a `confirm()` method to the `DialogService` to prompt the user to confirm their intent. The `window.confirm` is a _blocking_ action that displays a modal dialog and waits for user interaction. +Add a `confirm()` method to the `DialogService` to prompt the user to confirm their intent. +The `window.confirm` is a blocking action that displays a modal dialog and waits for user interaction. -It returns an `Observable` that *resolves* when the user eventually decides what to do: either -to discard changes and navigate away (`true`) or to preserve the pending changes and stay in the crisis editor (`false`). - +It returns an `Observable` that resolves when the user eventually decides what to do: either to discard changes and navigate away (`true`) or to preserve the pending changes and stay in the crisis editor (`false`). {@a CanDeactivate} - -Generate a _guard_ that checks for the presence of a `canDeactivate()` method in a component—any component. +Generate a guard that checks for the presence of a `canDeactivate()` method in a component—any component. ng generate guard can-deactivate -The `CrisisDetailComponent` will have this method. -But the guard doesn't have to know that. -The guard shouldn't know the details of any component's deactivation method. -It need only detect that the component has a `canDeactivate()` method and call it. -This approach makes the guard reusable. - +Paste the following code into your guard. - +While the guard doesn't have to know which component has a deactivate method, it can detect that the `CrisisDetailComponent` component has the `canDeactivate()` method and call it. +The guard not knowing the details of any component's deactivation method makes the guard reusable. Alternatively, you could make a component-specific `CanDeactivate` guard for the `CrisisDetailComponent`. -The `canDeactivate()` method provides you with the current -instance of the `component`, the current `ActivatedRoute`, -and `RouterStateSnapshot` in case you needed to access -some external information. This would be useful if you only -wanted to use this guard for this component and needed to get -the component's properties or confirm whether the router should allow navigation away from it. - +The `canDeactivate()` method provides you with the current instance of the `component`, the current `ActivatedRoute`, and `RouterStateSnapshot` in case you needed to access some external information. +This would be useful if you only wanted to use this guard for this component and needed to get the component's properties or confirm whether the router should allow navigation away from it. - - Looking back at the `CrisisDetailComponent`, it implements the confirmation workflow for unsaved changes. - - - -Notice that the `canDeactivate()` method *can* return synchronously; -it returns `true` immediately if there is no crisis or there are no pending changes. -But it can also return a `Promise` or an `Observable` and the router will wait for that -to resolve to truthy (navigate) or falsy (stay put). - +Notice that the `canDeactivate()` method can return synchronously; it returns `true` immediately if there is no crisis or there are no pending changes. +But it can also return a `Promise` or an `Observable` and the router will wait for that to resolve to truthy (navigate) or falsy (stay on the current route). Add the `Guard` to the crisis detail route in `crisis-center-routing.module.ts` using the `canDeactivate` array property. - - Now you have given the user a safeguard against unsaved changes. + {@a Resolve} {@a resolve-guard} - ### _Resolve_: pre-fetching component data In the `Hero Detail` and `Crisis Detail`, the app waited until the route was activated to fetch the respective hero or crisis. -This worked well, but there's a better way. If you were using a real world API, there might be some delay before the data to display is returned from the server. You don't want to display a blank component while waiting for the data. -It's preferable to pre-fetch data from the server so it's ready the -moment the route is activated. This also allows you to handle errors before routing to the component. +To improve this behavior, you can pre-fetch data from the server using a resolver so it's ready the +moment the route is activated. +This also allows you to handle errors before routing to the component. There's no point in navigating to a crisis detail for an `id` that doesn't have a record. It'd be better to send the user back to the `Crisis List` that shows only valid crisis centers. -In summary, you want to delay rendering the routed component until all necessary data have been fetched. - -You need a *resolver*. +In summary, you want to delay rendering the routed component until all necessary data has been fetched. {@a fetch-before-navigating} - #### Fetch data before navigating At the moment, the `CrisisDetailComponent` retrieves the selected crisis. -If the crisis is not found, it navigates back to the crisis list view. +If the crisis is not found, the router navigates back to the crisis list view. The experience might be better if all of this were handled first, before the route is activated. -A `CrisisDetailResolver` service could retrieve a `Crisis` or navigate away if the `Crisis` does not exist -_before_ activating the route and creating the `CrisisDetailComponent`. +A `CrisisDetailResolver` service could retrieve a `Crisis` or navigate away, if the `Crisis` did not exist, _before_ activating the route and creating the `CrisisDetailComponent`. Generate a `CrisisDetailResolver` service file within the `Crisis Center` feature area. @@ -3582,61 +2926,45 @@ Generate a `CrisisDetailResolver` service file within the `Crisis Center` featur ng generate service crisis-center/crisis-detail-resolver - +Move the relevant parts of the crisis retrieval logic in `CrisisDetailComponent.ngOnInit()` into the `CrisisDetailResolverService`. +Import the `Crisis` model, `CrisisService`, and the `Router` so you can navigate elsewhere if you can't fetch the crisis. - -Take the relevant parts of the crisis retrieval logic in `CrisisDetailComponent.ngOnInit` -and move them into the `CrisisDetailResolverService`. -Import the `Crisis` model, `CrisisService`, and the `Router` -so you can navigate elsewhere if you can't fetch the crisis. - -Be explicit. Implement the `Resolve` interface with a type of `Crisis`. +Be explicit and implement the `Resolve` interface with a type of `Crisis`. Inject the `CrisisService` and `Router` and implement the `resolve()` method. That method could return a `Promise`, an `Observable`, or a synchronous return value. -The `CrisisService.getCrisis` method returns an observable, in order to prevent the route from loading until the data is fetched. -The `Router` guards require an observable to `complete`, meaning it has emitted all -of its values. You use the `take` operator with an argument of `1` to ensure that the -Observable completes after retrieving the first value from the Observable returned by the -`getCrisis` method. +The `CrisisService.getCrisis()` method returns an observable in order to prevent the route from loading until the data is fetched. +The `Router` guards require an observable to `complete`, which means it has emitted all +of its values. +You use the `take` operator with an argument of `1` to ensure that the `Observable` completes after retrieving the first value from the Observable returned by the `getCrisis()` method. -If it doesn't return a valid `Crisis`, return an empty `Observable`, canceling the previous in-flight navigation to the `CrisisDetailComponent` and navigate the user back to the `CrisisListComponent`. The updated resolver service looks like this: +If it doesn't return a valid `Crisis`, then return an empty `Observable`, cancel the previous in-progress navigation to the `CrisisDetailComponent`, and navigate the user back to the `CrisisListComponent`. +The updated resolver service looks like this: -Import this resolver in the `crisis-center-routing.module.ts` -and add a `resolve` object to the `CrisisDetailComponent` route configuration. - +Import this resolver in the `crisis-center-routing.module.ts` and add a `resolve` object to the `CrisisDetailComponent` route configuration. - - The `CrisisDetailComponent` should no longer fetch the crisis. +When you re-configured the route, you changed where the crisis is. Update the `CrisisDetailComponent` to get the crisis from the `ActivatedRoute.data.crisis` property instead; -that's where you said it should be when you re-configured the route. -It will be there when the `CrisisDetailComponent` ask for it. - - - -**Two critical points** +Note the following two important points: 1. The router's `Resolve` interface is optional. The `CrisisDetailResolverService` doesn't inherit from a base class. The router looks for that method and calls it if found. -1. Rely on the router to call the resolver. -Don't worry about all the ways that the user could navigate away. -That's the router's job. Write this class and let the router take it from there. - -The relevant *Crisis Center* code for this milestone follows. +1. The router calls the resolver in any case where the the user could navigate away so you don't have to code for each use case. +The relevant Crisis Center code for this milestone follows. @@ -3700,19 +3028,14 @@ Guards - - {@a query-parameters} - {@a fragment} - ### Query parameters and fragments -In the [route parameters](#optional-route-parameters) example, you only dealt with parameters specific to -the route, but what if you wanted optional parameters available to all routes? -This is where query parameters come into play. +In the [route parameters](#optional-route-parameters) section, you only dealt with parameters specific to the route. +However, you can use query parameters to get optional parameters available to all routes. [Fragments](https://en.wikipedia.org/wiki/Fragment_identifier) refer to certain elements on the page identified with an `id` attribute. @@ -3723,60 +3046,38 @@ Add an `anchor` element so you can jump to a certain point on the page. Add the `NavigationExtras` object to the `router.navigate()` method that navigates you to the `/login` route. - - - -You can also preserve query parameters and fragments across navigations without having to provide them -again when navigating. In the `LoginComponent`, you'll add an *object* as the -second argument in the `router.navigateUrl()` function -and provide the `queryParamsHandling` and `preserveFragment` to pass along the current query parameters -and fragment to the next route. - +You can also preserve query parameters and fragments across navigations without having to provide them again when navigating. +In the `LoginComponent`, you'll add an *object* as the second argument in the `router.navigateUrl()` function and provide the `queryParamsHandling` and `preserveFragment` to pass along the current query parameters and fragment to the next route.
    - -The `queryParamsHandling` feature also provides a `merge` option, which will preserve and combine the current query parameters with any provided query parameters -when navigating. - +The `queryParamsHandling` feature also provides a `merge` option, which preserves and combines the current query parameters with any provided query parameters when navigating.
    - - -As you'll be navigating to the *Admin Dashboard* route after logging in, you'll update it to handle the +To navigate to the Admin Dashboard route after logging in, update `admin-dashboard.component.ts` to handle the query parameters and fragment. - +Query parameters and fragments are also available through the `ActivatedRoute` service. +Just like route parameters, the query parameters and fragments are provided as an `Observable`. +The updated Crisis Admin component feeds the `Observable` directly into the template using the `AsyncPipe`. +Now, you can click on the Admin button, which takes you to the Login page with the provided `queryParamMap` and `fragment`. +After you click the login button, notice that you have been redirected to the `Admin Dashboard` page with the query parameters and fragment still intact in the address bar. -*Query parameters* and *fragments* are also available through the `ActivatedRoute` service. -Just like *route parameters*, the query parameters and fragments are provided as an `Observable`. -The updated *Crisis Admin* component feeds the `Observable` directly into the template using the `AsyncPipe`. - - -Now, you can click on the *Admin* button, which takes you to the *Login* -page with the provided `queryParamMap` and `fragment`. After you click the login button, notice that -you have been redirected to the `Admin Dashboard` page with the query parameters and fragment still intact in the address bar. - -You can use these persistent bits of information for things that need to be provided across pages like -authentication tokens or session ids. - +You can use these persistent bits of information for things that need to be provided across pages like authentication tokens or session ids.
    - - The `query params` and `fragment` can also be preserved using a `RouterLink` with the `queryParamsHandling` and `preserveFragment` bindings respectively. -
    @@ -3785,10 +3086,9 @@ the `queryParamsHandling` and `preserveFragment` bindings respectively. ## Milestone 6: Asynchronous routing As you've worked through the milestones, the application has naturally gotten larger. -As you continue to build out feature areas, the overall application size will continue to grow. -At some point you'll reach a tipping point where the application takes a long time to load. +At some point you'll reach a point where the application takes a long time to load. -How do you combat this problem? With asynchronous routing, which loads feature modules _lazily_, on request. +To remedy this issue, use asynchronous routing, which loads feature modules lazily, on request. Lazy loading has multiple benefits. * You can load feature areas only when requested by the user. @@ -3805,17 +3105,14 @@ But others can and should be lazy loaded. The `AdminModule`, for example, is needed by a few authorized users, so you should only load it when requested by the right people. - {@a lazy-loading-route-config} - ### Lazy Loading route configuration -Change the `admin` **path** in the `admin-routing.module.ts` from `'admin'` to an empty string, `''`, the _empty path_. +Change the `admin` path in the `admin-routing.module.ts` from `'admin'` to an empty string, `''`, the empty path. -The `Router` supports *empty path* routes; -use them to group routes together without adding any additional path segments to the URL. -Users will still visit `/admin` and the `AdminComponent` still serves as the *Routing Component* containing child routes. +Use empty path routes to group routes together without adding any additional path segments to the URL. +Users will still visit `/admin` and the `AdminComponent` still serves as the Routing Component containing child routes. Open the `AppRoutingModule` and add a new `admin` route to its `appRoutes` array. @@ -3828,65 +3125,51 @@ After the code is requested and loaded, the `Promise` resolves an object that co
    -*Note*: When using absolute paths, the `NgModule` file location must begin with `src/app` in order to resolve correctly. For custom [path mapping with absolute paths](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping), the `baseUrl` and `paths` properties in the project `tsconfig.json` must be configured. +*Note*: When using absolute paths, the `NgModule` file location must begin with `src/app` in order to resolve correctly. For custom [path mapping with absolute paths](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping), you must configure the `baseUrl` and `paths` properties in the project `tsconfig.json`.
    - When the router navigates to this route, it uses the `loadChildren` string to dynamically load the `AdminModule`. Then it adds the `AdminModule` routes to its current route configuration. Finally, it loads the requested route to the destination admin component. -The lazy loading and re-configuration happen just once, when the route is _first_ requested; -the module and routes are available immediately for subsequent requests. +The lazy loading and re-configuration happen just once, when the route is first requested; the module and routes are available immediately for subsequent requests.
    - - Angular provides a built-in module loader that supports SystemJS to load modules asynchronously. If you were using another bundling tool, such as Webpack, you would use the Webpack mechanism for asynchronously loading modules. -
    - - Take the final step and detach the admin feature set from the main application. The root `AppModule` must neither load nor reference the `AdminModule` or its files. In `app.module.ts`, remove the `AdminModule` import statement from the top of the file and remove the `AdminModule` from the NgModule's `imports` array. - {@a can-load-guard} +### `CanLoad`: guarding unauthorized loading of feature modules -### _CanLoad_ Guard: guarding unauthorized loading of feature modules - -You're already protecting the `AdminModule` with a `CanActivate` guard that prevents unauthorized users from -accessing the admin feature area. +You're already protecting the `AdminModule` with a `CanActivate` guard that prevents unauthorized users from accessing the admin feature area. It redirects to the login page if the user is not authorized. But the router is still loading the `AdminModule` even if the user can't visit any of its components. Ideally, you'd only load the `AdminModule` if the user is logged in. -Add a **`CanLoad`** guard that only loads the `AdminModule` once the user is logged in _and_ attempts to access the admin feature area. +Add a `CanLoad` guard that only loads the `AdminModule` once the user is logged in _and_ attempts to access the admin feature area. -The existing `AuthGuard` already has the essential logic in -its `checkLogin()` method to support the `CanLoad` guard. +The existing `AuthGuard` already has the essential logic in its `checkLogin()` method to support the `CanLoad` guard. Open `auth.guard.ts`. Import the `CanLoad` interface from `@angular/router`. Add it to the `AuthGuard` class's `implements` list. Then implement `canLoad()` as follows: - - - The router sets the `canLoad()` method's `route` parameter to the intended destination URL. The `checkLogin()` method redirects to that URL once the user has logged in. @@ -3894,67 +3177,51 @@ Now import the `AuthGuard` into the `AppRoutingModule` and add the `AuthGuard` t array property for the `admin` route. The completed admin route looks like this: - - - {@a preloading} - ### Preloading: background loading of feature areas -You've learned how to load modules on-demand. -You can also load modules asynchronously with _preloading_. -This may seem like what the app has been doing all along. Not quite. -The `AppModule` is loaded when the application starts; that's _eager_ loading. -Now the `AdminModule` loads only when the user clicks on a link; that's _lazy_ loading. +In addition to loading modules on-demand, you can load modules asynchronously with preloading. -_Preloading_ is something in between. -Consider the _Crisis Center_. +The `AppModule` is eagerly loaded when the application starts, meaning that it loads right away. +Now the `AdminModule` loads only when the user clicks on a link, which is called lazy loading. + +Preloading allows you to load modules in the background so that the data is ready to render when the user activates a particular route. +Consider the Crisis Center. It isn't the first view that a user sees. -By default, the _Heroes_ are the first view. -For the smallest initial payload and fastest launch time, -you should eagerly load the `AppModule` and the `HeroesModule`. - -You could lazy load the _Crisis Center_. -But you're almost certain that the user will visit the _Crisis Center_ within minutes of launching the app. -Ideally, the app would launch with just the `AppModule` and the `HeroesModule` loaded -and then, almost immediately, load the `CrisisCenterModule` in the background. -By the time the user navigates to the _Crisis Center_, its module will have been loaded and ready to go. - -That's _preloading_. +By default, the Heroes are the first view. +For the smallest initial payload and fastest launch time, you should eagerly load the `AppModule` and the `HeroesModule`. +You could lazy load the Crisis Center. +But you're almost certain that the user will visit the Crisis Center within minutes of launching the app. +Ideally, the app would launch with just the `AppModule` and the `HeroesModule` loaded and then, almost immediately, load the `CrisisCenterModule` in the background. +By the time the user navigates to the Crisis Center, its module will have been loaded and ready. {@a how-preloading} - #### How preloading works -After each _successful_ navigation, the router looks in its configuration for an unloaded module that it can preload. -Whether it preloads a module, and which modules it preloads, depends upon the *preload strategy*. +After each successful navigation, the router looks in its configuration for an unloaded module that it can preload. +Whether it preloads a module, and which modules it preloads, depends upon the preload strategy. -The `Router` offers two preloading strategies out of the box: +The `Router` offers two preloading strategies: -* No preloading at all which is the default. Lazy loaded feature areas are still loaded on demand. +* No preloading, which is the default. Lazy loaded feature areas are still loaded on-demand. * Preloading of all lazy loaded feature areas. -Out of the box, the router either never preloads, or preloads every lazy load module. -The `Router` also supports [custom preloading strategies](#custom-preloading) for -fine control over which modules to preload and when. - -In this next section, you'll update the `CrisisCenterModule` to load lazily -by default and use the `PreloadAllModules` strategy -to load it (and _all other_ lazy loaded modules) as soon as possible. +The router either never preloads, or preloads every lazy loaded module. +The `Router` also supports [custom preloading strategies](#custom-preloading) for fine control over which modules to preload and when. +This section guides you through updating the `CrisisCenterModule` to load lazily by default and use the `PreloadAllModules` strategy to load all lazy loaded modules. {@a lazy-load-crisis-center} - -#### Lazy load the _crisis center_ +#### Lazy load the crisis center Update the route configuration to lazy load the `CrisisCenterModule`. -Take the same steps you used to configure `AdminModule` for lazy load. +Take the same steps you used to configure `AdminModule` for lazy loading. 1. Change the `crisis-center` path in the `CrisisCenterRoutingModule` to an empty string. @@ -3984,8 +3251,6 @@ Here are the updated modules _before enabling preload_:     - - You could try this now and confirm that the `CrisisCenterModule` loads after you click the "Crisis Center" button. To enable preloading of all lazy loaded modules, import the `PreloadAllModules` token from the Angular router package. @@ -3996,49 +3261,35 @@ Add the `PreloadAllModules` token to the `forRoot()` call: +This configures the `Router` preloader to immediately load all lazy loaded routes (routes with a `loadChildren` property). +When you visit `http://localhost:4200`, the `/heroes` route loads immediately upon launch and the router starts loading the `CrisisCenterModule` right after the `HeroesModule` loads. -This tells the `Router` preloader to immediately load _all_ lazy loaded routes (routes with a `loadChildren` property). - -When you visit `http://localhost:4200`, the `/heroes` route loads immediately upon launch -and the router starts loading the `CrisisCenterModule` right after the `HeroesModule` loads. - -Surprisingly, the `AdminModule` does _not_ preload. Something is blocking it. - +Currently, the `AdminModule` does not preload because `CanLoad` is blocking it. {@a preload-canload} - -#### CanLoad blocks preload +#### `CanLoad` blocks preload The `PreloadAllModules` strategy does not load feature areas protected by a [CanLoad](#can-load-guard) guard. -This is by design. -You added a `CanLoad` guard to the route in the `AdminModule` a few steps back -to block loading of that module until the user is authorized. +You added a `CanLoad` guard to the route in the `AdminModule` a few steps back to block loading of that module until the user is authorized. That `CanLoad` guard takes precedence over the preload strategy. -If you want to preload a module _and_ guard against unauthorized access, -drop the `canLoad()` guard method and rely on the [canActivate()](#can-activate-guard) guard alone. - +If you want to preload a module as well as guard against unauthorized access, remove the `canLoad()` guard method and rely on the [canActivate()](#can-activate-guard) guard alone. {@a custom-preloading} - ### Custom Preloading Strategy -Preloading every lazy loaded modules works well in many situations, -but it isn't always the right choice, especially on mobile devices and over low bandwidth connections. -You may choose to preload only certain feature modules, based on user metrics and other business and technical factors. +Preloading every lazy loaded module works well in many situations. +However, in consideration of things such as low bandwidth and user metrics, you can use a custom preloading strategy for specific feature modules. -You can control what and how the router preloads with a custom preloading strategy. - -In this section, you'll add a custom strategy that _only_ preloads routes whose `data.preload` flag is set to `true`. +This section guides you through adding a custom strategy that only preloads routes whose `data.preload` flag is set to `true`. Recall that you can add anything to the `data` property of a route. Set the `data.preload` flag in the `crisis-center` route in the `AppRoutingModule`. - Generate a new `SelectivePreloadingStrategy` service. @@ -4047,26 +3298,24 @@ Generate a new `SelectivePreloadingStrategy` service. ng generate service selective-preloading-strategy +Replace the contents of `selective-preloading-strategy.service.ts` with the following: - + +`SelectivePreloadingStrategyService` implements the `PreloadingStrategy`, which has one method, `preload()`. - -`SelectivePreloadingStrategyService` implements the `PreloadingStrategy`, which has one method, `preload`. - -The router calls the `preload` method with two arguments: +The router calls the `preload()` method with two arguments: 1. The route to consider. 1. A loader function that can load the routed module asynchronously. An implementation of `preload` must return an `Observable`. -If the route should preload, it returns the observable returned by calling the loader function. -If the route should _not_ preload, it returns an `Observable` of `null`. +If the route does preload, it returns the observable returned by calling the loader function. +If the route does not preload, it returns an `Observable` of `null`. -In this sample, the `preload` method loads the route if the route's `data.preload` flag is truthy. +In this sample, the `preload()` method loads the route if the route's `data.preload` flag is truthy. -It also has a side-effect. -`SelectivePreloadingStrategyService` logs the `path` of a selected route in its public `preloadedModules` array. +As a side-effect, `SelectivePreloadingStrategyService` logs the `path` of a selected route in its public `preloadedModules` array. Shortly, you'll extend the `AdminDashboardComponent` to inject this service and display its `preloadedModules` array. @@ -4074,8 +3323,7 @@ But first, make a few changes to the `AppRoutingModule`. 1. Import `SelectivePreloadingStrategyService` into `AppRoutingModule`. 1. Replace the `PreloadAllModules` strategy in the call to `forRoot()` with this `SelectivePreloadingStrategyService`. -1. Add the `SelectivePreloadingStrategyService` strategy to the `AppRoutingModule` providers array so it can be injected -elsewhere in the app. +1. Add the `SelectivePreloadingStrategyService` strategy to the `AppRoutingModule` providers array so you can inject it elsewhere in the app. Now edit the `AdminDashboardComponent` to display the log of preloaded routes. @@ -4083,52 +3331,58 @@ Now edit the `AdminDashboardComponent` to display the log of preloaded routes. 1. Inject it into the dashboard's constructor. 1. Update the template to display the strategy service's `preloadedModules` array. -When you're done it looks like this. - +Now the file is as follows: - - Once the application loads the initial route, the `CrisisCenterModule` is preloaded. Verify this by logging in to the `Admin` feature area and noting that the `crisis-center` is listed in the `Preloaded Modules`. -It's also logged to the browser's console. - +It also logs to the browser's console. {@a redirect-advanced} -## Migrating URLs with Redirects - -You've setup the routes for navigating around your application. You've used navigation imperatively and declaratively to many different routes. But like any application, requirements change over time. You've setup links and navigation to `/heroes` and `/hero/:id` from the `HeroListComponent` and `HeroDetailComponent` components. If there was a requirement that links to `heroes` become `superheroes`, you still want the previous URLs to navigate correctly. You also don't want to go and update every link in your application, so redirects makes refactoring routes trivial. +### Migrating URLs with redirects +You've setup the routes for navigating around your application and used navigation imperatively and declaratively. +But like any application, requirements change over time. +You've setup links and navigation to `/heroes` and `/hero/:id` from the `HeroListComponent` and `HeroDetailComponent` components. +If there were a requirement that links to `heroes` become `superheroes`, you would still want the previous URLs to navigate correctly. +You also don't want to update every link in your application, so redirects makes refactoring routes trivial. {@a url-refactor} -### Changing /heroes to /superheroes +#### Changing `/heroes` to `/superheroes` -Let's take the `Hero` routes and migrate them to new URLs. The `Router` checks for redirects in your configuration before navigating, so each redirect is triggered when needed. To support this change, you'll add redirects from the old routes to the new routes in the `heroes-routing.module`. +This section guides you through migrating the `Hero` routes to new URLs. +The `Router` checks for redirects in your configuration before navigating, so each redirect is triggered when needed. To support this change, add redirects from the old routes to the new routes in the `heroes-routing.module`. - -You'll notice two different types of redirects. The first change is from `/heroes` to `/superheroes` without any parameters. This is a straightforward redirect, unlike the change from `/hero/:id` to `/superhero/:id`, which includes the `:id` route parameter. Router redirects also use powerful pattern matching, so the `Router` inspects the URL and replaces route parameters in the `path` with their appropriate destination. Previously, you navigated to a URL such as `/hero/15` with a route parameter `id` of `15`. +Notice two different types of redirects. +The first change is from `/heroes` to `/superheroes` without any parameters. +The second change is from `/hero/:id` to `/superhero/:id`, which includes the `:id` route parameter. +Router redirects also use powerful pattern-matching, so the `Router` inspects the URL and replaces route parameters in the `path` with their appropriate destination. +Previously, you navigated to a URL such as `/hero/15` with a route parameter `id` of `15`.
    The `Router` also supports [query parameters](#query-parameters) and the [fragment](#fragment) when using redirects. -* When using absolute redirects, the `Router` will use the query parameters and the fragment from the redirectTo in the route config. +* When using absolute redirects, the `Router` will use the query parameters and the fragment from the `redirectTo` in the route config. * When using relative redirects, the `Router` use the query params and the fragment from the source URL.
    -Before updating the `app-routing.module.ts`, you'll need to consider an important rule. Currently, our empty path route redirects to `/heroes`, which redirects to `/superheroes`. This _won't_ work and is by design as the `Router` handles redirects once at each level of routing configuration. This prevents chaining of redirects, which can lead to endless redirect loops. +Currently, the empty path route redirects to `/heroes`, which redirects to `/superheroes`. +This won't work because the `Router` handles redirects once at each level of routing configuration. +This prevents chaining of redirects, which can lead to endless redirect loops. -So instead, you'll update the empty path route in `app-routing.module.ts` to redirect to `/superheroes`. +Instead, update the empty path route in `app-routing.module.ts` to redirect to `/superheroes`. -`RouterLink`s aren't tied to route configuration, so you'll need to update the associated router links so they remain active when the new route is active. You'll update the `app.component.ts` template for the `/heroes` routerLink. +A `routerLink` isn't tied to route configuration, so update the associated router links to remain active when the new route is active. +Update the `app.component.ts` template for the `/heroes` `routerLink`. @@ -4138,287 +3392,792 @@ Update the `goToHeroes()` method in the `hero-detail.component.ts` to navigate b With the redirects setup, all previous routes now point to their new destinations and both URLs still function as intended. - {@a inspect-config} +### Inspect the router's configuration +To determine if your routes are actually evaluated [in the proper order](#routing-module-order), you can inspect the router's configuration. -## Inspect the router's configuration - -You put a lot of effort into configuring the router in several routing module files -and were careful to list them [in the proper order](#routing-module-order). -Are routes actually evaluated as you planned? -How is the router really configured? - -You can inspect the router's current configuration any time by injecting it and -examining its `config` property. +Do this by injecting the router and logging to the console its `config` property. For example, update the `AppModule` as follows and look in the browser console window to see the finished route configuration. - {@a final-app} +## Final app -## Wrap up and final app - -You've covered a lot of ground in this guide and the application is too big to reprint here. -Please visit the -where you can download the final source code. - - -{@a appendices} - - - -## Appendices - -The balance of this guide is a set of appendices that -elaborate some of the points you covered quickly above. - -The appendix material isn't essential. Continued reading is for the curious. - +For the completed router app, see the for the final source code. {@a link-parameters-array} - - -### Appendix: link parameters array +## Link parameters array A link parameters array holds the following ingredients for router navigation: -* The *path* of the route to the destination component. +* The path of the route to the destination component. * Required and optional route parameters that go into the route URL. You can bind the `RouterLink` directive to such an array like this: - - - -You've written a two element array when specifying a route parameter like this: - +The following is a two-element array when specifying a route parameter: - - -You can provide optional route parameters in an object like this: - +You can provide optional route parameters in an object, as in `{ foo: 'foo' }`: +These three examples cover the needs of an app with one level of routing. +However, with a child router, such as in the crisis center, you create new link array possibilities. - -These three examples cover the need for an app with one level routing. -The moment you add a child router, such as the crisis center, you create new link array possibilities. - -Recall that you specified a default child route for the crisis center so this simple `RouterLink` is fine. - +The following minimal `RouterLink` example builds upon a specified [default child route](guide/router#a-crisis-center-with-child-routes) for the crisis center. - - -Parse it out. +Note the following: * The first item in the array identifies the parent route (`/crisis-center`). -* There are no parameters for this parent route so you're done with it. +* There are no parameters for this parent route. * There is no default for the child route so you need to pick one. * You're navigating to the `CrisisListComponent`, whose route path is `/`, but you don't need to explicitly add the slash. -* Voilà! `['/crisis-center']`. - -Take it a step further. Consider the following router link that -navigates from the root of the application down to the *Dragon Crisis*: +Consider the following router link that navigates from the root of the application down to the Dragon Crisis: - - * The first item in the array identifies the parent route (`/crisis-center`). -* There are no parameters for this parent route so you're done with it. +* There are no parameters for this parent route. * The second item identifies the child route details about a particular crisis (`/:id`). * The details child route requires an `id` route parameter. -* You added the `id` of the *Dragon Crisis* as the second item in the array (`1`). +* You added the `id` of the Dragon Crisis as the second item in the array (`1`). * The resulting path is `/crisis-center/1`. - -If you wanted to, you could redefine the `AppComponent` template with *Crisis Center* routes exclusively: - +You could also redefine the `AppComponent` template with Crisis Center routes exclusively: - - -In sum, you can write applications with one, two or more levels of routing. -The link parameters array affords the flexibility to represent any routing depth and -any legal sequence of route paths, (required) router parameters, and (optional) route parameter objects. - +In summary, you can write applications with one, two or more levels of routing. +The link parameters array affords the flexibility to represent any routing depth and any legal sequence of route paths, (required) router parameters, and (optional) route parameter objects. {@a browser-url-styles} - {@a location-strategy} +## `LocationStrategy` and browser URL styles +When the router navigates to a new component view, it updates the browser's location and history with a URL for that view. +As this is a strictly local URL the browser won't send this URL to the server and will not reload the page. -### Appendix: *LocationStrategy* and browser URL styles - -When the router navigates to a new component view, it updates the browser's location and history -with a URL for that view. -This is a strictly local URL. The browser shouldn't send this URL to the server -and should not reload the page. - -Modern HTML5 browsers support -history.pushState, -a technique that changes a browser's location and history without triggering a server page request. -The router can compose a "natural" URL that is indistinguishable from -one that would otherwise require a page load. - -Here's the *Crisis Center* URL in this "HTML5 pushState" style: +Modern HTML5 browsers support history.pushState, a technique that changes a browser's location and history without triggering a server page request. +The router can compose a "natural" URL that is indistinguishable from one that would otherwise require a page load. +Here's the Crisis Center URL in this "HTML5 pushState" style: localhost:3002/crisis-center/ - - -Older browsers send page requests to the server when the location URL changes -_unless_ the change occurs after a "#" (called the "hash"). -Routers can take advantage of this exception by composing in-application route -URLs with hashes. Here's a "hash URL" that routes to the *Crisis Center*. - +Older browsers send page requests to the server when the location URL changes unless the change occurs after a "#" (called the "hash"). +Routers can take advantage of this exception by composing in-application route URLs with hashes. +Here's a "hash URL" that routes to the Crisis Center. localhost:3002/src/#/crisis-center/ - - The router supports both styles with two `LocationStrategy` providers: 1. `PathLocationStrategy`—the default "HTML5 pushState" style. 1. `HashLocationStrategy`—the "hash URL" style. -The `RouterModule.forRoot()` function sets the `LocationStrategy` to the `PathLocationStrategy`, -making it the default strategy. -You can switch to the `HashLocationStrategy` with an override during the bootstrapping process if you prefer it. - +The `RouterModule.forRoot()` function sets the `LocationStrategy` to the `PathLocationStrategy`, which makes it the default strategy. +You also have the option of switching to the `HashLocationStrategy` with an override during the bootstrapping process.
    - - -Learn about providers and the bootstrap process in the -[Dependency Injection guide](guide/dependency-injection#bootstrap). - +For more information on providers and the bootstrap process, see [Dependency Injection](guide/dependency-injection#bootstrap).
    +## Choosing a routing strategy - -#### Which strategy is best? - -You must choose a strategy and you need to make the right call early in the project. -It won't be easy to change later once the application is in production -and there are lots of application URL references in the wild. +You must choose a routing strategy early in the development of you project because once the application is in production, visitors to your site use and depend on application URL references. Almost all Angular projects should use the default HTML5 style. -It produces URLs that are easier for users to understand. -And it preserves the option to do _server-side rendering_ later. +It produces URLs that are easier for users to understand and it preserves the option to do server-side rendering. -Rendering critical pages on the server is a technique that can greatly improve -perceived responsiveness when the app first loads. -An app that would otherwise take ten or more seconds to start -could be rendered on the server and delivered to the user's device -in less than a second. +Rendering critical pages on the server is a technique that can greatly improve perceived responsiveness when the app first loads. +An app that would otherwise take ten or more seconds to start could be rendered on the server and delivered to the user's device in less than a second. -This option is only available if application URLs look like normal web URLs -without hashes (#) in the middle. +This option is only available if application URLs look like normal web URLs without hashes (#) in the middle. -Stick with the default unless you have a compelling reason to -resort to hash routes. +## `` +The router uses the browser's history.pushState for navigation. +`pushState` allows you to customize in-app URL paths; for example, `localhost:4200/crisis-center`. +The in-app URLs can be indistinguishable from server URLs. -#### The *<base href>* - -The router uses the browser's -history.pushState -for navigation. Thanks to `pushState`, you can make in-app URL paths look the way you want them to -look, e.g. `localhost:4200/crisis-center`. The in-app URLs can be indistinguishable from server URLs. - -Modern HTML5 browsers were the first to support `pushState` which is why many people refer to these URLs as -"HTML5 style" URLs. - +Modern HTML5 browsers were the first to support `pushState` which is why many people refer to these URLs as "HTML5 style" URLs.
    - - HTML5 style navigation is the router default. -In the [LocationStrategy and browser URL styles](#browser-url-styles) Appendix, -learn why HTML5 style is preferred, how to adjust its behavior, and how to switch to the -older hash (#) style, if necessary. - +In the [LocationStrategy and browser URL styles](#browser-url-styles) section, learn why HTML5 style is preferable, how to adjust its behavior, and how to switch to the older hash (#) style, if necessary.
    - - -You must **add a -<base href> element** -to the app's `index.html` for `pushState` routing to work. -The browser uses the `` value to prefix *relative* URLs when referencing -CSS files, scripts, and images. +You must add a <base href> element to the app's `index.html` for `pushState` routing to work. +The browser uses the `` value to prefix relative URLs when referencing CSS files, scripts, and images. Add the `` element just after the `` tag. If the `app` folder is the application root, as it is for this application, -set the `href` value in **`index.html`** *exactly* as shown here. - +set the `href` value in `index.html` as shown here. -#### HTML5 URLs and the *<base href>* +### HTML5 URLs and the `` -While the router uses the -HTML5 pushState -style by default, you *must* configure that strategy with a **base href**. - -The preferred way to configure the strategy is to add a -<base href> element -tag in the `` of the `index.html`. +While the router uses the HTML5 pushState style by default, you must configure that strategy with a ``. +The preferred way to configure the strategy is to add a <base href> element tag in the `` of the `index.html`. - - Without that tag, the browser may not be able to load resources (images, CSS, scripts) when "deep linking" into the app. -Bad things could happen when someone pastes an application link into the -browser's address bar or clicks such a link in an email. -Some developers may not be able to add the `` element, perhaps because they don't have -access to `` or the `index.html`. +Some developers may not be able to add the `` element, perhaps because they don't have access to `` or the `index.html`. -Those developers may still use HTML5 URLs by taking two remedial steps: +Those developers may still use HTML5 URLs by taking the following two steps: 1. Provide the router with an appropriate [APP_BASE_HREF][] value. -1. Use _root URLs_ for all web resources: CSS, images, scripts, and template HTML files. +1. Use root URLs for all web resources: CSS, images, scripts, and template HTML files. {@a hashlocationstrategy} -#### *HashLocationStrategy* - -You can go old-school with the `HashLocationStrategy` by -providing the `useHash: true` in an object as the second argument of the `RouterModule.forRoot()` -in the `AppModule`. +### `HashLocationStrategy` +You can use `HashLocationStrategy` by providing the `useHash: true` in an object as the second argument of the `RouterModule.forRoot()` in the `AppModule`. + +## Router Reference + +The folllowing sections highlight some core router concepts. + +{@a basics-router-imports} + +### Router imports + +The Angular Router is an optional service that presents a particular component view for a given URL. +It is not part of the Angular core and thus is in its own library package, `@angular/router`. + +Import what you need from it as you would from any other Angular package. + + + + +
    + +For more on browser URL styles, see [`LocationStrategy` and browser URL styles](#browser-url-styles). + +
    + +{@a basics-config} + +### Configuration + +A routed Angular application has one singleton instance of the `Router` service. +When the browser's URL changes, that router looks for a corresponding `Route` from which it can determine the component to display. + +A router has no routes until you configure it. +The following example creates five route definitions, configures the router via the `RouterModule.forRoot()` method, and adds the result to the `AppModule`'s `imports` array. + + + +{@a example-config} + +The `appRoutes` array of routes describes how to navigate. +Pass it to the `RouterModule.forRoot()` method in the module `imports` to configure the router. + +Each `Route` maps a URL `path` to a component. +There are no leading slashes in the path. +The router parses and builds the final URL for you, which allows you to use both relative and absolute paths when navigating between application views. + +The `:id` in the second route is a token for a route parameter. +In a URL such as `/hero/42`, "42" is the value of the `id` parameter. +The corresponding `HeroDetailComponent` uses that value to find and present the hero whose `id` is 42. + +The `data` property in the third route is a place to store arbitrary data associated with +this specific route. +The data property is accessible within each activated route. Use it to store items such as page titles, breadcrumb text, and other read-only, static data. +You can use the [resolve guard](#resolve-guard) to retrieve dynamic data. + +The empty path in the fourth route represents the default path for the application—the place to go when the path in the URL is empty, as it typically is at the start. +This default route redirects to the route for the `/heroes` URL and, therefore, displays the `HeroesListComponent`. + +If you need to see what events are happening during the navigation lifecycle, there is the `enableTracing` option as part of the router's default configuration. +This outputs each router event that took place during each navigation lifecycle to the browser console. +Use `enableTracing` only for debugging purposes. +You set the `enableTracing: true` option in the object passed as the second argument to the `RouterModule.forRoot()` method. + +{@a basics-router-outlet} + +### Router outlet + +The `RouterOutlet` is a directive from the router library that is used like a component. +It acts as a placeholder that marks the spot in the template where the router should +display the components for that outlet. + + + <router-outlet></router-outlet> + <!-- Routed components go here --> + + + +Given the configuration above, when the browser URL for this application becomes `/heroes`, the router matches that URL to the route path `/heroes` and displays the `HeroListComponent` as a sibling element to the `RouterOutlet` that you've placed in the host component's template. + +{@a basics-router-links} + +{@a router-link} + +### Router links + +To navigate as a result of some user action such as the click of an anchor tag, use `RouterLink`. + +Consider the following template: + + + +The `RouterLink` directives on the anchor tags give the router control over those elements. +The navigation paths are fixed, so you can assign a string to the `routerLink` (a "one-time" binding). + +Had the navigation path been more dynamic, you could have bound to a template expression that returned an array of route link parameters; that is, the [link parameters array](guide/router#link-parameters-array). +The router resolves that array into a complete URL. + +{@a router-link-active} + +### Active router links + +The `RouterLinkActive` directive toggles CSS classes for active `RouterLink` bindings based on the current `RouterState`. + +On each anchor tag, you see a [property binding](guide/template-syntax#property-binding) to the `RouterLinkActive` directive that looks like `routerLinkActive="..."`. + +The template expression to the right of the equal sign, `=`, contains a space-delimited string of CSS classes that the Router adds when this link is active (and removes when the link is inactive). +You set the `RouterLinkActive` directive to a string of classes such as `[routerLinkActive]="'active fluffy'"` or bind it to a component property that returns such a string. + +Active route links cascade down through each level of the route tree, so parent and child router links can be active at the same time. +To override this behavior, you can bind to the `[routerLinkActiveOptions]` input binding with the `{ exact: true }` expression. By using `{ exact: true }`, a given `RouterLink` will only be active if its URL is an exact match to the current URL. + +{@a basics-router-state} + +### Router state + +After the end of each successful navigation lifecycle, the router builds a tree of `ActivatedRoute` objects that make up the current state of the router. You can access the current `RouterState` from anywhere in the application using the `Router` service and the `routerState` property. + +Each `ActivatedRoute` in the `RouterState` provides methods to traverse up and down the route tree to get information from parent, child and sibling routes. + +{@a activated-route} + +### Activated route + +The route path and parameters are available through an injected router service called the [ActivatedRoute](api/router/ActivatedRoute). +It has a great deal of useful information including: + +
    • + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Property + + Description +
    + url + + + An `Observable` of the route path(s), represented as an array of strings for each part of the route path. + +
    + data + + + An `Observable` that contains the `data` object provided for the route. + Also contains any resolved values from the [resolve guard](#resolve-guard). + +
    + paramMap + + + An `Observable` that contains a [map](api/router/ParamMap) of the required and [optional parameters](#optional-route-parameters) specific to the route. + The map supports retrieving single and multiple values from the same parameter. + +
    + queryParamMap + + + An `Observable` that contains a [map](api/router/ParamMap) of the [query parameters](#query-parameters) available to all routes. + The map supports retrieving single and multiple values from the query parameter. + +
    + fragment + + + An `Observable` of the URL [fragment](#fragment) available to all routes. + +
    + outlet + + + The name of the `RouterOutlet` used to render the route. + For an unnamed outlet, the outlet name is primary. + +
    + routeConfig + + + The route configuration used for the route that contains the origin path. + +
    + parent + + + The route's parent `ActivatedRoute` when this route is a [child route](#child-routing-component). + +
    + firstChild + + + Contains the first `ActivatedRoute` in the list of this route's child routes. + +
    + children + + + Contains all the [child routes](#child-routing-component) activated under the current route. + +
    + +
    + +Two older properties are still available, however, their replacements are preferable as they may be deprecated in a future Angular version. + +* `params`: An `Observable` that contains the required and [optional parameters](#optional-route-parameters) specific to the route. Use `paramMap` instead. + +* `queryParams`: An `Observable` that contains the [query parameters](#query-parameters) available to all routes. +Use `queryParamMap` instead. + +
    + +### Router events + +During each navigation, the `Router` emits navigation events through the `Router.events` property. +These events range from when the navigation starts and ends to many points in between. The full list of navigation events is displayed in the table below. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Router Event + + Description +
    + NavigationStart + + + An [event](api/router/NavigationStart) triggered when navigation starts. + +
    + RouteConfigLoadStart + + + An [event](api/router/RouteConfigLoadStart) triggered before the `Router` + [lazy loads](#asynchronous-routing) a route configuration. + +
    + RouteConfigLoadEnd + + + An [event](api/router/RouteConfigLoadEnd) triggered after a route has been lazy loaded. + +
    + RoutesRecognized + + + An [event](api/router/RoutesRecognized) triggered when the Router parses the URL and the routes are recognized. + +
    + GuardsCheckStart + + + An [event](api/router/GuardsCheckStart) triggered when the Router begins the Guards phase of routing. + +
    + ChildActivationStart + + + An [event](api/router/ChildActivationStart) triggered when the Router begins activating a route's children. + +
    + ActivationStart + + + An [event](api/router/ActivationStart) triggered when the Router begins activating a route. + +
    + GuardsCheckEnd + + + An [event](api/router/GuardsCheckEnd) triggered when the Router finishes the Guards phase of routing successfully. + +
    + ResolveStart + + + An [event](api/router/ResolveStart) triggered when the Router begins the Resolve phase of routing. + +
    + ResolveEnd + + + An [event](api/router/ResolveEnd) triggered when the Router finishes the Resolve phase of routing successfuly. + +
    + ChildActivationEnd + + + An [event](api/router/ChildActivationEnd) triggered when the Router finishes activating a route's children. + +
    + ActivationEnd + + + An [event](api/router/ActivationStart) triggered when the Router finishes activating a route. + +
    + NavigationEnd + + + An [event](api/router/NavigationEnd) triggered when navigation ends successfully. + +
    + NavigationCancel + + + An [event](api/router/NavigationCancel) triggered when navigation is canceled. + This can happen when a [Route Guard](#guards) returns false during navigation, + or redirects by returning a `UrlTree`. + +
    + NavigationError + + + An [event](api/router/NavigationError) triggered when navigation fails due to an unexpected error. + +
    + Scroll + + + An [event](api/router/Scroll) that represents a scrolling event. + +
    + +When you enable the `enableTracing` option, Angular logs these events to the console. +For an example of filtering router navigation events, see the [router section](guide/observables-in-angular#router) of the [Observables in Angular](guide/observables-in-angular) guide. + +### Router terminology + +Here are the key `Router` terms and their meanings: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Router Part + + Meaning +
    + Router + + Displays the application component for the active URL. + Manages navigation from one component to the next. +
    + RouterModule + + A separate NgModule that provides the necessary service providers + and directives for navigating through application views. +
    + Routes + + Defines an array of Routes, each mapping a URL path to a component. +
    + Route + + Defines how the router should navigate to a component based on a URL pattern. + Most routes consist of a path and a component type. +
    + RouterOutlet + + The directive (<router-outlet>) that marks where the router displays a view. +
    + RouterLink + + The directive for binding a clickable HTML element to a route. Clicking an element with a routerLink directive that is bound to a string or a link parameters array triggers a navigation. +
    + RouterLinkActive + + The directive for adding/removing classes from an HTML element when an associated routerLink contained on or inside the element becomes active/inactive. +
    + ActivatedRoute + + A service that is provided to each route component that contains route specific information such as route parameters, static data, resolve data, global query params, and the global fragment. +
    + RouterState + + The current state of the router including a tree of the currently activated routes together with convenience methods for traversing the route tree. +
    + Link parameters array + + An array that the router interprets as a routing instruction. + You can bind that array to a RouterLink or pass the array as an argument to the Router.navigate method. +
    + Routing component + + An Angular component with a RouterOutlet that displays views based on router navigations. +
    diff --git a/aio/content/guide/testing.md b/aio/content/guide/testing.md index a42f78a4e4..b2f1d08a42 100644 --- a/aio/content/guide/testing.md +++ b/aio/content/guide/testing.md @@ -1958,7 +1958,7 @@ for the `id` to change during its lifetime.
    -The [Router](guide/router#route-parameters) guide covers `ActivatedRoute.paramMap` in more detail. +The [ActivatedRoute in action](guide/router#activated-route-in-action) section of the [Router](guide/router) guide covers `ActivatedRoute.paramMap` in more detail.