diff --git a/aio/content/guide/router.en.md b/aio/content/guide/router.en.md new file mode 100644 index 0000000000000..030041c749bad --- /dev/null +++ b/aio/content/guide/router.en.md @@ -0,0 +1,1216 @@ +# In-app navigation: routing to views + +In a single-page app, you change what the user sees by showing or hiding portions of the display that correspond to particular components, rather than going out to the server to get a new page. +As users perform application tasks, they need to move between the different [views](guide/glossary#view "Definition of view") that you have defined. + +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 + +Before creating a route, you should be familiar with the following: + +- [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). + +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. + +{@a basics} + +## Generate an app with routing enabled + +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`. + + + ng new routing-app --routing + + +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} + +
+ +#### `` + +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 `"/"`. + + + +
+ +### Importing your new components + +To use your new components, import them into `AppRoutingModule` at the top of the file, as follows: + + + +import { FirstComponent } from './first/first.component'; +import { SecondComponent } from './second/second.component'; + + + +{@a basic-route} + +## Defining a basic route + +There are three fundamental building blocks to creating a route. + +Import the `AppRoutingModule` into `AppModule` and add it to the `imports` array. + +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. + + + + + +1. Import `RouterModule` and `Routes` into your routing module. + +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()`. + + + + + +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. + + + + + +1. Add your routes to your application. + +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. + + + +{@a route-order} + +### Route order + +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 getting-route-information} + +## Getting route information + +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. + +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. + + + + + These `import` statements add several important elements that your component needs. + To learn more about each, see the following API pages: + + - [`Router`](api/router) + - [`ActivatedRoute`](api/router/ActivatedRoute) + - [`ParamMap`](api/router/ParamMap) + +2. Inject an instance of `ActivatedRoute` by adding it to your application's constructor: + + + + +3. Update the `ngOnInit()` method to access the `ActivatedRoute` and track the `id` parameter: + + + ngOnInit() { + this.route.queryParams.subscribe(params => { + this.name = params['name']; + }); + } + + + Note: The preceding example uses a variable, `name`, and assigns it the value based on the `name` parameter. + +{@a setting-up-wildcard-routes} + +## Setting up wildcard routes + +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. + +To set up a wildcard route, add the following code to your `routes` definition. + + + +{ path: '\*\*', component: } + + + +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). + +{@a 404-page-how-to} + +## Displaying a 404 page + +To display a 404 page, set up a [wildcard route](guide/router#setting-up-wildcard-routes) 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`. + +## Setting up redirects + +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. + + + + + +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-tutorial-toh#pathmatch). + +{@a nesting-routes} + +## Nesting routes + +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`. + +In this example, there are two additional child components, `child-a`, and `child-b`. +Here, `FirstComponent` has its own `