Permalink
Fetching contributors…
Cannot retrieve contributors at this time
268 lines (213 sloc) 10.9 KB
title description sideNavGroup prevpage nextpage
Routing Overview
Overview of core router features
advanced
title url
Pipes
/angular/guide/pipes
title url
Routing Basics
/angular/guide/router/1

{%- assign pageUrl = page.url | regex_replace: '/index$|/index.html$|/$' -%}

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.

[Feedback]: {{site.repo.this}}/issues/new?title='{{page.title}}' page issue&body=From URL: {{site.url}}{{page.url}}

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 {% example_ref text="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.

{% comment %} //- Skip this for now; might drop it altogether anyways You'll learn many router details in this guide which covers

[After the Embedding entry above, the TS page has the following list]

Setup overview

Add angular_router

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

  dependencies:
    angular: ^5.2.0
    # ···
    [!angular_router: ^2.0.0-alpha+21!]

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

  import 'package:angular_router/angular_router.dart';

Register providers and list directives

If you're already familiar with Angular routing, here's a reminder of what you need to do:

Basic feature overview

This guide proceeds in phases, marked by milestones, starting from a skeletal app 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.

Routes

Routes tell the router which views to display when a user clicks a link or pastes a URL into the browser address bar. To configure routes you'll need to do the following:

  • Define [route paths]({{pageUrl}}/1#route-paths):
      import 'package:angular_router/angular_router.dart';
    
      class RoutePaths {
        static final heroes = RoutePath(path: 'heroes');
      }
    
  • Define [route definitions]({{pageUrl}}/1#route-definitions):
      import 'package:angular_router/angular_router.dart';
    
      import 'route_paths.dart';
      import 'hero_list_component.template.dart' as hero_list_template;
    
      export 'route_paths.dart';
    
      class Routes {
        static final heroes = RouteDefinition(
          routePath: RoutePaths.heroes,
          component: hero_list_template.HeroListComponentNgFactory,
        );
    
        static final all = <RouteDefinition>[
          heroes,
        ];
      }
    
  • Bind the route definitions to a _router outlet_, as illustrated next.

Router outlet

When you visit localhost:8080/#/heroes{:.no-automatic-external}, the router matches the URL with the heroes route path, and displays a HeroListComponent immediately below the <router-outlet> in the routing component template:

  import 'src/routes.dart';

  @Component(
    template: '''
      ...
      [!<router-outlet [routes]="Routes.all"></router-outlet>!]
    ''',
    directives: [routerDirectives],
    exports: [RoutePaths, Routes],
  )
  class AppComponent {
  }

For details, see RouterOutlet.

Router links

A RouterLink directive on an anchor tag gives the router control over the anchor. Bind each RouterLink directive to a template expression that evaluates to a URL.

  template: '''
    <h1>Angular Router</h1>
    <nav>
      <a [![routerLink]!]="RoutePaths.crises.toUrl()"
         [![routerLinkActive]!]="'active-route'">Crisis Center</a>
      <a [![routerLink]!]="RoutePaths.heroes.toUrl()"
         [![routerLinkActive]!]="'active-route'">Heroes</a>
    </nav>
    <router-outlet [routes]="Routes.all"></router-outlet>
  ''',
  styles: ['.active-route {color: #039be5}'],

A RouterLinkActive will apply the named CSS class to the anchor whose link is active. This helps visually distinguish the active links.

For details, see RouterLinks.

Summary

Here are the key router terms and their meanings.

{:.table .table-striped} | Router Part | Meaning | | Router | Displays the app component for the active URL. Manages navigation from one component to the next. | | Routing component | An Angular component with a <router-outlet> that displays views based on router navigations. | | 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. | | RouteDefinition | Defines how the router should navigate to a component based on a URL pattern. | | RouterOutlet | The directive (<router-outlet>) that marks where the router should display a views. | | RouterLink | The directive for binding a clickable HTML element to a route. Clicking an element with a routerLink directive triggers a navigation. |

What next?

The rest of this guide describes the development of a {% example_ref text="multi-page routed app" %} through a sequence of milestones. Each milestone highlights specific design decisions and introduces new key features of the router.