Package org.angular.ts.ng

Interface TransitionsService

@JsType(isNative=true, name="ng.TransitionsService", namespace="<global>") public interface TransitionsService
This interface specifies the api for registering Transition Hooks. Both the [[TransitionService]] and also the [[Transition]] object itself implement this interface. Note: the Transition object only allows hooks to be registered before the Transition is started.

  • Method Details

    • onBefore

      TransitionsService.DeregisterFn onBefore(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionHookFn callback, Object options)
      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".
      Parameters:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onEnter

      TransitionsService.DeregisterFn onEnter(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionStateHookFn callback, Object options)
      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.
      Parameters:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onError

      TransitionsService.DeregisterFn onError(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionHookFn callback, Object options)
      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 (`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 catch-all error reporting, configure `$router.error` or `$exceptionHandler`. ### Return value Since the Transition is already completed, the hook's return value is ignored
      Parameters:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onExit

      TransitionsService.DeregisterFn onExit(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionStateHookFn callback, Object options)
      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]]).
      Parameters:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onFinish

      TransitionsService.DeregisterFn onFinish(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionHookFn callback, Object options)
      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:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onRetain

      TransitionsService.DeregisterFn onRetain(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionStateHookFn callback, Object options)
      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 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]]).
      Parameters:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onStart

      TransitionsService.DeregisterFn onStart(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionHookFn callback, Object options)
      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 #### Load feature shell data during transition This example pauses transitions into a reporting branch while an application-level feature shell loads. Use state `resolve` for route data and `policy.navigation` for security; use transition hooks for advanced orchestration that intentionally spans multiple states. #### Example: ```js $transitions.onStart({ to: 'reports.**' }, function(trans) { var reportsShell = trans.injector().get('ReportsShell'); return reportsShell.ensureLoaded(); }); ```
      Parameters:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.

    • onSuccess

      TransitionsService.DeregisterFn onSuccess(jsinterop.base.JsPropertyMap<Object> matchCriteria, TransitionsService.TransitionHookFn callback, Object options)
      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:
      matchCriteria - defines which Transitions the Hook should be invoked for.
      callback - the hook function which will be injected and invoked.
      options - Value supplied for the options parameter.
      Returns:
      Method result.