$stateProvider
ui.router.state
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 $stateProvider
provides interfaces to declare these states for your app.
Allows you to extend (carefully) or override (at your own peril) the
stateBuilder
object used internally by $stateProvider
. This can be used
to add custom functionality to ui-router, for example inferring templateUrl
based on the state name.
When passing only a name, it returns the current (original or decorated) builder
function that matches name
.
The builder functions that can be decorated are listed below. Though not all necessarily have a good use case for decoration, that is up to you to decide.
In addition, users can attach custom decorators, which will generate new properties within the state's internal definition. There is currently no clear use-case for this beyond accessing internal states (i.e. $state.$current), however, expect this to become increasingly relevant as we introduce additional meta-programming features.
Warning: Decorators should not be interdependent because the order of execution of the builder functions in non-deterministic. Builder functions should only be dependent on the state definition object and super function.
Existing builder functions and current return values:
{object}
- returns the parent state object.{object}
- returns state data, including any inherited data that is not
overridden by own values (if any).{object}
- returns a UrlMatcher
or null
.{object}
- returns closest ancestor state that has a URL (aka is
navigable).{object}
- returns an array of state params that are ensured to
be a super-set of parent's params.{object}
- returns a views object where each key is an absolute view
name (i.e. "viewName@stateName") and each value is the config object
(template, controller) for the view. Even when you don't use the views object
explicitly on a state config, one is still created for you internally.
So by decorating this builder function you have access to decorating template
and controller properties.{object}
- returns an array of params that belong to the state,
not including any params defined by ancestor states.{string}
- returns the full path from the root down to this state.
Needed for state activation.{object}
- returns an object that includes every state that
would pass a $state.includes()
test.Param | Type | Details |
---|---|---|
name | string | The name of the builder function to decorate. |
func | object | A function that is responsible for decorating the original builder function. The function receives two parameters:
|
object | $stateProvider - $stateProvider instance |
// Override the internal 'views' builder with a function that takes the state // definition, and a reference to the internal function being overridden: $stateProvider.decorator('views', function (state, parent) { var result = {}, views = parent(state); angular.forEach(views, function (config, name) { var autoName = (state.name + '.' + name).replace('.', '/'); config.templateUrl = config.templateUrl || '/partials/' + autoName + '.html'; result[name] = config; }); return result; }); $stateProvider.state('home', { views: { 'contact.list': { controller: 'ListController' }, 'contact.item': { controller: 'ItemController' } } }); // ... $state.go('home'); // Auto-populates list and item views with /partials/home/contact/list.html, // and /partials/home/contact/item.html, respectively.
Registers a state configuration under a given state name. The stateConfig object has the following acceptable properties.
Param | Type | Details |
---|---|---|
name | string | A unique state name, e.g. "home", "about", "contacts". To create a parent/child state use a dot, e.g. "about.sales", "home.newest". |
stateConfig | object | State configuration object. |
stateConfig.template (optional) | stringfunction | html template as a string or a function that returns an html template as a string which should be used by the uiView directives. This property takes precedence over templateUrl. If
template: "<h1>inline template definition</h1>" + "<div ui-view></div>" template: function(params) { return "<h1>generated template</h1>"; } |
stateConfig.templateUrl (optional) | stringfunction | path or function that returns a path to an html template that should be used by uiView. If
templateUrl: "home.html" templateUrl: function(params) { return myTemplates[params.pageId]; } |
stateConfig.templateProvider (optional) | function | |
stateConfig.controller (optional) | stringfunction | Controller fn that should be associated with newly related scope or the name of a registered controller if passed as a string. Optionally, the ControllerAs may be declared here. controller: "MyRegisteredController" controller: "MyRegisteredController as fooCtrl"} controller: function($scope, MyService) { $scope.data = MyService.getData(); } |
stateConfig.controllerProvider (optional) | function | |
stateConfig.controllerAs (optional) | string | |
stateConfig.parent (optional) | stringobject | |
stateConfig.resolve (optional) | object | An optional map<string, function> of dependencies which should be injected into the controller. If any of these dependencies are promises, the router will wait for them all to be resolved before the controller is instantiated. If all the promises are resolved successfully, the $stateChangeSuccess event is fired and the values of the resolved promises are injected into any controllers that reference them. If any of the promises are rejected the $stateChangeError event is fired. The map object is:
resolve: { myResolve1: function($http, $stateParams) { return $http.get("/api/foos/"+stateParams.fooID); } } |
stateConfig.url (optional) | string | A url fragment with optional parameters. When a state is navigated or
transitioned to, the (See UrlMatcher examples: url: "/home" url: "/users/:userid" url: "/books/{bookid:[a-zA-Z_-]}" url: "/books/{categoryid:int}" url: "/books/{publishername:string}/{categoryid:int}" url: "/messages?before&after" url: "/messages?{before:date}&{after:date}" url: "/messages/:mailboxid?{before:date}&{after:date}" |
stateConfig.views (optional) | object | an optional map<string, object> which defined multiple views, or targets views manually/explicitly. Examples: Targets three named views: { header: { controller: "headerCtrl", templateUrl: "header.html" }, body: { controller: "bodyCtrl", templateUrl: "body.html" }, footer: { controller: "footCtrl", templateUrl: "footer.html" } } Targets named views: { 'header@top': { controller: "msgHeaderCtrl", templateUrl: "msgHeader.html" }, 'body': { controller: "messagesCtrl", templateUrl: "messages.html" } } |
stateConfig.abstract (optional) | boolean | An abstract state will never be directly activated, but can provide inherited properties to its common children states. abstract: true (default: false) |
stateConfig.onEnter (optional) | function | Callback function for when a state is entered. Good way to trigger an action or dispatch an event, such as opening a dialog. If minifying your scripts, make sure to explictly annotate this function, because it won't be automatically annotated by your build tools. onEnter: function(MyService, $stateParams) { MyService.foo($stateParams.myParam); } |
stateConfig.onExit (optional) | function | Callback function for when a state is exited. Good way to trigger an action or dispatch an event, such as opening a dialog. If minifying your scripts, make sure to explictly annotate this function, because it won't be automatically annotated by your build tools. onExit: function(MyService, $stateParams) { MyService.cleanup($stateParams.myParam); } |
stateConfig.reloadOnSearch (optional) | boolean | If reloadOnSearch: false (default: true) |
stateConfig.data (optional) | object | |
stateConfig.params (optional) | object | A map which optionally configures parameters declared in the Each parameter configuration object may contain the following properties:
// define a parameter's default value params: { param1: { value: "defaultValue" } } // shorthand default values params: { param1: "defaultValue", param2: "param2Default" }
params: { param1: { array: true } }
params: { param1: { value: "defaultId", squash: true } } // squash "defaultValue" to "~" params: { param1: { value: "defaultValue", squash: "~" } } |
// Some state name examples // stateName can be a single top-level name (must be unique). $stateProvider.state("home", {}); // Or it can be a nested state name. This state is a child of the // above "home" state. $stateProvider.state("home.newest", {}); // Nest states as deeply as needed. $stateProvider.state("home.newest.abc.xyz.inception", {}); // state() returns $stateProvider, so you can chain state declarations. $stateProvider .state("home", {}) .state("about", {}) .state("contacts", {});