JarCastingangular-promise-tracker
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.
Quick Start
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);
});
};
});
API Documentation
Service promiseTracker
-
trackerpromiseTracker([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.- Usage example: You have some http calls that sometimes return too quickly for a loading spinner to look good. You only want to show the tracker if a promise is pending for over 500ms. You put
{activationDelay: 500}in options.
- Usage example: You have some http calls that sometimes return too quickly for a loading spinner to look good. You only want to show the tracker if a promise is pending for over 500ms. You put
minDuration{Number}- Minimum number of milliseconds that a tracker will stay active.- Usage example: You want a loading spinner to always show up for at least 750ms. You put
{minDuration: 750}in options.
- Usage example: You want a loading spinner to always show up for at least 750ms. You put
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(); });
Instantiated promiseTracker
Example: var myTracker = promiseTracker({ activationDelay: 500, minDuration: 750 });
-
booleantracker.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
activationDelayhas not elapsed yet, this will return false. -
booleantracker.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. -
numbertracker.trackingCount()The count of promises currently being tracked.
-
promisetracker.addPromise(promise)Add any arbitrary promise to tracker.
tracker.active()will be true untilpromiseis resolved or rejected.promise{object}- Promise to add
Usage Example:
var promise = $timeout(doSomethingCool, 1000); myTracker.addPromise(promise); console.log(myTracker.active()); // => true //1000 milliseconds later... console.log(myTracker.active()); // => false
-
promisetracker.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
-
voidtracker.cancel()Causes a tracker to immediately become inactive and stop tracking all current promises.
$http Sugar
Requires promise-tracker-http-interceptor.js
- Any $http call's
configparameter can have atrackerfield. 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] })
More Examples
- Do something whenever the tracker's active state changes
angular.module('app', ['ajoslin.promise-tracker'])
.factory('myTracker', function (promiseTracker) {
return promiseTracker();
})
.controller('AppCtrl', function ($rootScope, myTracker) {
$rootScope.$watch(myTracker.active, function (isActive) {
//doSomething()
});
});
Development
- Install karma & grunt with
npm install -g karma grunt-clito build & test - Install local dependencies with
bower install && npm install - Run
gruntto lint, test, build the code, and build the docs site - Run
grunt devto watch and re-test on changes
New Versions
License
angular-promise-tracker by Andy Joslin is free of known copyright restrictions.
