Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Easily add spinners or general request tracking to your angular app
JavaScript

README.md

angular-promise-tracker

Version: 2.0

(note to users using version 1.x: upgrading has many breaking changes, see the CHANGELOG.)

Build Status

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

  • 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.
      • 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.
    • 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.

    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 });

  • 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.

  • void tracker.addPromise(promise)

    Add any arbitrary promise to tracker. tracker.active() will be true until promise is 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
  • 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

  • Any $http call's 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] })

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-cli to build & test
  • Install local dependencies with bower install && npm install
  • Run grunt to lint, test, build the code, and build the docs site
  • Run grunt dev to watch and re-test on changes

New Versions

License

Public Domain Mark angular-promise-tracker by Andy Joslin is free of known copyright restrictions.

Something went wrong with that request. Please try again.