Skip to content

Commit 55dcf33

Browse files
christopherthielenchristopherthielen
committed
docs(stateEvents): typedoc'ified the deprecated ng1 state events
1 parent 5a38ac3 commit 55dcf33

File tree

1 file changed

+136
-95
lines changed

1 file changed

+136
-95
lines changed

‎src/ng1/stateEvents.ts

Lines changed: 136 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,20 @@
11
/**
2-
* This file provides implementation of the deprecated UI-Router 0.2.x state events:
2+
* Provides implementation of the UI-Router 0.2.x state events.
33
*
4-
* @deprecated $stateChangeStart See: [[TransitionService.onStart]]
5-
* @deprecated $stateChangeSuccess See: [[TransitionService.onSuccess]]
6-
* @deprecated $stateChangeError See: [[TransitionService.onError]]
7-
* @deprecated $stateNotFound See: [[StateProvider.onInvalid]]
4+
* The 0.2.x state events are deprecated. We recommend moving to Transition Hooks instead, as they
5+
* provide much more flexibility, support async, and provide the context (the Transition, etc) necessary
6+
* to implement meaningful application behaviors.
87
*
9-
* @module ng1
8+
* To enable these state events, include the `stateEvents.js` file in your project, e.g.,
9+
* ```
10+
* <script src="stateEvents.js"></script>
11+
* ```
12+
* and also make sure you depend on the `ui.router.state.events` angular module, e.g.,
13+
* ```
14+
* angular.module("myApplication", ['ui.router', 'ui.router.state.events']
15+
* ```
16+
*
17+
* @module ng1_state_events
1018
*/
1119

1220
/** for typedoc */
@@ -17,6 +25,126 @@ import {StateService, StateProvider} from "../state/interface";
1725
import {TargetState} from "../state/module";
1826
import {Transition} from "../transition/transition";
1927

