Transition | UI-Router
Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Transition

Represents a transition between two states.

When navigating to a state, we are transitioning from the current state to the new state.

This object contains all contextual information about the to/from states, parameters, resolves. It has information about all states being entered and exited as a result of the transition.

Hierarchy

  • Transition

Implements

Index

Constructors

  • Creates a new Transition object.

    If the target state is not valid, an error is thrown.

    Parameters

    • fromPath: PathNode[]
      :

      The path of PathNodes from which the transition is leaving. The last node in the fromPath encapsulates the "from state".

    • targetState: TargetState
      :

      The target state and parameters being transitioned to (also, the transition options)

    • router: UIRouter
      :

      The UIRouter instance

    Returns Transition


Properties

$id: number
_targetState: TargetState
_treeChanges: TreeChanges
getHooks: IHookGetter
promise: Promise<any>

This promise is resolved or rejected based on the outcome of the Transition.

This promise is resolved or rejected based on the outcome of the Transition.

When the transition is successful, the promise is resolved When the transition is unsuccessful, the promise is rejected with the [[TransitionRejection]] or javascript error

router: UIRouter

A reference to the UIRouter instance

A reference to the UIRouter instance

This reference can be used to access the router services, such as the StateService

success: boolean

A boolean which indicates if the transition was successful

A boolean which indicates if the transition was successful

After a successful transition, this value is set to true. After a failed transition, this value is set to false.

diToken: Transition

