Interface StateDeclaration

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 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.

This default applies to all parameters declared on this state.

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 state hook invoked when a state is being entered.

The hook can inject global services. It can also inject $transition$ or $state$ (from the current transition).

Example:

$stateProvider.state({
  name: 'mystate',
  onEnter: (MyService, $transition$, $state$) => {
    return MyService.doSomething($state$.name, $transition$.params());
  }
});
Copy

Example:`

$stateProvider.state({
  name: 'mystate',
  onEnter: [ 'MyService', '$transition$', '$state$', function (MyService, $transition$, $state$) {
    return MyService.doSomething($state$.name, $transition$.params());
  } ]
});
Copy

A state hook invoked when a state is being exited.

The hook can inject global services. It can also inject $transition$ or $state$ (from the current transition).

Example:

$stateProvider.state({
  name: 'mystate',
  onExit: (MyService, $transition$, $state$) => {
    return MyService.doSomething($state$.name, $transition$.params());
  }
});
Copy

Example:`

$stateProvider.state({
  name: 'mystate',
  onExit: [ 'MyService', '$transition$', '$state$', function (MyService, $transition$, $state$) {
    return MyService.doSomething($state$.name, $transition$.params());
  } ]
});
Copy

A state hook invoked when a state is being retained.

The hook can inject global services. It can also inject $transition$ or $state$ (from the current transition).

Example:

$stateProvider.state({
  name: 'mystate',
  onRetain: (MyService, $transition$, $state$) => {
    return MyService.doSomething($state$.name, $transition$.params());
  }
});
Copy

Example:`

$stateProvider.state({
  name: 'mystate',
  onRetain: [ 'MyService', '$transition$', '$state$', function (MyService, $transition$, $state$) {
    return MyService.doSomething($state$.name, $transition$.params());
  } ]
});
Copy

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.

Example:

params: {
  param1: {
   type: "int",
   array: true,
   value: []
  },
  param2: {
    value: "index"
  }
}
Copy

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 ng-sref="childstate">Child</a> instead of `Child

When using this property, the state's name should not have any dots in it.

Example:

var parentstate = {
  name: 'parentstate'
}
var childstate = {
  name: 'childstate',
  parent: 'parentstate'
  // or use a JS var which is the parent StateDeclaration, i.e.:
  // parent: parentstate
}
Copy

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:

  • The function is called with the current [[Transition]]
  • The return value is processed using the previously mentioned rules.
  • If the return value is a promise, the promise is waited for, then the resolved async value is processed using the same rules.

Note: redirectTo is processed as an onStart hook, before non-eager resolves. If your redirect function relies on resolve data, get the [[Transition.injector]] and request the resolve data with getAsync().

Example:

// 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);
  }
})
Copy

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.

As an array

Each array element should be a [[ResolvableLiteral]] object.

Example:

The user resolve injects the current Transition and the UserService (using its token, which is a string). The [[ResolvableLiteral.eager]] flag controls whether the resolve starts at transition start instead of when the owning state is entered. The user data, fetched asynchronously, can then be used in a view.

var state = {
  name: 'user',
  url: '/user/:userId
  resolve: [
    {
      token: 'user',
      eager: true,
      deps: ['UserService', Transition],
      resolveFn: (userSvc, trans) => userSvc.fetchUser(trans.params().userId) },
    }
  ]
}
Copy

As an object

The resolve property may be an object where:

• Each key (string) is the name of the dependency.
• Each value (function) is an injectable function which returns the dependency, or a promise for the dependency.

This style is based on AngularTS injectable functions. If your code will be minified, the function should be "annotated" in the AngularTS manner.

AngularTS Example:

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);
  }]
}
Copy

Note: You cannot mark individual entries as eager, nor can you use non-string tokens when using the object style resolve: block.

Lifecycle

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.

Injecting resolves into other things

During a transition, Resolve data can be injected into:

• Views (the components which fill a ng-view tag)
• Transition Hooks
• Other resolves (a resolve may depend on asynchronous data from a different resolve)

Injecting other things into resolves

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();

Special injectable tokens

• 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.
• Other resolve tokens: A resolve can depend on another resolve, either from the same state, or from any parent state.

Example:

// 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
  { token: 'allusers', resolveFn: (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.
  { token: 'user', resolveFn: (allusers, trans) => _.find(allusers, trans.params().userId), deps: ['allusers', Transition] }
}
Copy

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. It may include path parameters, typed parameters, and query parameters.

Named view declarations for this state.

Each key targets an ng-view; each value is either a full view declaration or a string shorthand for { component: "componentName" }.

Examples:

views: {
  mymessages: "mymessages",
  messagelist: { component: "messageList" },
  "^.^.messagecontent": "message"
}
Copy