State provider service

The state service provides a number of methods for accessing states and doing transitions.

• $state.root
• $state.current
• $state.goto(state, params?)
• $state.lookup(path)
• $state.reload(state?)
• $state.url(state?, params?)

Goto

To transition to another state, use goto...

• expression: either a path, the full name of a state or a state object (e.g. use lookup to get the object). Uses $state.lookup(path) to resolve the targeted state when a path or name is provided.
• params: (optional) a set of parameters to use for the state.

If the state has an associated route, that route will be activated and the location with change it the address bar of the browser. It is also important that all parameters are defined for such route, however if the previous state defines any of those, they won't need to be redefined.

e.g. say the following states are defined:

$stateProvider
  .state('home', { route: '/home/:homeParam' })
  .state('home.child', { route: '/child/:childParam' })

To activate the home state, a call to goto must include the :homeParam e.g:

$state.goto('home', { homeParam: 'goHome' } );

To activate the home.child state, a call to goto must include the :homeParam and the :childParam e.g:

$state.goto('home.child', { homeParam: 'goHome', childParam: 'goChild' } );

To activate the home.child state when currently in the home state, a call to goto must include the the :childParam and can optionally include the :homeParam e.g:

$state.goto('home.child', { childParam: 'goChild' } );
$state.goto('home.child', { homeParam: 'goHome', childParam: 'goChild' } );

We can leave out the home param as that is already defined in the current set of params, that also means we can goto home from child without specifying any params, but if we wish to change it we must specify it, the following example will demonstrate a full flow:

$state.goto('home', { homeParam: 1 } );
// - location set to: '/home/1'

$state.goto('home.child', { childParam: 1 } );
// - location set to: '/home/1/child/1'

$state.goto('home');
// - location set to: '/home/1'

$state.goto('home.child', { homeParam: 2, childParam: 2 } );
// - location set to: '/home/2/child/2'

$state.goto('home.child', { childParam: 4 } );
// - location set to: '/home/2/child/4'

$state.goto('home.child', { homeParam: 4 } );
// - location set to: '/home/4/child/4'

Lookup

To lookup a state, use lookup...

• path: a path to the state that can either be relative to the current state or from the root.

Path is inspired by XPath and supports a subset of that syntax.

• . : current state
• .. : parent state
• / : path separator
• [] : index selector, errors on overflow
• $node() : sibling selector, can overflow

Using these selectors, the following are examples of paths:

• /state : Selects state from the root.
• ./state : Selects state from the current node.
• ./state/child : Selects child under state from the current node.
• ../state : Selects state under the parent of the current state.
• [0] : Selects the first child of the current state.
• [-1] : Selects the last child of the current state.
• ./state/[-1] : Selects the last child under state under current state.
• $node(1) : Selects the next sibling of the current state.
• $node(-1) : Selects the previous sibling of the current state.

Note that if there when using $node(), it allows for overflow. this means if you are at the last child of a state and selects $node(1), it will select the first child instead.

Finally it is also possible to select states by their full name:

• state: Selects state under root.
• state.child : Selects state.child under root.

Errors will be thrown in cases where the path isn't valid. The root state it self can't be selected. (The root state is implicitly defined by the system, when defining .state('home', {...});, the state home isn't a root state, it is instead a child of root.

Reload

To force reload a state, use reload...

• state: (optional) can be string, state object or boolean
• call .reload() to reload only the current leaf state.
• call .reload(true) to reload all active states from the root state to the current leaf.
• call .reload('state.full.name') to reload all states from state.full.name and down to the current leaf.

E.g. if the current state is state.full.name.to.here and .reload() is called then all views etc. will be reloaded for the leaf state here.

If .reload(true) called, views etc. will be reloaded for all the states state, full, name, to, here.

Finally if .reload('state.full.name') is called, views etc. will be reloaded for the states name, to, here.

Url

To build a url for a particular state, use url...

• expression: (optional) either a path, the full name of a state or a state object (e.g. use lookup to get the object). If state is undefined, the url will be build for the current state. Uses $state.lookup(path) to resolve the targeted state when a path or name is provided.
• params: (optional) a set of parameters to use for the state.

If the state defined either by state, or current state does not have an route associated with it, it will throw an error.