Methods

  • dynamic(): boolean
  • Returns true if the transition is dynamic.

  • Returns true if the transition is dynamic.

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

    Returns boolean

    :

    true if the Transition is dynamic


  • error(): any
  • The Transition error reason.

  • The Transition error reason.

    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 any

    :

    an error message explaining why the transition is invalid, or the reason the transition failed.


  • getResolveTokens(): any[]
  • Gets all available resolve tokens (keys)

  • Gets all available resolve tokens (keys)

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

    The returned tokens include those defined on StateDeclaration.resolve blocks, for the states in the Transition's TreeChanges.to path.

    Returns any[]

    :

    an array of resolve tokens (keys)


  • getResolveValue(token: any): any
  • Gets resolved values

  • Gets resolved values

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

    Given a token, returns the resolved data for that token. Given an array of tokens, returns an array of resolved data for those tokens.

    If a resolvable hasn't yet been fetched, returns undefined for that token If a resolvable doesn't exist for the token, throws an error.

    Parameters

    • token: any
      :

      the token (or array of tokens)

    Returns any

    :

    an array of resolve tokens (keys)


  • ignored(): boolean
  • Returns true if the transition is ignored.

  • Returns true if the transition is ignored.

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

    Returns boolean

    :

    true if the Transition is ignored.


  • Creates a UIInjector Dependency Injector

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

    If a state is provided, the injector that is returned will be limited to resolve values that the provided state has access to.

    Parameters

    • state Optional: StateOrName
      :

      Limits the resolves provided to only the resolves the provided state has access to.

    Returns UIInjector

    :

    a UIInjector


  • is(compare: Transition | object): boolean
  • Determines whether two transitions are equivalent.

  • isActive(): boolean
  • Registers a TransitionHookFn, called before a transition starts.

    Registers a transition lifecycle hook, which is invoked before a transition even begins. This hook can be useful to implement logic which prevents a transition from even starting, such as authentication, redirection

    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

    onBefore hooks are invoked before a Transition starts. No resolves have been fetched yet. Each onBefore hook is invoked synchronously, in the same call stack as StateService.transitionTo. The registered onBefore hooks are invoked in priority order.

    Note: during the onBefore phase, additional hooks can be added to the specific Transition instance. These "on-the-fly" hooks only affect the currently running transition..

    Return value

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

    If any hook modifies the transition synchronously (by throwing, returning false, or returning a TargetState), the remainder of the hooks are skipped. If a hook returns a promise, the remainder of the onBefore hooks are still invoked synchronously. All promises are resolved, and processed asynchronously before the onStart phase of the Transition.

    Examples

    Default Substate

    This example redirects any transition from 'home' to 'home.dashboard'. This is commonly referred to as a "default substate".

    example
    // ng2
    transitionService.onBefore({ to: 'home' }, (trans: Transition) =>
        trans.router.stateService.target("home.dashboard"));
    

    Data Driven Default Substate

    This example provides data-driven default substate functionality. It matches on a transition to any state which has defaultSubstate: "some.sub.state" defined. See: Transition.to which returns the "to state" definition.

    example
    // ng1
    // state declaration
    {
      name: 'home',
      template: '<div ui-view/>',
      defaultSubstate: 'home.dashboard'
    }
    
    var criteria = {
      to: function(state) {
        return state.defaultSubstate != null;
      }
    }
    
    $transitions.onBefore(criteria, function(trans: Transition) {
      var substate = trans.to().defaultSubstate;
      return trans.router.stateService.target(substate);
    });
    

    Require authentication

    This example cancels a transition to a state which requires authentication, if the user is not currently authenticated.

    This example assumes a state tree where all states which require authentication are children of a parent 'requireauth' state. This example assumes MyAuthService synchronously returns a boolean from isAuthenticated().

    example
    // ng1
    $transitions.onBefore( { to: 'requireauth.**' }, function(trans) {
      var myAuthService = trans.injector().get('MyAuthService');
      // If isAuthenticated returns false, the transition is cancelled.
      return myAuthService.isAuthenticated();
    });
    

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionStateHookFn, called when a specific state is entered.

    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.

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionHookFn, called after a transition has errored.

    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
    • A transition was cancelled by a Transition Hook returning false
    • A transition was redirected by a Transition Hook returning a TargetState
    • A transition was invalid because the target state/parameters are not valid
    • A transition was ignored because the target state/parameters are exactly the current state/parameters
    • 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

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionStateHookFn, called when a specific state is exited.

    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.

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionHookFn, called just before a transition finishes.

    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.

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionStateHookFn, called when a specific state is retained/kept.

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

    Since this hook is invoked when a transition is when the state is kept, it means the transition is coming from a substate of the kept state to a substate of the kept 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.

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionHookFn, called when a transition starts.

    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");
        });
      }
    });
    

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • Registers a TransitionHookFn, called after a successful transition completed.

    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

    Parameters

    Returns Function

    :

    a function which deregisters the hook.


  • params(pathname?: string): object
  • Gets transition parameter values

  • Gets transition parameter values

    Parameters

    • pathname Default value: string = "to"
      :

      Pick which treeChanges path to get parameters for: ('to', 'from', 'entering', 'exiting', 'retained')

    Returns object

    :

    transition parameter values for the desired path.

    • [key: string]: any

  • redirect(targetState: TargetState): Transition
  • Creates a new transition that is a redirection of the current one.

  • redirectedFrom(): Transition
  • If the current transition is a redirect, returns the transition that was redirected.

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

    Gets the transition from which this transition was redirected.

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

    Returns Transition

    :

    The previous Transition, or null if this Transition is not the result of a redirection


  • Gets the states being retained.

    Returns StateDeclaration[]

    :

    an array of states that are already entered from a previous Transition, that will not be exited during this Transition


  • run(): Promise<any>
  • Runs the transition

  • toString(): string
  • A string representation of the Transition

  • A string representation of the Transition

    Returns string

    :

    A string representation of the Transition


  • valid(): boolean
  • Checks if the Transition is valid

  • Get the ViewConfigs associated with this 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").

    Parameters

    • pathname Default value: string = "entering"
      :

      the name of the path to fetch views for: ('to', 'from', 'entering', 'exiting', 'retained')

    • state Optional: State
      :

      If provided, only returns the ViewConfigs for a single state in the path

    Returns ViewConfig[]

    :

    a list of ViewConfig objects for the given path.


Generated using TypeDoc