Showing posts with label angular-promise-tracker. Show all posts
Showing posts with label angular-promise-tracker. Show all posts
angular-promise-tracker

angular-promise-tracker

July 15, 2017
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.
  • 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:
       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


Note: Special thanks to Andy Joslin

Contact: andrewtjoslin@gmail.com

Disclaimer: The blog is created to share angular directives information to geek, curious Angular Developers.