Class Transition

Imperative API to abort a Transition. This only applies to Transitions that are not yet complete.

Allows a transition hook to dynamically add a Resolvable to this Transition.

Use the Transition.injector to retrieve the resolved data in subsequent hooks (UIInjector.get).

If a state argument is provided, the Resolvable is processed when that state is being entered. If no state is provided then the root state is used. If the given state has already been entered, the Resolvable is processed when any child state is entered. If no child states will be entered, the Resolvable is processed during the onFinish phase of the Transition.

The state argument also scopes the resolved data. The resolved data is available from the injector for that state and any children states.

Example:

transitionService.onBefore({}, transition => {
  transition.addResolvable({
    token: 'myResolve',
    deps: ['MyService'],
    resolveFn: myService => myService.getData()
  });
});

A transition is dynamic if no states are entered nor exited, but at least one dynamic parameter has changed.

If the transition is invalid (and could not be run), returns the reason the transition is invalid. If the transition was valid and ran, but was not successful, returns the reason the transition failed.

Returns the state that the transition is coming from.

This method can be used in conjunction with injector to inspect the resolve values available to the Transition.

This returns all the tokens defined on StateDeclaration.resolve blocks, for the states in the Transition's TreeChanges.to path.

Example:

This example logs all resolve values

let tokens = trans.getResolveTokens();
tokens.forEach(token => console.log(token + " = " + trans.injector().get(token)));

Example:

This example creates promises for each resolve value. This triggers fetches of resolves (if any have not yet been fetched). When all promises have all settled, it logs the resolve values.

let tokens = trans.getResolveTokens();
let promise = tokens.map(token => trans.injector().getAsync(token));
Promise.all(promises).then(values => console.log("Resolved values: " + values));

Note: Angular 1 users whould use $q.all()

A transition is ignored if no states are entered nor exited, and no parameter values have changed.

Returns a Dependency Injector for the Transition's target state (to state). The injector provides resolve values which the target state has access to.

The UIInjector can also provide values from the native root/global injector (ng1/ng2).

Example:

.onEnter({ entering: 'myState' }, trans => {
  var myResolveValue = trans.injector().get('myResolve');
  // Inject a global service from the global/native injector (if it exists)
  var MyService = trans.injector().get('MyService');
})

In some cases (such as onBefore), you may need access to some resolve data but it has not yet been fetched. You can use UIInjector.getAsync to get a promise for the data.

Example:

.onBefore({}, trans => {
  return trans.injector().getAsync('myResolve').then(myResolveValue =>
    return myResolveValue !== 'ABORT';
  });
});

If a state is provided, the injector that is returned will be limited to resolve values that the provided state has access to. This can be useful if both a parent state foo and a child state foo.bar have both defined a resolve such as data.

Example:

.onEnter({ to: 'foo.bar' }, trans => {
  // returns result of `foo` state's `myResolve` resolve
  // even though `foo.bar` also has a `myResolve` resolve
  var fooData = trans.injector('foo').get('myResolve');
});

If you need resolve data from the exiting states, pass 'from' as pathName. The resolve data from the from path will be returned.

Example:

.onExit({ exiting: 'foo.bar' }, trans => {
  // Gets the resolve value of `myResolve` from the state being exited
  var fooData = trans.injector(null, 'from').get('myResolve');
});

deprecated

Registers a lifecycle hook, which is invoked (during a transition) when a specific state is being entered.

Since this hook is run only when the specific state is being entered, it can be useful for performing tasks when entering a submodule/feature area such as initializing a stateful service, or for guarding access to a submodule/feature area.

See TransitionStateHookFn for the signature of the function.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. onEnter hooks generally specify { entering: 'somestate' }. To match all Transitions, use an empty criteria object {}.

Lifecycle

onEnter hooks are invoked when the Transition is entering a state. States are entered after the onRetain phase is complete. If more than one state is being entered, the parent state is entered first. The registered onEnter hooks for a state are invoked in priority order.

Note: A built-in onEnter hook with high priority is used to fetch lazy resolve data for states being entered.

Return value

The hook's return value can be used to pause, cancel, or redirect the current Transition. See HookResult for more information.

Inside a state declaration

