BackboneORM

Introduction

BackboneHTTP provides an HTTP interface that can be used in the browser or from Node.js by using Superagent.

This allows for a iteration of remote collections from the browser using BackboneORM's unified query syntax and iteration methods.

CoffeeScript

class Project extends Backbone.Model
  urlRoot: '/projects'
  sync: require('backbone-http').sync(Project)

# Find all items with is_active = true
Project.find {is_active: true}, (err, projects) ->

# Iterate through all items with is_active = true in batches of 200
Project.each {is_active: true, $each: {fetch: 200}},
  ((project, callback) -> console.log "project: #{project.get('name')}"; callback()),
  (err) -> console.log 'Done'

# Stream all items with is_active = true in batches of 200
Project.stream({is_active: true, $each: {fetch: 200}})
  .pipe(new ModelStringifier())
  .on('finish', -> console.log 'Done')

var Project = Backbone.Model.extend({
  urlRoot: '/projects'
});
Project.prototype.sync = require('backbone-http').sync(Project);

// Find all items with is_active = true
Project.find({is_active: true}, function(err, projects) {});

// Iterate through all items with is_active = true in batches of 200
Project.each({is_active: true, $each: {fetch: 200}},
  function(project, callback) {console.log('project: ' + project.get('name')); callback()},
  function(err) {return console.log('Done');}
);

// Stream all items with is_active = true in batches of 200
Project.stream({is_active: true, $each: {fetch: 200}})
  .pipe(new ModelStringifier())
  .on('finish', function() {return console.log('Done');});

Getting Started

When loading BackboneHTTP in the browser, you can use global script tags, AMD, or a broswerified bundle. Also, you should set up a BackboneREST controller in your Node.js server to provide a JSON API for BackboneHTTP to consume.

Note: depending on the way BackboneORM is loaded, you may need to access it differently. See below examples for details.

Load Using Global Script Tags

BackboneHTTP can be used in the browser by using script tags.

<script type="text/javascript" src="underscore.js"></script>
<script type="text/javascript" src="backbone.js"></script>
<script type="text/javascript" src="moment.js"></script>
<script type="text/javascript" src="inflection.js"></script>
<script type="text/javascript" src="backbone-orm.js"></script>
<script type="text/javascript" src="superagent.js"></script>
<script type="text/javascript" src="backbone-http.js"></script>

<script type="text/javascript">
  var Test = Backbone.Model.extend({
    urlRoot: '/api/tests',
    model_name: 'Test'
  });
  Test.prototype.sync = BackboneHTTP.sync(Test);

  var test = new Test({name: 'Bob'});
  test.save(function(err){});
</script>

Load Using AMD

BackboneORM supports the AMD module loading pattern.

<script type="text/javascript" src="require.js"></script>

<script type="text/javascript">
  require.config({
    paths: {
      'underscore': "underscore", 'backbone': "backbone",
      'moment': "moment", 'inflection': "inflection",
      'backbone-orm': "backbone-orm",
      'superagent': "superagent",
      'backbone-http': "backbone-http"
    }
  });

  require(['underscore', 'backbone', 'backbone-orm', 'superagent', 'backbone-http'], function(_, Backbone, bborm, superagent, BackboneHTTP) {
    var Backbone = BackboneHTTP.modules.backbone;

    var Test = Backbone.Model.extend({
      urlRoot: '/api/tests',
      model_name: 'Test'
    });
    Test.prototype.sync = BackboneHTTP.sync(Test);

    var test = new Test({name: 'Bob'});
    test.save(function(err){});
  });
</script>

Load Using Browserify

You can browserify BackboneHTTP and include the full package into the browser:

npm install backbone-http

browserify -r backbone-http > backbone-http-bundle.js

Because browserify by default will pull in the stream interface, you can use the stream interface on the client.

  <script type="text/javascript" src="backbone-http-bundle.js"></script>

  <script type="text/javascript">
    var BackboneHTTP = require('backbone-http');
    var Backbone = BackboneHTTP.modules.backbone;

    var Test = Backbone.Model.extend({
      urlRoot: '/api/tests',
      model_name: 'Test'
    });
    Test.prototype.sync = BackboneHTTP.sync(Test);

    var test = new Test({name: 'Bob'});
    test.save(function(err){
      Test.stream()
        .on('data', function(model){ console.log("Model: " + model.get('name')); })
        .on('error', function(err){ console.log("An error is expected: " + err); });
    });
  </script>

Selecting JSON Templates

You can use the $template option in your calls to request JSON rendered by specific templates by BackboneREST.

For example, you can request a relationship to be embedded in the response to avoid a second call for related models. If you need all the attributes in a relationship, you could alternatively use include.