angular-promise-tracker
v2.2.2
Published
angular-promise-tracker =======================
Downloads
1,993
Readme
angular-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()); // => falsepromisetracker.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()); // => falsevoidtracker.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.