angular-promise-tracker

angular-promise-tracker =======================

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
angular-promise-tracker
2.2.28 years ago10 years agoMinified + gzip package size for angular-promise-tracker in KB

Popular Searches

Readme

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


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:
```js 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.
  • 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 add
Usage Example:
```js 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:
```js 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:
```js //Add $http promise to tracker with id 'myTracker' $http('/banana', { tracker: myPromiseTrackerInstance }) `` ``js //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.