-
Notifications
You must be signed in to change notification settings - Fork 0
Home
To evolve the concept of an Angular "Route" into a more general concept of a "State" for managing coarse application UI states.
- A state manager
$stateProvider
and$state
, keeps state logic separate from routing logic. - Nested states (parent/child relationships).
- Can set multiple views via named views.
ui-view
directive. - URL Routing
- Backwards compatible with Angular v1 router
- Various other nuggets of goodness
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.
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.
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) {
return $timeout(function () { return '<h1>My Contacts</h1>' }, 100);
}
}
You can pair a template with a controller like this:
$stateProvider.state('contacts', {
template: '<h1>{{title}}</h1>',
controller: function($scope){
$scope.title = 'My Contacts';
}
}
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;
}
}
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>',
controller: function($scope, title){
$scope.title = 'My Contacts';
},
onEnter: function(..what to inject?...){
... need simple useful example here ...
},
onExit: function(..what to inject?...){
... need simple useful example here ...
}
}
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 use specify the parent of a state via the parent
property. IS THIS RIGHT?
$stateProvider
.state('contacts', {});
.state('list', {
parent: 'contacts'
});
If you aren't fond of using string-based states, you can also use object-based states, like this:
var contacts = {
name: 'contacts',
templateUrl: 'contacts.html',
data: {
customData1: 5,
customData2: "blue"
}
}
var contactsList = {
name: 'list',
parent: states.contacts, //parent is required in this method
templateUrl: 'contacts.list.html'
}
$stateProvider
.state(contacts);
.state(contactsList)
A bonus if you use object-based states is you can attach custom data to the state object (we recommend using a data
property to avoid conflicts). 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";
}
And 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)
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>
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}}";
});
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'
})
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:
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 ... }
},
}
})
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 :).
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
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}}"
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' }