diff --git a/public/docs/_examples/router/ts/app/app.component.2.ts b/public/docs/_examples/router/ts/app/app.component.2.ts index fa3dfd11cf..ffd4d8dfae 100644 --- a/public/docs/_examples/router/ts/app/app.component.2.ts +++ b/public/docs/_examples/router/ts/app/app.component.2.ts @@ -1,6 +1,4 @@ /* Second Heroes version */ -// #docplaster - // #docregion import { Component } from '@angular/core'; diff --git a/public/docs/ts/latest/guide/router.jade b/public/docs/ts/latest/guide/router.jade index d258167d55..2ffa94f1b3 100644 --- a/public/docs/ts/latest/guide/router.jade +++ b/public/docs/ts/latest/guide/router.jade @@ -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 `` element to the `index.html` as the first child in the `` 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 routerLink directive - that is bound to a string or a Link Parameters Array triggers a navigation. + that is bound to a string or a link parameters array triggers a navigation. tr td RouterLinkActive 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 Link Parameters Array + td Link Parameters Array td. 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. tr - td Routing Component + td Routing Component td. An Angular component with a RouterOutlet 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 `` with a script that writes the `` 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 AppComponent 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 `` element. - The router inserts the outlet's view components as sibling elements, immediately _after_ the closing `` tag. + The router inserts the outlet's view components as sibling elements, + immediately _after_ the closing `` 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 RouterLinkActive 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 RouterLinkActive 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 Router Directives +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 Wildcard Routes :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 Wildcard Routes .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. - -.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. - -.l-main-section +.l-main-section#asynchronous-routing :marked ## Milestone #6: Asynchronous Routing