The context that this view is declared within.
The raw name for the view declaration, i.e., the [[StateDeclaration.views]] property name.
A type identifier for the View
This is used when loading prerequisites for the view, before it enters the DOM. Different types of views may load differently (e.g., templateProvider+controllerProvider vs component class)
The normalized context anchor (state name) for the uiViewName
When targeting a ui-view
, the uiViewName
address is anchored to a context name (state name).
The normalized address for the ui-view
which this ViewConfig targets.
A ViewConfig targets a ui-view
in the DOM (relative to the uiViewContextAnchor
) which has
a specific name.
Abstract state indicator
An abstract state can never be directly activated. Use an abstract state to provide inherited properties (url, resolve, data, etc) to children states.
An object which maps resolve
keys to component bindings
.
A property of Ng2StateDeclaration or Ng2ViewDeclaration:
When using a component declaration (component: MyComponent
), each input binding for the component is supplied
data from a resolve of the same name, by default. You may supply data from a different resolve name by mapping it here.
This might be useful if you want to reuse the same resolve value with various components with different input binding names.
Each key in this object is the name of one of the component's input bindings. Each value is the name of the resolve that should be provided to that binding.
Any component bindings that are omitted from this map get the default behavior of mapping to a resolve of the * same name.
export const fooState = {
name: 'foo',
component: MyComponent,
resolve: [
{ token: 'users', deps: [UserService], resolveFn: getUsers }
],
bindings: {
resolveData: 'users'
}
}
export function getUsers(userservice) {
return userservice.getUsers();
}
@Component() {
}
class MyComponent {
@Input() resolveData;
constructor() { }
}
The Component
class to use for this view.
A property of Ng2StateDeclaration or Ng2ViewDeclaration:
.state('profile', {
// Use the <my-profile></my-profile> component for the Unnamed view
component: MyProfileComponent,
}
.state('messages', {
// use the <nav-bar></nav-bar> component for the view named 'header'
// use the <message-list></message-list> component for the view named 'content'
views: {
header: { component: NavBar },
content: { component: MessageList }
}
}
// Named views shorthand:
// Inside a "views:" block, a Component class (NavBar) is shorthand for { component: NavBar }
.state('contacts', {
// use the <nav-bar></nav-bar> component for the view named 'header'
// use the <contact-list></contact-list> component for the view named 'content'
views: {
header: NavBar,
content: ContactList
}
}
The component can access the Transition's Ng2StateDeclaration.resolve data in one of two ways:
1) Using Dependency Injection in the component constructor
(using Typescript)
class MyComponent {
constructor(@Inject("myResolveData") public resolveValueA, resolveValueB: public SomeClass) {
}
}
(using ES6/7/babel)
class MyComponent {
static get parameters() {
return [["myResolveData"], [MyResolveClass]];
}
constructor(resolveValueA, resolveValueB) {
this.resolveValueA = resolveValueA;
this.resolveValueB = resolveValueB;
}
}
See also: https://github.com/shuhei/babel-plugin-angular2-annotations
2) Using a component input
Note: To bind a resolve to a component input, the resolves must provide:
a string value
@Component() {
inputs: ['resolveValueA']
}
class MyComponent {
myResolveValueA;
@Input() resolveValueB;
@Input("resolveValueC") resolveValueC;
constructor() {
}
}
An inherited property to store state data
This is a spot for you to store inherited state metadata.
Child states' data
object will prototypally inherit from their parent state.
This is a good spot to put metadata such as requiresAuth
.
Note: because prototypal inheritance is used, changes to parent data
objects reflect in the child data
objects.
Care should be taken if you are using hasOwnProperty
on the data
object.
Properties from parent objects will return false for hasOwnProperty
.
Marks all the state's parameters as dynamic
.
All parameters on the state will use this value for dynamic
as a default.
Individual parameters may override this default using [[ParamDeclaration.dynamic]] in the params block.
Note: this value overrides the dynamic
value on a custom parameter type ([[ParamTypeDefinition.dynamic]]).
A function used to lazy load code
The lazyLoad
function is invoked before the state is activated.
The transition waits while the code is loading.
The function should load the code that is required to activate the state. For example, it may load a component class, or some service code. The function must return a promise which resolves when loading is complete.
For example, this code lazy loads a service before the abc
state is activated:
.state('abc', {
lazyLoad: (transition, state) => import('./abcService')
}
The abcService
file is imported and loaded
(it is assumed that the abcService
file knows how to register itself as a service).
The lazyLoad
function is invoked if a transition is going to enter the state.
The function is invoked before the transition starts (using an onBefore
transition hook).
The function is only invoked once; while the lazyLoad
function is loading code, it will not be invoked again.
For example, if the user double clicks a ui-sref, lazyLoad
is only invoked once even though there were two transition attempts.
Instead, the existing lazy load promise is re-used.
When the promise resolves successfully, the lazyLoad
property is deleted from the state declaration.
If the promise resolves to a [[LazyLoadResult]] which has an array of states
, those states are registered.
The original transition is retried (this time without the lazyLoad
property present).
If the lazyLoad
function fails, then the transition also fails.
The failed transition (and the lazyLoad
function) could potentially be retried by the user.
State definitions can also be lazy loaded. This might be desirable when building large, multi-module applications.
To lazy load state definitions, a Future State should be registered as a placeholder. When the state definitions are lazy loaded, the Future State is deregistered.
A future state can act as a placeholder for a single state, or for an entire module of states and substates. A future state should have:
name
which ends in .**
.
A future state's name
property acts as a wildcard [[Glob]].
It matches any state name that starts with the name
(including child states that are not yet loaded).url
prefix.
A future state's url
property acts as a wildcard.
UI-Router matches all paths that begin with the url
.
It effectively appends .*
to the internal regular expression.
When the prefix matches, the future state will begin loading.lazyLoad
function.
This function should should return a Promise to lazy load the code for one or more [[StateDeclaration]] objects.
It should return a [[LazyLoadResult]].
Generally, one of the lazy loaded states should have the same name as the future state.
The new state will then replace the future state placeholder in the registry.For in depth information on lazy loading and Future States, see the Lazy Loading Guide.
// This child state is a lazy loaded future state
// The `lazyLoad` function loads the final state definition
{
name: 'parent.**',
url: '/parent',
lazyLoad: () => import('./lazy.states.js')
}
This file is lazy loaded. It exports an array of states.
import {ChildComponent} from "./child.component.js";
import {ParentComponent} from "./parent.component.js";
// This fully defined state replaces the future state
let parentState = {
// the name should match the future state
name: 'parent',
url: '/parent/:parentId',
component: ParentComponent,
resolve: {
parentData: ($transition$, ParentService) =>
ParentService.get($transition$.params().parentId)
}
}
let childState = {
name: 'parent.child',
url: '/child/:childId',
params: {
childId: "default"
},
resolve: {
childData: ($transition$, ChildService) =>
ChildService.get($transition$.params().childId)
}
};
// This array of states will be registered by the lazyLoad hook
let lazyLoadResults = {
states: [ parentState, childState ]
};
export default lazyLoadResults;
A function used to lazy load an NgModule
The loadChildren
property should be added to a Future State (a lazy loaded state whose name ends in .**
).
The Future State is a placeholder for a tree of states that will be lazy loaded in the future.
When the future state is activated, the loadChildren
property should lazy load an NgModule
which contains the fully loaded states.
The NgModule
should contain the fully loaded states which will be registered.
The fully loaded states will replace the temporary future states once lazy loading is complete.
var futureState = {
name: 'home.**',
url: '/home',
loadChildren: () => import('./home/home.module')
.then(result => result.HomeModule);
}
The state name (required)
A unique state name, e.g. "home"
, "about"
, "contacts"
.
To create a parent/child state use a dot, e.g. "about.sales"
, "home.newest"
.
Note: [State] objects require unique names. The name is used like an id.
A Transition Hook called with the state is being entered. See: [[IHookRegistry.onEnter]]
.state({
name: 'mystate',
onEnter: function(trans, state) {
console.log("Entering " + state.name);
}
});
Note: The above onEnter
on the state declaration is effectively sugar for:
transitionService.onEnter({ entering: 'mystate' }, function(trans, state) {
console.log("Entering " + state.name);
});
A Transition Hook called with the state is being exited. See: [[IHookRegistry.onExit]]
.state({
name: 'mystate',
onExit: function(trans, state) {
console.log("Leaving " + state.name);
}
});
Note: The above onRetain
on the state declaration is effectively sugar for:
transitionService.onExit({ exiting: 'mystate' }, function(trans, state) {
console.log("Leaving " + state.name);
});
A [[TransitionStateHookFn]] called with the state is being retained/kept. See: [[IHookRegistry.onRetain]]
.state({
name: 'mystate',
onRetain: function(trans, state) {
console.log(state.name + " is still active!");
}
});
Note: The above onRetain
on the state declaration is effectively sugar for:
transitionService.onRetain({ retained: 'mystate' }, function(trans, state) {
console.log(state.name + " is still active!");
});
Params configuration
An object which optionally configures parameters declared in the url, or defines additional non-url parameters. For each parameter being configured, add a [[ParamDeclaration]] keyed to the name of the parameter.
params: {
param1: {
type: "int",
array: true,
value: []
},
param2: {
value: "index"
}
}
The parent state
Normally, a state's parent is implied from the state's name, e.g., "parentstate.childstate"
.
Alternatively, you can explicitly set the parent state using this property.
This allows shorter state names, e.g., <a ui-sref="childstate">Child</a>
instead of `Child
When using this property, the state's name should not have any dots in it.
var parentstate = {
name: 'parentstate'
}
var childstate = {
name: 'childstate',
parent: 'parentstate'
// or use a JS var which is the parent StateDeclaration, i.e.:
// parent: parentstate
}
Synchronously or asynchronously redirects Transitions to a different state/params
If this property is defined, a Transition directly to this state will be redirected based on the property's value.
If the value is a string
, the Transition is redirected to the state named by the string.
If the property is an object with a state
and/or params
property,
the Transition is redirected to the named state
and/or params
.
If the value is a [[TargetState]] the Transition is redirected to the TargetState
If the property is a function:
Note: redirectTo
is processed as an onStart
hook, before LAZY
resolves.
If your redirect function relies on resolve data, get the [[Transition.injector]] and get a
promise for the resolve data using [[UIInjector.getAsync]].
// a string
.state('A', {
redirectTo: 'A.B'
})
// a {state, params} object
.state('C', {
redirectTo: { state: 'C.D', params: { foo: 'index' } }
})
// a fn
.state('E', {
redirectTo: () => "A"
})
// a fn conditionally returning a {state, params}
.state('F', {
redirectTo: (trans) => {
if (trans.params().foo < 10)
return { state: 'F', params: { foo: 10 } };
}
})
// a fn returning a promise for a redirect
.state('G', {
redirectTo: (trans) => {
let svc = trans.injector().get('SomeAsyncService')
let promise = svc.getAsyncRedirectTo(trans.params.foo);
return promise;
}
})
// a fn that fetches resolve data
.state('G', {
redirectTo: (trans) => {
// getAsync tells the resolve to load
let resolvePromise = trans.injector().getAsync('SomeResolve')
return resolvePromise.then(resolveData => resolveData === 'login' ? 'login' : null);
}
})
Marks all query parameters as [[ParamDeclaration.dynamic]]
Resolve - a mechanism to asynchronously fetch data, participating in the Transition lifecycle
The resolve:
property defines data (or other dependencies) to be fetched asynchronously when the state is being entered.
After the data is fetched, it may be used in views, transition hooks or other resolves that belong to this state.
The data may also be used in any views or resolves that belong to nested states.
Each array element should be a [[ResolvableLiteral]] object.
The user
resolve injects the current Transition
and the UserService
(using its token, which is a string).
The [[ResolvableLiteral.resolvePolicy]] sets how the resolve is processed.
The user
data, fetched asynchronously, can then be used in a view.
var state = {
name: 'user',
url: '/user/:userId
resolve: [
{
token: 'user',
policy: { when: 'EAGER' },
deps: ['UserService', Transition],
resolveFn: (userSvc, trans) => userSvc.fetchUser(trans.params().userId) },
}
]
}
Note: an Angular 2 style useFactory
provider literal
may also be used. See [[ProviderLike]].
resolve: [
{ provide: 'token', useFactory: (http) => http.get('/'), deps: [ Http ] },
]
The resolve
property may be an object where:
This style is based on AngularJS injectable functions, but can be used with any UI-Router implementation. If your code will be minified, the function should be "annotated" in the AngularJS manner.
resolve: {
// If you inject `myStateDependency` into a controller, you'll get "abc"
myStateDependency: function() {
return "abc";
},
// Dependencies are annotated in "Inline Array Annotation"
myAsyncData: ['$http', '$transition$' function($http, $transition$) {
// Return a promise (async) for the data
return $http.get("/foos/" + $transition$.params().foo);
}]
}
Note: You cannot specify a policy for each Resolvable, nor can you use non-string
tokens when using the object style resolve:
block.
Since a resolve function can return a promise, the router will delay entering the state until the promises are ready. If any of the promises are rejected, the Transition is aborted with an Error.
By default, resolves for a state are fetched just before that state is entered.
Note that only states which are being entered during the Transition
have their resolves fetched.
States that are "retained" do not have their resolves re-fetched.
If you are currently in a parent state parent
and are transitioning to a child state parent.child
, the
previously resolved data for state parent
can be injected into parent.child
without delay.
Any resolved data for parent.child
is retained until parent.child
is exited, e.g., by transitioning back to the parent
state.
Because of this scoping and lifecycle, resolves are a great place to fetch your application's primary data.
During a transition, Resolve data can be injected into:
ui-view
tag)Resolve functions usually have dependencies on some other API(s).
The dependencies are usually declared and injected into the resolve function.
A common pattern is to inject a custom service such as UserService
.
The resolve then delegates to a service method, such as UserService.list()
;
UIRouter
: The [[UIRouter]] instance which has references to all the UI-Router services.Transition
: The current [[Transition]] object; information and API about the current transition, such as
"to" and "from" State Parameters and transition options.'$transition$'
: A string alias for the Transition
injectable'$state$'
: For onEnter
/onExit
/onRetain
, the state being entered/exited/retained.// Injecting a resolve into another resolve
resolve: [
// Define a resolve 'allusers' which delegates to the UserService.list()
// which returns a promise (async) for all the users
{ provide: 'allusers', useFactory: (UserService) => UserService.list(), deps: [UserService] },
// Define a resolve 'user' which depends on the allusers resolve.
// This resolve function is not called until 'allusers' is ready.
{ provide: 'user', (allusers, trans) => _.find(allusers, trans.params().userId, deps: ['allusers', Transition] }
}
Sets the resolve policy defaults for all resolves on this state
This should be an [[ResolvePolicy]] object.
It can contain the following optional keys/values:
when
: (optional) defines when the resolve is fetched. Accepted values: "LAZY" or "EAGER"async
: (optional) if the transition waits for the resolve. Accepted values: "WAIT", "NOWAIT", {@link CustomAsyncPolicy}See [[ResolvePolicy]] for more details.
The url fragment for the state
A URL fragment (with optional parameters) which is used to match the browser location with this state.
This fragment will be appended to the parent state's URL in order to build up the overall URL for this state. See [[UrlMatcher]] for details on acceptable patterns.
An optional object used to define multiple named views.
Each key is the name of a view, and each value is a Ng2ViewDeclaration.
Unnamed views are internally renamed to $default
.
A view's name is used to match an active <ui-view>
directive in the DOM. When the state
is entered, the state's views are activated and then matched with active <ui-view>
directives:
The view's name is processed into a ui-view target:
Examples:
Targets three named ui-views in the parent state's template
views: {
header: {component: HeaderComponent},
body: {component: BodyComponent},
footer: {component: FooterComponent}
}
// Targets named ui-view="header" in the template of the ancestor state 'top'
// and the named `ui-view="body" from the parent state's template.
views: {
'header@top': {component: MsgHeaderComponent},
'body': {component: MessagesComponent}
}
There are a few styles of view addressing/targeting. The most common is a simple ui-view
name
Addresses without an @
are anchored to the parent state.
// target the `<div ui-view='foo'></div>` created in the parent state's view
views: { foo: {...} }
You can anchor the ui-view
name to a specific state by including an @
Generated using TypeDoc
The StateDeclaration object is used to define a state or nested state. It should be registered with the [[StateRegistry]].
Example:
import {FoldersComponent} from "./folders"; export function getAllFolders(FolderService) { return FolderService.list(); } // StateDeclaration object export let foldersState = { name: 'folders', url: '/folders', component: FoldersComponent, resolve: [ { token: 'allfolders', deps: [FolderService], resolveFn: getAllFolders } ] }