Easily add spinners or general request tracking to your angular app
Version: 2.0
(note to users using version 1.x: upgrading has many breaking changes, see the CHANGELOG.)
Small, feature filled library used to easily add spinners or general promise/request tracking to your angular app.
The basic idea: each time we add one or more promises to an instance of a promiseTracker
, that instance's active()
method will return true until all added promises are resolved. A common use case is showing some sort of loading spinner while some http requests are loading.
Play with this example on plunkr
$ bower install angular-promise-tracker
<body ng-app="myApp" ng-controller="MainCtrl">
<div class="my-super-awesome-loading-box" ng-show="loadingTracker.active()">
Loading...
</div>
<button ng-click="delaySomething()">Delay Something</button>
<button ng-click="fetchSomething()">Fetch Something</button>
<script src="angular.js"></script>
<script src="promise-tracker.js"></script>
<!-- optional for $http sugar -->
<script src="promise-tracker-http-interceptor.js"></script>
</body>
angular.module('myApp', ['ajoslin.promise-tracker'])
.controller('MainCtrl', function($scope, $http, $timeout, promiseTracker) {
//Create a new tracker
$scope.loadingTracker = promiseTracker();
//use `addPromise` to add any old promise to our tracker
$scope.delaySomething = function() {
var promise = $timeout(function() {
alert('Delayed something!');
}, 1000);
$scope.loadingTracker.addPromise(promise);
};
//use `tracker:` shortcut in $http config to link our http promise to a tracker
//This shortcut is included in promise-tracker-http-interceptor.js
$scope.fetchSomething = function(id) {
return $http.get('/something', {
tracker: $scope.loadingTracker
}).then(function(response) {
alert('Fetched something! ' + response.data);
});
};
});
promiseTracker
tracker
promiseTracker([options])
Creates and returns a new promiseTracker.
Options can be given as an object, with the following allowed values:
activationDelay
{Number}
- Number of milliseconds that an added promise needs to be pending before this tracker is active.
{activationDelay: 500}
in options.minDuration
{Number}
- Minimum number of milliseconds that a tracker will stay active.
{minDuration: 750}
in options.Often you want a global promiseTracker (eg to show a loading screen); one easy way is to put the tracker on your $rootScope:
app.run(function($rootScope, promiseTracker) {
$rootScope.loadingTracker = promiseTracker();
});
Example: var myTracker = promiseTracker({ activationDelay: 500, minDuration: 750 });
boolean
tracker.active()
Returns whether this tracker is currently active. That is, whether any of the promises added to/created by this tracker are still pending. Note: if the activationDelay
has not elapsed yet, this will return false.
boolean
tracker.tracking()
Returns whether this tracker is currently tracking a request. That is, whether any of the promises added to/created by this tracker are still pending. This method has no regard for activationDelay
.
number
tracker.trackingCount()
The count of promises currently being tracked.
promise
tracker.addPromise(promise)
Add any arbitrary promise to tracker. tracker.active()
will be true until promise
is resolved or rejected.
promise
{object}
- Promise to addUsage Example:
var promise = $timeout(doSomethingCool, 1000);
myTracker.addPromise(promise);
console.log(myTracker.active()); // => true
//1000 milliseconds later...
console.log(myTracker.active()); // => false
promise
tracker.createPromise()
Creates and returns a new deferred object that is tracked by our promiseTracker.
Usage Example:
var deferred = myTracker.createPromise()
console.log(myTracker.active()); // => true
deferred.resolve();
console.log(myTracker.active()); // => false
void
tracker.cancel()
Causes a tracker to immediately become inactive and stop tracking all current promises.
$http
Sugar
Requires promise-tracker-http-interceptor.js
config
parameter can have a tracker
field. Examples://Add $http promise to tracker with id 'myTracker'
$http('/banana', { tracker: myPromiseTrackerInstance })
//Add $http promise to both 'tracker1' and 'tracker2'
$http.post('/elephant', {some: 'data'}, { tracker: [myFirstTracker, mySecondTracker] })
angular.module('app', ['ajoslin.promise-tracker'])
.factory('myTracker', function (promiseTracker) {
return promiseTracker();
})
.controller('AppCtrl', function ($rootScope, myTracker) {
$rootScope.$watch(myTracker.active, function (isActive) {
//doSomething()
});
});
npm install -g karma grunt-cli
to build & testbower install && npm install
grunt
to lint, test, build the code, and build the docs sitegrunt dev
to watch and re-test on changesangular-promise-tracker by Andy Joslin is free of known copyright restrictions.