28+
/**
29+
* An event broadcast on `$rootScope` when the state transition **begins**.
30+
*
31+
* You can use `event.preventDefault()`
32+
* to prevent the transition from happening and then the transition promise will be
33+
* rejected with a `'transition prevented'` value.
34+
*
35+
* Additional arguments to the event handler are provided:
36+
* - `toState`: the Transition Target state
37+
* - `toParams`: the Transition Target Params
38+
* - `fromState`: the state the transition is coming from
39+
* - `fromParams`: the parameters from the state the transition is coming from
40+
* - `options`: any Transition Options
41+
* - `$transition$`: the [[Transition]]
42+
*
43+
* @example
44+
* ```
45+
*
46+
* $rootScope.$on('$stateChangeStart', function(event, transition) {
47+
* event.preventDefault();
48+
* // transitionTo() promise will be rejected with
49+
* // a 'transition prevented' error
50+
* })
51+
* ```
52+
*
53+
* @deprecated use [[TransitionService.onStart]]
54+
* @event $stateChangeStart
55+
*/
56+
var $stateChangeStart;
57+
58+
/**
59+
* An event broadcast on `$rootScope` if a transition is **cancelled**.
60+
*
61+
* Additional arguments to the event handler are provided:
62+
* - `toState`: the Transition Target state
63+
* - `toParams`: the Transition Target Params
64+
* - `fromState`: the state the transition is coming from
65+
* - `fromParams`: the parameters from the state the transition is coming from
66+
* - `options`: any Transition Options
67+
* - `$transition$`: the [[Transition]] that was cancelled
68+
*
69+
* @deprecated
70+
* @event $stateChangeCancel
71+
*/
72+
var $stateChangeCancel;
73+
74+
/**
75+
*
76+
* An event broadcast on `$rootScope` once the state transition is **complete**.
77+
*
78+
* Additional arguments to the event handler are provided:
79+
* - `toState`: the Transition Target state
80+
* - `toParams`: the Transition Target Params
81+
* - `fromState`: the state the transition is coming from
82+
* - `fromParams`: the parameters from the state the transition is coming from
83+
* - `options`: any Transition Options
84+
* - `$transition$`: the [[Transition]] that just succeeded
85+
*
86+
* @deprecated use [[TransitionService.onStart]] and [[Transition.promise]], or [[Transition.onSuccess]]
87+
* @event $stateChangeSuccess
88+
*/
89+
var $stateChangeSuccess;
90+
91+
/**
92+
* An event broadcast on `$rootScope` when an **error occurs** during transition.
93+
*
94+
* It's important to note that if you
95+
* have any errors in your resolve functions (javascript errors, non-existent services, etc)
96+
* they will not throw traditionally. You must listen for this $stateChangeError event to
97+
* catch **ALL** errors.
98+
*
99+
* Additional arguments to the event handler are provided:
100+
* - `toState`: the Transition Target state
101+
* - `toParams`: the Transition Target Params
102+
* - `fromState`: the state the transition is coming from
103+
* - `fromParams`: the parameters from the state the transition is coming from
104+
* - `error`: The reason the transition errored.
105+
* - `options`: any Transition Options
106+
* - `$transition$`: the [[Transition]] that errored
107+
*
108+
* @deprecated use [[TransitionService.onStart]] and [[Transition.promise]], or [[Transition.onError]]
109+
* @event $stateChangeError
110+
*/
111+
var $stateChangeError;
112+
113+
/**
114+
* An event broadcast on `$rootScope` when a requested state **cannot be found** using the provided state name.
115+
*
116+
* The event is broadcast allowing any handlers a single chance to deal with the error (usually by
117+
* lazy-loading the unfound state). A `TargetState` object is passed to the listener handler,
118+
* you can see its properties in the example. You can use `event.preventDefault()` to abort the
119+
* transition and the promise returned from `transitionTo()` will be rejected with a
120+
* `'transition aborted'` error.
121+
*
122+
* Additional arguments to the event handler are provided:
123+
* - `unfoundState` Unfound State information. Contains: `to, toParams, options` properties.
124+
* - `fromState`: the state the transition is coming from
125+
* - `fromParams`: the parameters from the state the transition is coming from
126+
* - `options`: any Transition Options
127+
* @example
128+
*
129+
* <pre>
130+
* // somewhere, assume lazy.state has not been defined
131+
* $state.go("lazy.state", { a: 1, b: 2 }, { inherit: false });
132+
*
133+
* // somewhere else
134+
* $scope.$on('$stateNotFound', function(event, transition) {
135+
* function(event, unfoundState, fromState, fromParams){
136+
* console.log(unfoundState.to); // "lazy.state"
137+
* console.log(unfoundState.toParams); // {a:1, b:2}
138+
* console.log(unfoundState.options); // {inherit:false} + default options
139+
* });
140+
* </pre>
141+
*
142+
* @deprecated use [[StateProvider.onInvalid]] // TODO: Move to [[StateService.onInvalid]]
143+
* @event $stateNotFound
144+
*/
145+
var $stateNotFound;
146+
147+
20148
(function() {
21149
let {isFunction, isString} = angular;
22150

@@ -35,30 +163,6 @@ import {Transition} from "../transition/transition";
35163

36164
let enabledEvents = $stateEvents.provider.enabled();
37165

38-
/**
39-
* @ngdoc event
40-
* @name ui.router.state.$state#$stateChangeStart
41-
* @eventOf ui.router.state.$state
42-
* @eventType broadcast on root scope
43-
* @description
44-
* Fired when the state transition **begins**. You can use `event.preventDefault()`
45-
* to prevent the transition from happening and then the transition promise will be
46-
* rejected with a `'transition prevented'` value.
47-
*
48-
* @param {Object} event Event object.
49-
* @param {Transition} Transition An object containing all contextual information about
50-
* the current transition, including to and from states and parameters.
51-
*
52-
* @example
53-
*
54-
* <pre>
55-
* $rootScope.$on('$stateChangeStart', function(event, transition) {
56-
* event.preventDefault();
57-
* // transitionTo() promise will be rejected with
58-
* // a 'transition prevented' error
59-
* })
60-
* </pre>
61-
*/
62166

63167
let toParams = $transition$.params("to");
64168
let fromParams = $transition$.params("from");
@@ -76,20 +180,6 @@ import {Transition} from "../transition/transition";
76180
}
77181

78182
$transition$.promise.then(function () {
79-
/**
80-
* @ngdoc event
81-
* @name ui.router.state.$state#$stateChangeSuccess
82-
* @eventOf ui.router.state.$state
83-
* @eventType broadcast on root scope
84-
* @description
85-
* Fired once the state transition is **complete**.
86-
*
87-
* @param {Object} event Event object.
88-
* @param to
89-
* @param toParams
90-
* @param from
91-
* @param fromParams
92-
*/
93183
$rootScope.$broadcast('$stateChangeSuccess', $transition$.to(), toParams, $transition$.from(), fromParams, $transition$.options(), $transition$);
94184
});
95185
}
@@ -99,24 +189,7 @@ import {Transition} from "../transition/transition";
99189
if (error && (error.type === 2 /* RejectType.SUPERSEDED */ || error.type === 3 /* RejectType.ABORTED */))
100190
return;
101191

