Home

Angular-promise-tracker Documentation

• Getting Started with angular-promise-tracker
• The promiseTracker Service
• Tracker Objects

## Getting Started with angular-promise-tracker

Here are some simple steps to get goin' quick with angular-promise-tracker!

1. Download angular-promise-tracker. You've got a few choices:

• Download through bower: bower install angular-promise-tracker
• Download the js file yourself: https://raw.github.com/ajoslin/angular-promise-tracker/master/promise-tracker.js
• Ask me to print the file and mail it to you, so you can get your scribe to type it up for you. That's why you have a scribe, after all...

2. <script src> that thang! Be sure to include it after angular.js!

• <script src="ninjas/promise-tracker.js"></script>

3. Add the promise-tracker module as a dependency to your AngularJS app:

• angular.module('ninjaTrackerApp', ['ajoslin.promise-tracker'])

4. Find a controller that does some sort of promise you want to track. Usually that'll be an $http call. Add promiseTracker service as a dependency to be injected that controller:

function NinjaBeaconCtrl($scope, $http, $timeout, promiseTracker) {
  $http.get('/ninja-beacon').then(function(response) {
    $scope.ninjaBeacon = response.data;
    $timeout(function() {
      alert('ninjas have arrived!');
    }, 2000);
  });
}

5. Create a promiseTracker, and add it to your scope. Then you can track some promises! Yes, even ninja promises can be tracked. promiseTracker is that good.

function NinjaBeaconCtrl($scope, $http, $timeout, promiseTracker) {
  //Create/get a promiseTracker called 'ninjas', and let the scope have access to it
  $scope.ninjaFinder = promiseTracker('ninjas');
  $http.get('/ninja-beacon', {
    tracker: 'ninjas' //tell our 'ninjas' tracker to track this http request's promise
  }).then(function(response) {
    $scope.ninjaBeacon = response.data;
    var wait = $timeout(function() {
      alert('ninjas have arrived!');
    }, 2000);
    //Tell our 'ninjas' tracker to also track our $timeout's 2000ms promise.
    //The `tracker:` approach we did a few lines ago is just a shortcut for this.
    $scope.ninjaFinder.addPromise(wait);
  });
}

6. Finally, we can display some cool loading stuff while our ninjas are arriving...! ninjaTracker.active() will evaluate to true while any promise added to it is unresolved. So in this case, it will be active until your $http call comes back and our $timeout is done.

<div ng-controller="NinjaBeaconCtrl">
  <div ng-show="ninjaFinder.active()" style="color: red; font-size: 50px;">
    The ninjas are on their way! They're loading! Just hold on a little longer!
  </div>
</div>

Intro Plunker Demo: comingsoon.com

## The promiseTracker Service

promiseTracker(trackerName[, options])

Returns the promiseTracker matching trackerName. If promiseTracker hasn't been created yet, it will be.

Allows an options parameter, JSON object. Available options are minDuration and maxDuration. See the config section for more information.

## A Tracker Object

var tracker = promiseTracker("ninjas");

**tracker.active()**

Returns true or false, saying whether this tracker is currently tracking one or more unresolved promises.

The most common use of this function is to assign a tracker to your scope, and in an html template do <my-spinner ng-show="tracker.active()"></my-spinner>.

#### tracker.addPromise(promise[, startEventParameter])

Starts tracking the given promise until is resolved or rejected. Optionally takes a startEventParameter to pass to tracker.on('start') event.

• Example:

  function MyCtrl($scope, $timeout, promiseTracker) {
    $scope.ninjaTracker = promiseTracker('ninjasWin');
    var timeoutPromise = $timeout(function() {
      alert('ninjas have arrived! uh oh!');
    }, 2000);
    $scope.ninjaTracker.addPromise(timeoutPromise);
  }

#### tracker.cancel() Stops tracking all current promises. [`tracker.active()`](#tracker-active) will immediately evaluate to false following `cancel()`.