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
{}.
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..
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.
This example redirects any transition from 'home' to 'home.dashboard'. This is commonly referred to as a "default substate".
defines which Transitions the Hook should be invoked for.
the hook function which will be invoked.
Optionaloptions:
HookRegOptions
a function which deregisters the hook.
transitionService.onBefore({ to: 'home' }, (trans: Transition) =>
trans.router.stateService.target("home.dashboard"));
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.
// state declaration
{
name: 'home',
template: '<div ng-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);
});
This example cancels a transition away from an editor
state when the user declines to discard unsaved
changes. Cross-cutting security should use route
policy.navigation; transition hooks are
the escape hatch for feature-specific lifecycle work.
$transitions.onBefore({ from: 'editor' }, function(trans) {
var editor = trans.injector().get('EditorSession');
if (!editor.hasUnsavedChanges()) {
return true;
}
return window.confirm('Discard unsaved changes?');
});
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
{}.
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.
The hook's return value can be used to pause, cancel, or redirect the current Transition. See [[HookResult]] for more information.
Instead of registering onEnter hooks using
the [[TransitionService]], you may define an
onEnter hook directly on a state
declaration (see: [[StateDeclaration.onEnter]]).
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.
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
a function which deregisters the hook.
$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);
}
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);
}
}
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
{}.
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:
Transition superseded)
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.
Since the Transition is already completed, the hook's return value is ignored
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
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
{}.
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.
The hook's return value can be used to pause, cancel, or redirect the current Transition. See [[HookResult]] for more information.
Instead of registering onExit hooks using
the [[TransitionService]], you may define an
onExit hook directly on a state declaration
(see: [[StateDeclaration.onExit]]).
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
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
{}.
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.
The hook's return value can be used to pause, cancel, or redirect the current Transition. See [[HookResult]] for more information.
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
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 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
{}.
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.
The hook's return value can be used to pause, cancel, or redirect the current Transition. See [[HookResult]] for more information.
Instead of registering onRetain hooks using
the [[TransitionService]], you may define an
onRetain hook directly on a state
declaration (see: [[StateDeclaration.onRetain]]).
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
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
{}.
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.
The hook's return value can be used to pause, cancel, or redirect the current Transition. See [[HookResult]] for more information.
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.
$transitions.onStart({ to: 'reports.**' }, function(trans) {
var reportsShell = trans.injector().get('ReportsShell');
return reportsShell.ensureLoaded();
});
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
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
{}.
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.
Since the Transition is already completed, the hook's return value is ignored
defines which Transitions the Hook should be invoked for.
the hook function which will be injected and invoked.
Optionaloptions:
HookRegOptions
a function which deregisters the hook.
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.