102-
/**
103-
* @ngdoc event
104-
* @name ui.router.state.$state#$stateChangeError
105-
* @eventOf ui.router.state.$state
106-
* @eventType broadcast on root scope
107-
* @description
108-
* Fired when an **error occurs** during transition. It's important to note that if you
109-
* have any errors in your resolve functions (javascript errors, non-existent services, etc)
110-
* they will not throw traditionally. You must listen for this $stateChangeError event to
111-
* catch **ALL** errors.
112-
*
113-
* @param {Object} event Event object.
114-
* @param {State} toState The state being transitioned to.
115-
* @param {Object} toParams The params supplied to the `toState`.
116-
* @param {State} fromState The current state, pre-transition.
117-
* @param {Object} fromParams The params supplied to the `fromState`.
118-
* @param {Error} error The resolve error object.
119-
*/
192+
120193
let evt = $rootScope.$broadcast('$stateChangeError', $transition$.to(), toParams, $transition$.from(), fromParams, error, $transition$.options(), $transition$);
121194

122195
if (!evt.defaultPrevented) {
@@ -128,38 +201,6 @@ import {Transition} from "../transition/transition";
128201

129202
stateNotFoundHandler.$inject = ['$to$', '$from$', '$state', '$rootScope', '$urlRouter'];
130203
function stateNotFoundHandler($to$: TargetState, $from$: TargetState, $state: StateService, $rootScope, $urlRouter) {
131-
/**
132-
* @ngdoc event
133-
* @name ui.router.state.$state#$stateNotFound
134-
* @eventOf ui.router.state.$state
135-
* @eventType broadcast on root scope
136-
* @description
137-
* Fired when a requested state **cannot be found** using the provided state name during transition.
138-
* The event is broadcast allowing any handlers a single chance to deal with the error (usually by
139-
* lazy-loading the unfound state). A `TargetState` object is passed to the listener handler,
140-
* you can see its properties in the example. You can use `event.preventDefault()` to abort the
141-
* transition and the promise returned from `transitionTo()` will be rejected with a
142-
* `'transition aborted'` error.
143-
*
144-
* @param {Object} event Event object.
145-
* @param {Object} unfoundState Unfound State information. Contains: `to, toParams, options` properties.
146-
* @param {State} fromState Current state object.
147-
* @param {Object} fromParams Current state params.
148-
* @example
149-
*
150-
* <pre>
151-
* // somewhere, assume lazy.state has not been defined
152-
* $state.go("lazy.state", { a: 1, b: 2 }, { inherit: false });
153-
*
154-
* // somewhere else
155-
* $scope.$on('$stateNotFound', function(event, transition) {
156-
* function(event, unfoundState, fromState, fromParams){
157-
* console.log(unfoundState.to); // "lazy.state"
158-
* console.log(unfoundState.toParams); // {a:1, b:2}
159-
* console.log(unfoundState.options); // {inherit:false} + default options
160-
* });
161-
* </pre>
162-
*/
163204
let redirect = {to: $to$.identifier(), toParams: $to$.params(), options: $to$.options()};
164205
let e = $rootScope.$broadcast('$stateNotFound', redirect, $from$.state(), $from$.params());
165206

@@ -239,4 +280,4 @@ import {Transition} from "../transition/transition";
239280
.provider("$stateEvents", <IServiceProviderFactory> $StateEventsProvider)
240281
.run(['$stateEvents', function ($stateEvents) { /* Invokes $get() */
241282
}]);
242-
})();
283+
})();

0 commit comments

Comments
 (0)