A simple plugin to give poll capabilities to backbone collections and models that uses a refresh rate to actively fetch data and keep the collection or model updated. In other words, it gives a backbone collection or model the ability to periodically query a data source. Useful for fetching dynamic data for monitoring.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin/coverage
demo
dist
src
tests
.gitignore
.jshintrc
.travis.yml
Gruntfile.js
LICENCE
README.md
package.json

README.md

Backbone-Polling

Build Status

A simple plugin to give poll capabilities to backbone collections and models that uses a refresh rate to actively fetch data and keep the collection or model updated. In other words, it gives a backbone collection or model the ability to periodically query a data source. Useful for fetching dynamic data for monitoring.

Source Code And Downloads

Development: backbone-polling.js

Production: backbone-polling.min.js

Basic Demo

http://aqueous-badlands-8314.herokuapp.com

Dependencies

This plugin uses backbone (v1.0.0 or above) , jQuery (v1.10.2 or above) and underscore (version 1.3.3 or above).

Usage

One possible usage is to create a backbone collection (or model) and add the plugin as a mixin.

  • Example without AMD
var ProcessCollection = Backbone.Collection.extend({
    url: '/processes',
});

// Add backbone polling mixin
_.extend(ProcessCollection.prototype, BackbonePolling);
  • Example with AMD
define([
    'backbone',
    'underscore',
    'backbonePolling',
], function (Backbone, _, BackbonePolling) {
    'use strict';

    var ProcessCollection = Backbone.Collection.extend({
        url: '/processes',
    });

    // Add backbone polling mixin
    _.extend(ProcessCollection.prototype, BackbonePolling);

    return ProcessCollection;
});

Simply Instantiate and start fetching:

var processCollection = new ProcessCollection();
processCollection.startFetching();

Or pass in some options first:

var pollOptions = { refresh: 2000 };
var processCollection = new ProcessCollection();

// Specify custom options for the plugin.
// You can also call this function inside the collection's initialize function and pass the
// options for the plugin when instantiating a new collection.
processCollection.configure(pollOptions);
processCollection.startFetching();

Configuration Options

An object can be used to customize the plugin’s behavior. All configurations are optional.

var options = {
    refresh: 1000,                 // rate at which the plugin fetches data
    fetchOptions: {},              // options for the fetch request
    retryRequestOnFetchFail: true  // automatically retry request on fetch failure
}
  • refresh: refresh rate in milliseconds. Default value is 1000 milliseconds.
  • fetchOptions: to be passed in the collection.fetch() request (same options as the backbone collection’s fetch method).
  • retryRequestOnFetchFail: specify if the plugin should retry the request if fails or if it should simply stop fetching data.

Events

  • refresh:loaded: is triggered every time a fetch/refresh finishes successfully.
  • refresh:fail: is triggered every time a fetch request fails.
  • refresh:always: is triggered every time a fetch request finishes.

Methods

  • configure(options): specify custom options for the plugin
  • startFetching: starts polling data from the server.
  • stopFetching: stops fetching data from the server.
  • isFetching: returns true if the collection is fetching data and false otherwise.

License

The code in this repository can be used under the MIT License.