Learn UI-Routing Series - Part Two

Introduction

This is the second article in series of articles for learning UI-Router. In this article, we will have an in-depth learning for state in ui-router.

In case you have not read previous article, you can find it Here,

Learn UI-Routing Series - Part One - Basics

Overview

What is ui-Router state?

A state normally references a “place” in an application where all the information of UI and Navigation exists. A state describes the UI of an application via the Controller/ template / view properties.

A state is a JavaScript object which has specific Properties. Those properties help in defining the functionality of application when a state is active, below are the properties of state.

name: A name for the state, providing a way to refer to the state
views: How the UI will look and behave
url: What the browser’s URL will be
prams: Parameter values that the state requires (such as blog-post-id)
resolve: The actual data the state requires (often fetched, asynchronously, from the backend using a parameter value)

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

<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>' })

Where is the Template viewed?

This is the question which will be raised in everyone’s mind. Whenever a state is activated the template is automatically rendered in the ui-view of its parent state’s template. If it's a top-level state—which 'contacts' is because it has no parent state–then its parent template is index.html.

Here in our example, the contacts state won’t ever be activated. So, let’s see how we can activate a state.

Activating a state

There are mainly three methods to activate a state as listed below.

Call $state.go(). High-level convenience method.
Click on the link written in ui-sref
Navigate to URL associated with state.

All three methods are explained in detail below.

$state.go()

$state

$state service is used for representing states and transition between them. It also provides information about the current state or even the states from which the transition is done.

$state.go(to, params, options)

Param	Type	Details
to	string	Absolute state name or relative state path. Some examples:· $state.go('contact.detail') - will go to the contact.detail state· $state.go('^') - will go to a parent state· $state.go('^.sibling') - will go to a sibling state· $state.go('.child.grandchild') - will go to grandchild state
params(optional)	object	A map of the parameters that will be sent to the state, will populate $stateParams. Any parameters that are not specified will be inherited from currently defined parameters. Only parameters specified in the state definition can be overridden, new parameters will be ignored.
options(optional)	object	Options object. The options are:· location - {boolean=true\|string=} - If true will update the url in the location bar, if false will not. If string, must be "replace", which will update url and replace last history record.· inherit - {boolean=true}, If true will inherit url parameters from current url.· relative - {object=$state.$current}, When transitioning with relative path (e.g '^'), defines which state to be relative from.· notify - {boolean=true}, If true will broadcast $stateChangeStart and $stateChangeSuccess events.· reload (v0.2.5) - {boolean=false\|string\|object}, If true will force transition even if no state or params have changed. It will reload the resolves and views of the current state and parent states. If reload is a string (or state object), the state object is fetched (by name, or object reference); and \ the transition reloads the resolves and views for that matched state, and all its children states.

ui-sref

It is a directive that binds a link(<a>) to a state. If there is an associated url in the state then the directive will automatically generate and update the href attribute using $state.href method.

Usage

ui-sref='stateName' - Navigate to state, no params. 'stateName' can be any valid absolute or relative state, following the same syntax rules as $state.go()
ui-sref='stateName({param: value, param: value})' - Navigate to state, with params.

Example

Template HTML

<a ui-sref="home">Home</a> | <a ui-sref="about">About</a>
<ul>
<li ng-repeat="contact in contacts">
<a ui-sref="contacts.detail({ id: contact.id })">{{ contact.name }}</a>
</li>
</ul>

URL

It is similar to the url that we have used in ngRoute

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.

Templates

There are several methods to configure states template.

As seen in above example the simplest way is to set template by template config property

$stateProvider.state('contacts', { template: '<h1>My Contacts</h1>'})

Instead of writing template inline you can load a partial html page and probably it is the method that is used normally to insert template in a view.

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

templateUrl can also be a function with a predefined parameter $stateParams which is not injected. This function returns URL.

$stateProvider.state('contacts', {
templateUrl: function ($stateParams){
return '/partials/contacts.' + $stateParams.filterBy + '.html';
}
})

