docs(router): copyedits (#3025)
This commit is contained in:
Patrice Chalin
Ward Bell
parent
223556fb2c
commit
ec2b07ef8c
@ -1,6 +1,4 @@
|
||||
/* Second Heroes version */
|
||||
// #docplaster
|
||||
|
||||
// #docregion
|
||||
import { Component } from '@angular/core';
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ include ../../../_includes/_see-addr-bar
|
||||
* Click the browser's back and forward buttons and the browser navigates
|
||||
backward and forward through the history of pages you've seen.
|
||||
|
||||
The Angular *`Router` ("the router") borrows from this model.
|
||||
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
|
||||
@ -32,35 +32,35 @@ include ../../../_includes/_see-addr-bar
|
||||
|
||||
* Setting the [base href](#base-href)
|
||||
* Importing from the [router library](#import)
|
||||
* [configuring the router](#route-config)
|
||||
* handling unmatched URLs with a [wildcard route](#wildcard-route)
|
||||
* the [link parameters array](#link-parameters-array) that propels router navigation
|
||||
* setting the [default route](#default-route) where the application navigates at launch
|
||||
* [redirecting](#redirect) from one route to another
|
||||
* navigating when the user clicks a data-bound [RouterLink](#router-link)
|
||||
* navigating under [program control](#navigate)
|
||||
* retrieving information from the [route](#activated-route)
|
||||
* [animating](#route-animation) transitions for route components
|
||||
* navigating [relative](#relative-navigation) to the current URL
|
||||
* toggling css classes for the [active router link](#router-link-active)
|
||||
* embedding critical information in the URL with [route parameters](#route-parameters)
|
||||
* providing non-critical information in [optional route parameters](#optional-route-parameters)
|
||||
* refactoring routing into a [routing module](#routing-module)
|
||||
* add [child routes](#child-routing-component) under a feature section
|
||||
* [grouping child routes](#component-less-route) without a component
|
||||
* displaying [multiple routes](#named-outlets) in separate outlets
|
||||
* confirming or canceling navigation with [guards](#guards)
|
||||
* [Configuring the router](#route-config)
|
||||
* Handling unmatched URLs with a [wildcard route](#wildcard-route)
|
||||
* The [link parameters array](#link-parameters-array) that propels router navigation
|
||||
* Setting the [default route](#default-route) where the application navigates at launch
|
||||
* [Redirecting](#redirect) from one route to another
|
||||
* Navigating when the user clicks a data-bound [RouterLink](#router-link)
|
||||
* Navigating under [program control](#navigate)
|
||||
* Retrieving information from the [route](#activated-route)
|
||||
* [Animating](#route-animation) transitions for route components
|
||||
* Navigating [relative](#relative-navigation) to the current URL
|
||||
* Toggling css classes for the [active router link](#router-link-active)
|
||||
* Embedding critical information in the URL with [route parameters](#route-parameters)
|
||||
* Providing non-critical information in [optional route parameters](#optional-route-parameters)
|
||||
* Refactoring routing into a [routing module](#routing-module)
|
||||
* Add [child routes](#child-routing-component) under a feature section
|
||||
* [Grouping child routes](#component-less-route) without a component
|
||||
* Displaying [multiple routes](#named-outlets) in separate outlets
|
||||
* Confirming or canceling navigation with [guards](#guards)
|
||||
* [CanActivate](#can-activate-guard) to prevent navigation to a route
|
||||
* [CanActivateChild](#can-activate-child-guard) to prevent navigation to a child route
|
||||
* [CanDeactivate](#can-deactivate-guard) to prevent navigation away from the current route
|
||||
* [Resolve](#resolve-guard) to pre-fetch data before activating a route
|
||||
* [CanLoad](#can-load-guard) to prevent asynchronous routing
|
||||
* providing optional information across routes with [query parameters](#query-parameters)
|
||||
* jumping to anchor elements using a [fragment](#fragment)
|
||||
* loading feature areas [asynchronously](#asynchronous-routing)
|
||||
* preloading feature areas [during navigation](#preloading)
|
||||
* using a [custom strategy](#custom-preloading) to only preload certain features
|
||||
* choosing the "HTML5" or "hash" [URL style](#browser-url-styles)
|
||||
* Providing optional information across routes with [query parameters](#query-parameters)
|
||||
* Jumping to anchor elements using a [fragment](#fragment)
|
||||
* Loading feature areas [asynchronously](#asynchronous-routing)
|
||||
* Preloading feature areas [during navigation](#preloading)
|
||||
* Using a [custom strategy](#custom-preloading) to only preload certain features
|
||||
* Choosing the "HTML5" or "hash" [URL style](#browser-url-styles)
|
||||
|
||||
.l-main-section
|
||||
:marked
|
||||
@ -69,10 +69,11 @@ include ../../../_includes/_see-addr-bar
|
||||
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.
|
||||
|
||||
An introduction to a few core Router concepts will help orient you to the details that follow.
|
||||
An introduction to a few core router concepts will help orient you to the details that follow.
|
||||
|
||||
:marked
|
||||
### *<base href>*
|
||||
|
||||
Most routing applications should add a `<base>` element to the `index.html` as the first child in the `<head>` tag
|
||||
to tell the router how to compose navigation URLs.
|
||||
|
||||
@ -83,6 +84,7 @@ include ../../../_includes/_see-addr-bar
|
||||
|
||||
:marked
|
||||
### 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.
|
||||
@ -94,6 +96,7 @@ include ../../../_includes/_see-addr-bar
|
||||
You'll learn about more options in the [details below](#browser-url-styles).
|
||||
:marked
|
||||
### 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.
|
||||
@ -140,14 +143,18 @@ a#example-config
|
||||
|
||||
:marked
|
||||
### Router Outlet
|
||||
|
||||
Given this configuration, when the browser URL for this application becomes `/heroes`,
|
||||
the router matches that URL to the route path `/heroes` and displays the `HeroListComponent`
|
||||
_after_ a `RouterOutlet` that you've placed in the host view's HTML.
|
||||
|
||||
code-example(language="html").
|
||||
<router-outlet></router-outlet>
|
||||
<!-- Routed views go here -->
|
||||
|
||||
:marked
|
||||
### Router Links
|
||||
|
||||
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
|
||||
@ -157,7 +164,7 @@ code-example(language="html").
|
||||
|
||||
+makeExcerpt('app/app.component.1.ts', 'template', '')
|
||||
:marked
|
||||
The `RouterLink` directive on the anchor tags gives the router control over those elements.
|
||||
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
|
||||
@ -170,6 +177,7 @@ code-example(language="html").
|
||||
|
||||
:marked
|
||||
### 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.
|
||||
@ -218,7 +226,7 @@ table
|
||||
td.
|
||||
The directive for binding a clickable HTML element to
|
||||
a route. Clicking an anchor tag with a <code>routerLink</code> directive
|
||||
that is bound to a <i>string</i> or a <i>Link Parameters Array</i> triggers a navigation.
|
||||
that is bound to a <i>string</i> or a <i>link parameters array</i> triggers a navigation.
|
||||
tr
|
||||
td <code>RouterLinkActive</code>
|
||||
td.
|
||||
@ -235,17 +243,16 @@ table
|
||||
The current state of the router including a tree of the currently activated
|
||||
routes together with convenience methods for traversing the route tree.
|
||||
tr
|
||||
td <code><i>Link Parameters Array</i></code>
|
||||
td <b><i>Link Parameters Array</i></b>
|
||||
td.
|
||||
An array that the router interprets as a routing instruction.
|
||||
You can bind that array to a <code>RouterLink</code> or pass the array as an argument to
|
||||
the <code>Router.navigate</code> method.
|
||||
tr
|
||||
td <code><i>Routing Component</i></code>
|
||||
td <b><i>Routing Component</i></b>
|
||||
td.
|
||||
An Angular component with a <code>RouterOutlet</code> that displays views based on router navigations.
|
||||
|
||||
a#getting-started
|
||||
.l-main-section
|
||||
:marked
|
||||
## The Sample Application
|
||||
@ -302,8 +309,10 @@ figure.image-display
|
||||
Angular app navigation updates the browser history as normal web navigation does.
|
||||
|
||||
Now click the *Crisis Center* link for a list of ongoing crises.
|
||||
|
||||
figure.image-display
|
||||
img(src='/resources/images/devguide/router/crisis-center-list.png' alt="Crisis Center List" width="250")
|
||||
|
||||
:marked
|
||||
Select a crisis and the application takes you to a crisis editing screen.
|
||||
The _Crisis Detail_ appears in a child view on the same page, beneath the list.
|
||||
@ -313,6 +322,7 @@ figure.image-display
|
||||
|
||||
figure.image-display
|
||||
img(src='/resources/images/devguide/router/crisis-center-detail.png' alt="Crisis Center Detail" width="250")
|
||||
|
||||
:marked
|
||||
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.
|
||||
@ -322,6 +332,7 @@ figure.image-display
|
||||
Click the browser back button or the "Heroes" link instead.
|
||||
|
||||
Up pops a dialog box.
|
||||
|
||||
figure.image-display
|
||||
img(src='/resources/images/devguide/router/confirm-dialog.png' alt="Confirm Dialog" width="250")
|
||||
|
||||
@ -336,18 +347,19 @@ figure.image-display
|
||||
|
||||
Proceed to the first application milestone.
|
||||
|
||||
.l-main-section
|
||||
.l-main-section#getting-started
|
||||
:marked
|
||||
## Milestone #1: Getting Started with the Router
|
||||
|
||||
Begin with a simple version of the app that navigates between two empty views.
|
||||
figure.image-display
|
||||
img(src='/resources/images/devguide/router/router-1-anim.gif' width="250px" alt="App in action" )
|
||||
img(src='/resources/images/devguide/router/router-1-anim.gif' alt="App in action" width="250")
|
||||
|
||||
a#base-href
|
||||
:marked
|
||||
### Set the *<base href>*
|
||||
The Router uses the browser's
|
||||
|
||||
The router uses the browser's
|
||||
[history.pushState](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Adding_and_modifying_history_entries)
|
||||
for navigation. Thanks to `pushState`, you can make in-app URL paths look the way you want them to
|
||||
look, e.g. `localhost:3000/crisis-center`. The in-app URLs can be indistinguishable from server URLs.
|
||||
@ -373,14 +385,15 @@ a#base-href
|
||||
|
||||
+makeExcerpt('index.html', 'base-href')
|
||||
|
||||
:marked
|
||||
.l-sub-section
|
||||
.callout.is-important
|
||||
header Live example note
|
||||
:marked
|
||||
#### Live example note
|
||||
A live coding environment like Plunker sets the application base address dynamically so you can't specify a fixed address.
|
||||
That's why the example code replaces the `<base href...>` with a script that writes the `<base>` tag on the fly.
|
||||
code-example(format="")
|
||||
|
||||
code-example(language="html").
|
||||
<script>document.write('<base href="' + document.location + '" />');</script>
|
||||
|
||||
:marked
|
||||
You should only need this trick for the live example, not production code.
|
||||
|
||||
@ -389,7 +402,6 @@ a#import
|
||||
### Configure the routes for the Router
|
||||
|
||||
Begin by importing some symbols from the router library.
|
||||
|
||||
The Router is in its own `@angular/router` package.
|
||||
It's not part of the Angular core. The router is an optional service because not all applications
|
||||
need routing and, depending on your requirements, you may need a different routing library.
|
||||
@ -397,8 +409,9 @@ a#import
|
||||
You teach the router how to navigate by configuring it with routes.
|
||||
|
||||
a#route-config
|
||||
h4#define-routes Define routes
|
||||
:marked
|
||||
#### Define routes
|
||||
|
||||
A router must be configured with a list of route definitions.
|
||||
|
||||
The first configuration defines an array of two routes with simple paths leading to the
|
||||
@ -411,13 +424,14 @@ h4#define-routes Define routes
|
||||
The router draws upon its registry of such route definitions when the browser URL changes
|
||||
or when application code tells the router to navigate along a route path.
|
||||
|
||||
In plain English, you might say of the first route:
|
||||
* *When the browser's location URL changes to match the path segment `/crisis-center`, create or retrieve an instance of
|
||||
the `CrisisListComponent` and display its view.*
|
||||
In simpler terms, you might say of the first route:
|
||||
|
||||
* *When the application requests navigation to the path `/crisis-center`, create or retrieve an instance of
|
||||
- When the browser's location URL changes to match the path segment `/crisis-center`, create or retrieve an instance of
|
||||
the `CrisisListComponent` and display its view.
|
||||
|
||||
- When the application requests navigation to the path `/crisis-center`, create or retrieve an instance of
|
||||
the `CrisisListComponent`, display its view, and update the browser's address location and history with the URL
|
||||
for that path.*
|
||||
for that path.
|
||||
|
||||
:marked
|
||||
Here is the first configuration. Pass the array of routes to the `RouterModule.forRoot` method.
|
||||
@ -436,10 +450,13 @@ h4#define-routes Define routes
|
||||
:marked
|
||||
Providing the `RouterModule` in the `AppModule` makes the Router available everywhere in the application.
|
||||
|
||||
h3#shell The <i>AppComponent</i> shell
|
||||
a#shell
|
||||
:marked
|
||||
### The *AppComponent* shell
|
||||
|
||||
The root `AppComponent` is the application shell. It has a title at the top, a navigation bar with two links,
|
||||
and a *Router Outlet* at the bottom where the router swaps views on and off the page. Here's what you mean:
|
||||
and a *router outlet* at the bottom where the router swaps views on and off the page. Here's what you get:
|
||||
|
||||
figure.image-display
|
||||
img(src='/resources/images/devguide/router/shell-and-outlet.png' alt="Shell" width="300" )
|
||||
|
||||
@ -455,16 +472,19 @@ a#router-outlet
|
||||
|
||||
The `RouterOutlet` is a directive from the router library that marks
|
||||
the spot in the template where the router should display the views for that outlet.
|
||||
|
||||
.l-sub-section
|
||||
:marked
|
||||
It renders in the the DOM as a `<router-outlet>` element.
|
||||
The router inserts the outlet's view components as sibling elements, immediately _after_ the closing `</router-outlet>` tag.
|
||||
The router inserts the outlet's view components as sibling elements,
|
||||
immediately _after_ the closing `</router-outlet>` tag.
|
||||
|
||||
a#router-link
|
||||
:marked
|
||||
### *RouterLink* binding
|
||||
|
||||
Above the outlet, within the anchor tags, you see [Property Bindings](template-syntax.html#property-binding) to
|
||||
Above the outlet, within the anchor tags, you see
|
||||
[attribute bindings](template-syntax.html#attribute-binding) to
|
||||
the `RouterLink` directive that look like `routerLink="..."`.
|
||||
|
||||
The links in this example each have a string path, the path of a route that
|
||||
@ -479,8 +499,9 @@ a#router-link
|
||||
Learn about the how you can also use the _link parameters array_ in the [appendix below](#link-parameters-array).
|
||||
|
||||
a#router-link-active
|
||||
h3#router-link <i>RouterLinkActive</i> binding
|
||||
:marked
|
||||
### *RouterLinkActive* binding
|
||||
|
||||
On each anchor tag, you also see [Property Bindings](template-syntax.html#property-binding) to
|
||||
the `RouterLinkActive` directive that look like `routerLinkActive="..."`.
|
||||
|
||||
@ -494,17 +515,20 @@ h3#router-link <i>RouterLinkActive</i> binding
|
||||
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.
|
||||
|
||||
h3#router-directives <i>Router Directives</i>
|
||||
a#router-directives
|
||||
:marked
|
||||
### *Router Directives*
|
||||
|
||||
`RouterLink`, `RouterLinkActive` and `RouterOutlet` are directives provided by the Angular `RouterModule` package.
|
||||
They are readily available for you to use in the template.
|
||||
:marked
|
||||
|
||||
The current state of `app.component.ts` looks like this:
|
||||
|
||||
+makeExcerpt('app/app.component.1.ts')
|
||||
|
||||
h3#wildcard-route <i>Wildcard Routes</i>
|
||||
:marked
|
||||
### 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.
|
||||
|
||||
@ -515,7 +539,7 @@ h3#wildcard-route <i>Wildcard Routes</i>
|
||||
|
||||
.l-sub-section
|
||||
:marked
|
||||
The `Router` selects the route with a [_first match wins_](#example-config) strategy.
|
||||
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.
|
||||
|
||||
@ -606,6 +630,7 @@ a#redirect
|
||||
when the user clicks a link.
|
||||
|
||||
You've learned how to
|
||||
|
||||
* 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
|
||||
@ -618,6 +643,7 @@ a#redirect
|
||||
Here are the details for readers inclined to build the sample through to this milestone.
|
||||
|
||||
The starter app's structure looks like this:
|
||||
|
||||
.filetree
|
||||
.file router-sample
|
||||
.children
|
||||
@ -748,7 +774,7 @@ a#why-routing-module
|
||||
and add *Hero Management* feature files there.
|
||||
|
||||
This example is pretty much a copy of the code and capabilities in the "[Tutorial: Tour of Heroes](../tutorial/index.html)".
|
||||
There's not need to be more creative.
|
||||
There's no need to be more creative.
|
||||
|
||||
Here's how the user will experience this version of the app
|
||||
figure.image-display
|
||||
@ -1752,9 +1778,7 @@ a#clear-secondary-routes
|
||||
This time, the value of `'popup'` is `null`. That's not a route, but it is a legitimate value.
|
||||
Setting _popup_ `RouterOutlet` to `null` clears the outlet and removes the secondary "popup" route from the current URL.
|
||||
|
||||
<a id="guards"></a>
|
||||
.l-main-section
|
||||
h2#guards Route Guards
|
||||
.l-main-section#guards
|
||||
:marked
|
||||
## Milestone #5: Route Guards
|
||||
|
||||
@ -2261,8 +2285,7 @@ include ../../../_includes/_see-addr-bar
|
||||
The `query params` and `fragment` can also be preserved using a `RouterLink` with
|
||||
the `preserveQueryParams` and `preserveFragment` bindings respectively.
|
||||
|
||||
<a id="asynchronous-routing"></a>
|
||||
.l-main-section
|
||||
.l-main-section#asynchronous-routing
|
||||
:marked
|
||||
## Milestone #6: Asynchronous Routing
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user