About States
UI-Router applications behave like a state machine.
Think about each feature of an application as a set of states. Only one state can be active at one time. The user can transition from one state to another, to activate a different feature of the application.
UI-Router States
The basic building block of a UI-Router application is a UI-Router state.
A UI-Router state usually corresponds to a feature (or place) in the application in terms of the overall UI and navigation.
Some examples of states might be dashboard
, messages
, shoppingcart
, or blogentry
.
A state is a javascript object which has specific properties. Those properties define the functionality of the application when that state is active.
State Properties
- 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
- params
- 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)
Nested States
Unlike states in a traditional state machine, UI-Router states can be nested inside each other. A parent state can have multiple children, forming a tree of states.
Child states can be used to drill down from a more general feature to more specific one, or to implement
a master/detail pattern. For instance, you might have a parent state called contacts
which defines
the contacts module, and renders a list of all the contacts.
Nested views
The child state’s view usually renders inside a viewport that the parent state created. This is referred to as Nested Views
Then, you might have two child states contacts.contact
(to view a specific contact’s details)
and contacts.new
(to create a new contact). These substates share the common parent state
contacts
and inherit data and behavior from the parent. They are rendered inside the UI for the
parent state.
State-based approach
UI-Router’s approach to applications as a tree of states encourages you to think about your application’s as a hierarchy of functionality. The tree defines the application’s functionality structure. The URL and views (i.e., the rendered tree of components in the DOM) are artifacts of the active state.
Optional Urls
Although states generally have URLs, they are optional.
You might create some child states without URLs, if it doesn’t make sense to bookmark those child states. The state machine transitions between url-less states as usual, but does not update the url when complete You still get all the other benefits of a state transition such as parameters, resolve, and lifecycle hooks.
Optional Views
Although states generally have views, they are optional.
You might create a parent state for the sole purpose of adding data or behaviors to a branch of your application.
For instance, you might create a state called admin
and then child states for each administration function in your app.
The parent admin
state could be used to restrict access to the entire tree of child states, but provide no UI itself.
Transitions
If the app’s current state is contacts
and the user wants to switch to the prefs
state,
the UI-Router state machine creates and runs a Transition from the contacts
state to the prefs
state.
Atomic
These transitions are essentially atomic.
When transitioning from contacts
to prefs
, either the entire transition succeeds and the application’s
current state is now prefs
, or the entire transition fails and the application remains in the contacts
state.
Lifecycle
Transitions have a lifecycle, starting at Transition creation and completing with either success or failure. That lifecycle is exposed to the application developer as a set of transition hooks. The hooks allow you to tap into each stage of the Transition and cancel or alter the Transition.
To learn more about transition hooks, read the Transitions Guide and the in depth API documentation for TransitionService.