you can also customize it by using templateProvider which can be injected, has access to locals and must return template HTML as below,

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

Controllers

You can assign a controller to your template.

Note

The controller will not be instantiated if template is not defined.

You set your controller like this,

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

Or if you have already defined a controller in module, you can use it as below

$stateProvider.state('contacts', {
template: ...,
controller: 'ContactsCtrl'
})

If you want to define some random function in state itself and then assigning a controller name you can use it as below

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

Or you can also write it as following

$stateProvider.state('contacts', {
template: ...,
controller: 'ContactsCtrl as contact'
})

Or for more advanced needs you can use the controllerProvider to dynamically return a controller function or string for you

$stateProvider.state('contacts', {
template: ...,
controllerProvider: function($stateParams) {
var ctrlName = $stateParams.type + "Controller";
return ctrlName;
}
})

Controllers are instantiated on an as-needed basis, when their corresponding scopes are created, i.e. when the user manually navigates to a state via a URL, $stateProvider will load the correct template into the view, then bind the controller to the template's scope.

Resolve

If you want to provide data or some content that is custom to the state then you can use resolve. Resolve is an optional map of dependencies that should be injected to the controller.

If any of these dependencies are promises, they will be resolved and converted to a value before the controller is instantiated and the $stateChangeSuccess event is fired.

The resolve property is a map object which contains key/value pairs of

key – {string}: a name of a dependency to be injected into the controller.
factory - {string|function}
- If string, then it is an alias for a service.
- Otherwise if function, then it is injected and the return value is treated as the dependency. If the result is a promise, it is resolved before the controller is instantiated and its value is injected into the controller.

Examples

Each of the objects in resolve below must be resolved (via deferred.resolve() if they are a promise) before the controller is instantiated. Notice how each resolve object is injected as a parameter into the controller.

$stateProvider.state('myState', {
resolve:{
// Example using function with simple return value.
// Since it's not a promise, it resolves immediately.
simpleObj: function(){
return {value: 'simple!'};
},
// Example using function with returned promise.
// This is the typical use case of resolve.
// You need to inject any services that you are
// using, e.g. $http in this example
promiseObj: function($http){
// $http returns a promise for the url data
return $http({method: 'GET', url: '/someUrl'});
},
// Another promise example. If you need to do some
// processing of the result, use .then, and your
// promise is chained in for free. This is another
// typical use case of resolve.
promiseObj2: function($http){
return $http({method: 'GET', url: '/someUrl'})
.then (function (data) {
return doSomeStuffFirst(data);
});
},
// Example using a service by name as string.
// This would look for a 'translations' service
// within the module and return it.
// Note: The service could return a promise and
// it would work just like the example above
translations: "translations",
// Example showing injection of service into
// resolve function. Service then returns a
// promise. Tip: Inject $stateParams to get
// access to url parameters.
translations2: function(translations, $stateParams){
// Assume that getLang is a service method
// that uses $http to fetch some translations.
// Also assume our url was "/:lang/home".
return translations.getLang($stateParams.lang);
},
// Example showing returning of custom made promise
greeting: function($q, $timeout){
var deferred = $q.defer();
$timeout(function() {
deferred.resolve('Hello!');
}, 1000);
return deferred.promise;
}
},
// The controller waits for every one of the above items to be
// completely resolved before instantiation. For example, the
// controller will not instantiate until promiseObj's promise has
// been resolved. Then those objects are injected into the controller
// and available for use.
controller: function($scope, simpleObj, promiseObj, promiseObj2, translations, translations2, greeting){
$scope.simple = simpleObj.value;
// You can be sure that promiseObj is ready to use!
$scope.items = promiseObj.data.items;
$scope.items = promiseObj2.items;
$scope.title = translations.getLang("english").title;
$scope.title = translations2.title;
$scope.greeting = greeting;
}
})

Attach Custom Data to State Object

You can attach custom data to the state object so data passing during initiation of state is easy.

// 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";
}

Conclusion

Finally, we can say UI-Router provides more features then ngRoute. In next part, we will cover Transition and some features of UI-Router.