Skip to content

Home

Jump to bottom Edit New page
timkindberg edited this page Feb 25, 2013 · 50 revisions

Main Goal

To evolve the concept of an Angular "Route" into a more general concept of a "State" for managing coarse application UI states.

Main Features:

  1. A state manager $stateProvider and $state, keeps state logic separate from routing logic.
  2. Nested states (parent/child relationships).
  3. Can set multiple views via named views. ui-view directive.
  4. URL Routing
  5. Backwards compatible with Angular v1 router
  6. Various other nuggets of goodness

State Manager

The new $stateProvider works similar to Angular's v1 router, but it focuses purely on state.

  • A state corresponds to a "place" in the application in terms of the overall UI and navigation.
  • A state describes (via the controller / template / view properties) what the UI looks like and does at that place.
  • States often have things in common, and the primary way of factoring out these commonalities in this model is via the state hierarchy, i.e. parent/child states aka nested states.

The simplest form of state

A state in its simplest form can be added like this (typically within module.config):

<!-- in index.html -->
<body ng-controller="MainCtrl">
<section ui-view></section>
</body>
// in app-states.js (or whatever you want to name it)
$stateProvider.state('contacts', {
  template: '<h1>My Contacts</h1>'
}

// main-controller.js
function MainCtrl($state){
  $state.transitionTo('contacts');
}

The template is automatically placed into the lone ui-view when the state is transitioned to.

Alternative ways to set the Template

Instead of writing the template inline you can load a partial. This is probably how you'll set templates most of the time.

$stateProvider.state('contacts', {
  templateUrl: 'contacts.html'
}

Or you can use a template provider function which can be injected and has access to locals, like this:

$stateProvider.state('contacts', {
  templateProvider: function ($timeout, $stateParams) {
    return $timeout(function () { return '<h1>'+$stateParams.contactId+'</h1>' }, 100);
  }
}

Controllers

You can pair a template with a controller like this:

$stateProvider.state('contacts', {
  template: '<h1>{{title}}</h1>',
  controller: function($scope){
    $scope.title = 'My Contacts';
  }
}

Resolve

You can use resolve to provide your controller with content or data that is custom to the state. This allows you to reuse controllers for similar objects that needs different dependencies.

$stateProvider.state('contacts', {
  template: '<h1>{{title}}</h1>',
  resolve: { title: 'My Contacts' },
  controller: function($scope, title){
    $scope.title = title;
  }
}

onEnter and onExit callbacks

There are also optional 'onEnter' and 'onExit' callbacks that get called when a state becomes active and inactive respectively. The callbacks also have access to all the resolved dependencies.

$stateProvider.state("contacts", {
  template: '<h1>{{title}}</h1>',
  resolve: { title: 'My Contacts' },
  controller: function($scope, title){
    $scope.title = 'My Contacts';
  },
  onEnter: function(title){
    if(title){ ... do something ... }
  },
  onExit: function(title){
    if(title){ ... do something ... }
  }
}

Nested states

States can be nested within each other. You can specify nesting in several ways:

You can use dot syntax to infer your heirarchy to the $stateProvider. Below, contacts.list becomes a child of contacts.

$stateProvider
  .state('contacts', {});
  .state('contacts.list', {});

Alternately, you can specify the parent of a state via the parent property.

$stateProvider
  .state('contacts', {});
  .state('list', {
    parent: 'contacts'
  });

Object-based States

If you aren't fond of using string-based states, you can also use object-based states. The name property goes in the object and the parent property must be set on all child states, like this:

var contacts = { 
    name: 'contacts',  //mandatory
    templateUrl: 'contacts.html'
}
var contactsList = { 
    name: 'list',      //mandatory
    parent: contacts,  //mandatory
    templateUrl: 'contacts.list.html'
}

$stateProvider
  .state(contacts)
  .state(contactsList)

You can usually reference the object directly when using other methods and property comparisons:

$state.transitionTo(states.contacts);
$state.self === states.contacts;
$state.includes(states.contacts)

Attach Custom Data to State Objects

You can attach custom data to the state object (we recommend using a data property to avoid conflicts).

// Example shows an object-based state and a string-based state
var contacts = { 
    name: 'contacts',
    templateUrl: 'contacts.html',
    data: {
        customData1: 5,
        customData2: "blue"
    }  
}
$stateProvider
  .state(contacts)
  .state('contacts.list', {
    templateUrl: 'contacts.list.html',
    data: {
        customData1: 44,
        customData2: "red"
    } 
  })

With the above example states you could access the data like this:

function Ctrl($state){
    console.log($state.current.data.customData1) // outputs 5;
    console.log($state.current.data.customData2) // outputs "blue";
}

Nested views

Child states will load their templates into their parent's ui-view.

$stateProvider
  .state('contacts', {
    templateUrl: 'contacts.html'
    controller: function($scope){
      $scope.contacts = [{ name: 'Alice' }, { name: 'Bob' }];
    }
  })
  .state('contacts.list', {
    templateUrl: 'contacts.list.html';
  });

function MainCtrl($state){
  $state.transitionTo('contacts.list');
}
<!-- index.html -->
<body ng-controller="MainCtrl">
  <div ui-view></div>
</body>
<!-- contacts.html -->
<h1>My Contacts</h1>
<div ui-view></div>
<!-- contacts.list.html -->
<ul>
  <li ng-repeat="contact in contacts">
    <a>{{contact.name}}</a>
  </li>
</ul>

Inheritance from parent states

When the application is in a particular State (aka when a state is "active"), all it's ancestor states are implicitly active as well. In the sample, when "contacts.list" state is active, the "contacts" state is implicitly active as well. Child states inherit views (templates/controllers) and resolved dependencies from parent state(s), which they can override.

Here contacts.list and contacts.detail are both inheriting the controller from contacts:

$stateProvider
  .state('contacts', {
    template: '<h1>My Contacts</h1>'
    controller: function($scope){
      $scope.contacts = [{ name: "Alice", favpet: "Mouse" }, 
                         { name: "Bob", favpet: "Python" }];
    }
  })
  .state('contacts.list', {
    template: '<ul><li ng-repeat="contact in contacts">' +
                 '<a ui-state-ref="contacts.detail">{{contact.name}}</a>' +
              '</li></ul>';
  })
  .state('contacts.detail', {
    template: "{contact.name}}'s favorite pet is {{contact.favpet}}";
  });

Abstract States

An abstract state can have child states but can not get activated itself. An 'abstract' state is simply a state that can't be transitioned to, because it's simply there to provide some UI or dependencies that are common to it's child states.

Here is an example where the 'contacts' state is abstract. It's main purpose is to provide its child states with access to the $scope.contacts data. $scope.contacts will be available to both child state views for interpolation.

$stateProvider
    .state('contacts', {
        abstract: true,
        templateUrl: 'contacts.html',
        controller: function($scope){
            $scope.contacts = [{ name: "Alice" }, { name: "Bob" }];
    })
    .state('contacts.list', {
        templateUrl: 'contacts.list.html'
    })
    .state('contacts.detail', {
        templateUrl: 'contacts.detail.html'
    })

Multiple Named Views

You can name your views so that you can have more than one ui-view per state. Let's say you had an application state that needed to dynamically populate a graph, some table data and filters for the table like this: Multiple Named Views Mockup

When setting multiple views you need to use the views property on state. views is an object. The property keys on views should match your view names, like so:

<!-- somereportthing.html -->
<body>
  <div ui-view="filters"></div>
  <div ui-view="tabledata"></div>
  <div ui-view="graph"></div>
</body>
$stateProvider
  .state('report', {
    views: {
      'filters': { ... templates, controllers, resolve, etc ... },
      'tabledata': {},
      'graph': {},
    }
  })

Then each view in views is can set up its own templates, controllers, and resolve data.

$stateProvider
  .state('report',{
    views: {
      'filters': {
        templateUrl: 'report-filters.html',
        controller: function($scope){ ... controller stuff just for filters view ... }
      },
      'tabledata': {
        templateUrl: 'report-table.html',
        controller: function($scope){ ... controller stuff just for tabledata view ... }
      },
      'graph': {
        templateUrl: 'report-graph.html',
        controller: function($scope){ ... controller stuff just for graph view ... }
      },
    }
  })

View Names

Every view gets assigned an absolute name that follows a scheme of viewname@statename, where viewname is the name used in the view directive and state name is the state's absolute name, e.g. contact.item. The previous example could also be written as such:

  .state('report',{
    views: {
      'filters@report': {
        templateUrl: 'report-filters.html',
        controller: function($scope){ ... controller stuff just for filters view ... }
      },
      ... other views ...

Notice that the view name is now specified as the absolute name, as opposed to the relative name. It is targeting the 'filters' view located in the 'report' state. This let's us do some powerful view targeting. Let's assume we had several nested views set up like this (this example is not realistic, its just to illustrate view targeting):

<!-- index.html -->
<body ng-app>
<div ui-view></div> <!-- Assume contacts.html plugs in here -->
<div ui-view="status"></div>
</body>
<!-- contacts.html -->
<h1>My Contacts</h1>
<div ui-view></div>
<div ui-view="detail"></div> <!-- Assume contacts.detail.html plugs in here -->
<!-- contacts.detail.html -->
<h1>Contacts Details</h1>
<div ui-view></div>
<div ui-view="info"></div>

Let's look at the various views you could target from within the contacts.detail state. Remember that if an @ is used then the view path is considered absolute:

$stateProvider
  .state('contacts.detail', {
    templateUrl: 'contacts.detail.html'
    views: {
        "info" : {}            // relatively targets the "info" view in "contacts.detail" state
        "" : {}                // relatively targets the unnamed view in "contacts.detail" state
        "detail@contacts" : {} // absolutely targets the "detail" view in parent "contacts" state
        "@contacts" : {}       // absolutely targets the unnamed view in parent "contacts" state
        "status@" : {}         // absolutely targets the "status" view in root unnamed state
        "@" : {}               // absolutely targets the unnamed view in root unnamed state
  });

You can see how this ability to not only set multiple views within the same state but ancestor states could become a veritable playground for developer :).

URL Routing

Most states in your application will probably have a url associated with them. URL Routing was not an after thought to the state mechanics, but was figured into the design from the beginning (all while keeping states separate from url routing)

Here's how you set a basic url.

$stateProvider
    .state('contacts', {
        url: "/contacts",
        templateUrl: 'contacts.html'
    })

Now when the user accesses index.html/contacts then the 'contacts' state would become active and the main ui-view will be populated with the 'contacts.html' partial. Alternatively, if the user were to transition to the 'contacts' state via transitionTo('contacts') then the url would be updated to index.html/contacts

URL Parameters

Often, URLs have dynamic parts to them which are called parameters. There are several options for specifying parameters. A basic parameter looks like this:

$stateProvider
    .state('contacts.detail', {
        url: "/contacts/:contactId",
        templateUrl: 'contacts.detail.html',
        controller: function ($stateParams) {
            // If we got here from a url of /contacts/42
            expect($stateParams).toBe({contactId: 42});
        }]
    })

Alternatively you can also use curly brackets:

// identical to previous example
url: "/contacts/{contactId}"

However, a bonus to using curly brackets is the ability to set a Regular Expression rule for the parameter:

// will only match a contactId of one to eight number characters
url: "/contacts/{contactId:[0-9]{1,8}}"

$stateParams Service

As you saw previously the $stateParams service is an object that will have one key per url parameter. The $stateParams is a perfect way to provide your controllers or other services with the individual parts of the navigated url.

// If you had a url on your state of:
url: '/users/:id/details/{type}/{repeat:[0-9]+}?from&to'

// Then you navigated your browser to:
'/users/123/details//0'

// Your $stateParams object would be
{ id:'123', type:'', repeat:'0' }

// Then you navigated your browser to:
'/users/123/details/default/0?from=there&to=here'

// Your $stateParams object would be
{ id:'123', type:'default', repeat:'0', from='there', to='here' }

Use the table of contents to the top right to navigate to other wiki sections.

Quick Overview

In-Depth Guide

Tips and Tricks

Clone this wiki locally