Instead of registering onEnter hooks using the TransitionService, you may define an onEnter hook directly on a state declaration (see: StateDeclaration.onEnter).

Examples

Audit Log

This example uses a service to log that a user has entered the admin section of an app. This assumes that there are substates of the "admin" state, such as "admin.users", "admin.pages", etc.

example

$transitions.onEnter({ entering: 'admin' }, function(transition, state) {
  var AuditService = trans.injector().get('AuditService');
  AuditService.log("Entered " + state.name + " module while transitioning to " + transition.to().name);
}

Audit Log (inside a state declaration)

The onEnter inside this state declaration is syntactic sugar for the previous Audit Log example.

{
  name: 'admin',
  component: 'admin',
  onEnter: function($transition$, $state$) {
    var AuditService = $transition$.injector().get('AuditService');
    AuditService.log("Entered " + state.name + " module while transitioning to " + transition.to().name);
  }
}

Note: A state declaration's onEnter function is injected for Angular 1 only.

Registers a transition lifecycle hook, which is invoked after a transition has been rejected for any reason.

See TransitionHookFn for the signature of the function.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. To match all Transitions, use an empty criteria object {}.

Lifecycle

The onError hooks are chained off the Transition's promise (see Transition.promise). If a Transition fails, its promise is rejected and the onError hooks are invoked. The onError hooks are invoked in priority order.

Since these hooks are run after the transition is over, their return value is ignored.

A transition "errors" if it was started, but failed to complete (for any reason). A non-exhaustive list of reasons a transition can error:

• A transition was cancelled because a new transition started while it was still running (Transition superseded)
• A transition was cancelled by a Transition Hook returning false
• A transition was redirected by a Transition Hook returning a TargetState
• A Transition Hook or resolve function threw an error
• A Transition Hook returned a rejected promise
• A resolve function returned a rejected promise

To check the failure reason, inspect the return value of Transition.error.

Note: onError should be used for targeted error handling, or error recovery. For simple catch-all error reporting, use StateService.defaultErrorHandler.

Return value

Since the Transition is already completed, the hook's return value is ignored

Registers a lifecycle hook, which is invoked (during a transition) when a specific state is being exited.

Since this hook is run only when the specific state is being exited, it can be useful for performing tasks when leaving a submodule/feature area such as cleaning up a stateful service, or for preventing the user from leaving a state or submodule until some criteria is satisfied.

See TransitionStateHookFn for the signature of the function.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. onExit hooks generally specify { exiting: 'somestate' }. To match all Transitions, use an empty criteria object {}.

Lifecycle

onExit hooks are invoked when the Transition is exiting a state. States are exited after any onStart phase is complete. If more than one state is being exited, the child states are exited first. The registered onExit hooks for a state are invoked in priority order.

Return value

The hook's return value can be used to pause, cancel, or redirect the current Transition. See HookResult for more information.

Inside a state declaration

Instead of registering onExit hooks using the TransitionService, you may define an onExit hook directly on a state declaration (see: StateDeclaration.onExit).

Note: A state declaration's onExit function is injected for Angular 1 only.

Registers a transition lifecycle hook, which is invoked just before a transition finishes. This hook is a last chance to cancel or redirect a transition.

See TransitionHookFn for the signature of the function.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. To match all Transitions, use an empty criteria object {}.

Lifecycle

onFinish hooks are invoked after the onEnter phase is complete. These hooks are invoked just before the transition is "committed". Each hook is invoked in priority order.

Return value

The hook's return value can be used to pause, cancel, or redirect the current Transition. See HookResult for more information.

Registers a lifecycle hook, which is invoked (during a transition) for a specific state that was previously active will remain active (is not being entered nor exited).

This hook is invoked when a state is "retained" or "kept". It means the transition is coming from a substate of the retained state to a substate of the retained state. This hook can be used to perform actions when the user moves from one substate to another, such as between steps in a wizard.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. onRetain hooks generally specify { retained: 'somestate' }. To match all Transitions, use an empty criteria object {}.

Lifecycle

onRetain hooks are invoked after any onExit hooks have been fired. If more than one state is retained, the child states' onRetain hooks are invoked first. The registered onRetain hooks for a state are invoked in priority order.

Return value

The hook's return value can be used to pause, cancel, or redirect the current Transition. See HookResult for more information.

Inside a state declaration

Instead of registering onRetain hooks using the TransitionService, you may define an onRetain hook directly on a state declaration (see: StateDeclaration.onRetain).

Note: A state declaration's onRetain function is injected for Angular 1 only.

Registers a transition lifecycle hook, which is invoked as a transition starts running. This hook can be useful to perform some asynchronous action before completing a transition.

See TransitionHookFn for the signature of the function.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. To match all Transitions, use an empty criteria object {}.

Lifecycle

onStart hooks are invoked asynchronously when the Transition starts running. This happens after the onBefore phase is complete. At this point, the Transition has not yet exited nor entered any states. The registered onStart hooks are invoked in priority order.

Note: A built-in onStart hook with high priority is used to fetch any eager resolve data.

Return value

The hook's return value can be used to pause, cancel, or redirect the current Transition. See HookResult for more information.

Example

Login during transition

This example intercepts any transition to a state which requires authentication, when the user is not currently authenticated. It allows the user to authenticate asynchronously, then resumes the transition. If the user did not authenticate successfully, it redirects to the "guest" state, which does not require authentication.

This example assumes:

• a state tree where all states which require authentication are children of a parent 'auth' state.
• MyAuthService.isAuthenticated() synchronously returns a boolean.
• MyAuthService.authenticate() presents a login dialog, and returns a promise which is resolved or rejected, whether or not the login attempt was successful.

Example:

// ng1
$transitions.onStart( { to: 'auth.**' }, function(trans) {
  var $state = trans.router.stateService;
  var MyAuthService = trans.injector().get('MyAuthService');

  // If the user is not authenticated
  if (!MyAuthService.isAuthenticated()) {

    // Then return a promise for a successful login.
    // The transition will wait for this promise to settle

    return MyAuthService.authenticate().catch(function() {

      // If the authenticate() method failed for whatever reason,
      // redirect to a 'guest' state which doesn't require auth.
      return $state.target("guest");
    });
  }
});

Registers a transition lifecycle hook, which is invoked after a transition successfully completes.

See TransitionHookFn for the signature of the function.

The HookMatchCriteria is used to determine which Transitions the hook should be invoked for. To match all Transitions, use an empty criteria object {}.

Lifecycle

onSuccess hooks are chained off the Transition's promise (see Transition.promise). If the Transition is successful and its promise is resolved, then the onSuccess hooks are invoked. Since these hooks are run after the transition is over, their return value is ignored. The onSuccess hooks are invoked in priority order.

Return value

Since the Transition is already completed, the hook's return value is ignored

A transition might belong to a long chain of multiple redirects. This method walks the redirectedFrom chain back to the original (first) transition in the chain.

Example:

// states
registry.register({ name: 'A', redirectTo: 'B' });
registry.register({ name: 'B', redirectTo: 'C' });
registry.register({ name: 'C', redirectTo: 'D' });
registry.register({ name: 'D' });

let transitionA = $state.go('A').transition

$transitions.onSuccess({ to: 'D' }, (trans) => {
  trans.to().name === 'D'; // true
  trans.redirectedFrom().to().name === 'C'; // true
  trans.originalTransition() === transitionA; // true
  trans.originalTransition().to().name === 'A'; // true
});

If the current transition is a redirect, this method returns the transition that was redirected.

Example:

let transitionA = $state.go('A').transition
transitionA.onStart({}, () => $state.target('B'));
$transitions.onSuccess({ to: 'B' }, (trans) => {
  trans.to().name === 'B'; // true
  trans.redirectedFrom() === transitionA; // true
});

A transition's TargetState encapsulates the to state, the params, and the options as a single object.

Returns the state that the transition is going to.

A transition goes from one state/parameters to another state/parameters. During a transition, states are entered and/or exited.

This function returns various branches (paths) which represent the changes to the active state tree that are caused by the transition.

Each state can define one or more views (template/controller), which are encapsulated as ViewConfig objects. This method fetches the ViewConfigs for a given path in the Transition (e.g., "to" or "entering").