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. There are a couple of choices:

• a. Download through bower: bower install angular-promise-tracker
• b. Download the js file yourself: https://raw.github.com/ajoslin/angular-promise-tracker/master/promise-tracker.js

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

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

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

• angular.module('myApp', ['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.

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 loading things 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>

## 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[, startParam])

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

• Example:

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

#### tracker.cancel()

Stops tracking all current promises. tracker.active() will immediately evaluate to false following cancel().

#### tracker.createPromise([startParam])

Creates a new promise to be tracked, but does not piggyback onto an existing promise. Returns a deferred object that will be tracked until it is resolved or rejected. Takes an optional startParam to pass to `tracker.on('start') event.