Routing Overview 4.0


This is a DRAFT of the router pages, which are still being actively updated. Most of the content is accurate, but the sample is still being reworked and enhanced. Feedback is welcome.

The Angular router enables navigation from one view to the next as users perform app tasks.

This guide covers the router’s primary features, illustrating them through the evolution of a small app that you can run live.

Overview

The browser is a familiar model of app navigation:

  • 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.

The Angular 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 app 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.

Adding angular_router

Router functionality is in the angular_router library, which comes in its own package. Add the package to the pubspec dependencies:

pubspec.yaml (dependencies)

dependencies: angular: ^4.0.0 angular_router: ^1.0.2

In any Dart file that makes use of router features, import the router library:

import 'package:angular_router/angular_router.dart';

Basic feature overview

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. This overview of core router concepts will help orient you to the details that follow.

<base href>

Most routing apps have a <base href="..."> element in the index.html <head> to tell the router how to compose navigation URLs. For details, see Set the base href.

Configuration

When the browser’s URL changes, the router looks for a corresponding RouteDefinition from which it can determine the component to display.

A router has no routes until you configure it. The following example creates some route definitions. It illustrates the preferred way of simultaneously creating a router and adding its routes using a @RouteConfig applied to the router’s host component:

lib/app_component.dart (routes)

@Component( selector: 'my-app', // ··· ) @RouteConfig(const [ const Route( path: '/crisis-center', name: 'CrisisCenter', component: CrisisCenterComponent), const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent) ]) class AppComponent {}

There are several flavors of RouteDefinition. The most common, illustrated above, is a named Route which maps a URL path to a component.

Router outlet

When the browser URL for this app becomes /#/heroes, the router matches that URL to the RouteDefinition named Heroes and displays the HeroesComponent after a RouterOutlet that you’ve placed in the host view’s HTML.

<router-outlet></router-outlet> <!-- Routed views go here -->

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.

Consider the following template:

lib/app_component.dart (template and styles)

template: ''' <h1>Angular Router</h1> <nav> <a [routerLink]="['CrisisCenter']">Crisis Center</a> <a [routerLink]="['Heroes']">Heroes</a> </nav> <router-outlet></router-outlet> ''', styles: const ['.router-link-active {color: #039be5;}'],

The RouterLink directives on the anchor tags give the router control over those elements. You bind each RouterLink directive to a template expression that returns the route link parameters as a link parameters list. The router resolves each link parameters list into a complete URL.

The RouterLink directive also helps visually distinguish the anchor for the currently selected active route. The router adds the router-link-active CSS class to the element when the associated router link becomes active. As illustrated above, you can define this style alongside the template in the @Component annotation of the AppComponent.

Summary

The app has a configured router. The shell component has a RouterOutlet where it can display views produced by the router. It has RouterLinks that users can click to navigate via the router.

Here are the key router terms and their meanings:

Router Part Meaning
Router Displays the app component for the active URL. Manages navigation from one component to the next.
@RouteConfig Configures a router with a RouteDefinition list.
RouteDefinition Defines how the router should navigate to a component based on a URL pattern.
Route A kind of RouteDefinition. Defines how the router should navigate to a component based on a URL pattern. Most routes consist of a path, a route name, and a component type.
RouterOutlet The directive (<router-outlet>) that marks where the router should display 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 link parameters list triggers a navigation.
Link parameters list A list that the router interprets as a routing instruction. You can bind that list to a RouterLink or pass the list as an argument to the Router.navigate method.
Routing component An Angular component with a RouterOutlet that displays views based on router navigations.

The sample app

This guide describes the development of a multi-page routed sample app. Along the way, it highlights design decisions and describes key features of the router.

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 app construction that are more thoroughly covered elsewhere in the documentation.

The full source for the final version of the app can be seen and downloaded from the .

The sample app in action

Imagine an app that helps the Hero Employment Agency run its business. Heroes need work and the agency finds crises for them to solve.

The app has these main features:

  1. A Crisis Center for maintaining the list of crises for assignment to heroes.
  2. A Heroes area for maintaining the list of heroes employed by the agency.

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.

Hero List

Select one hero and the app takes you to a hero editing screen.

Crisis Center Detail

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. Angular app navigation updates the browser history as normal web navigation does.

Now click the Crisis Center link for a list of ongoing crises.

Crisis Center List

Select a crisis and the app takes you to a crisis editing screen. The Crisis Detail appears in a child view on the same page, beneath the list.

Alter the name of a crisis. Notice that the corresponding name in the crisis list does not change.

Crisis Center Detail

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.

Confirm Dialog

You can select “OK” and lose your changes or click “Cancel” and continue editing.

Behind this behavior is the router’s routerCanDeactivate hook. The hook gives you a chance to clean-up or ask the user’s permission before navigating away from the current view.