Backbone.React.Component

Backbone.React.Component is a wrapper or mixin for React.Component and brings all the power of Facebook's React to Backbone.js.

It works as a bridge between React and Backbone enabling data binding between models, collections and components both on the client and server sides.

It comes in two flavours, a ready to use React mixin or a wrapper class with an extended API.

Table of Contents generated with DocToc

• Dependencies
• How To
  • Usage through the mixin
  • Usage through the component
    • Basic usage
    • Mounting the component
    • With a collection
    • With multiple models and collections
  • Usage on the server (Node.js)
  • How it works
  • Shared API (Component/Mixin)
    • $
    • getCollection()
    • getModel()
    • getOwner()
  • Component API
    • constructor(props, children)
    • extend(spec)
    • mount([el = this.el], [onRender])
    • unmount()
    • remove()
    • toHTML()
    • clone(props, children)
• Examples
• Tips
• TO DO

Dependencies

• Backbone (Underscore)
• React

How To

Using Bower

bower install backbone-react-component

Using Npm

npm install backbone-react-component

If you're not using Bower nor Npm download the source from the dist folder or use CDNJS.

Usage through the mixin

The usage of Backbone.React.Component.mixin is similar to Backbone.React.Component, though it relies on React top level API instead of wrapping it.

var MyComponent = React.createClass({
  mixins: [Backbone.React.Component.mixin],
  render: function () {
    return <div>{this.props.foo}</div>;
  }
});
var model = new Backbone.Model({foo: 'bar'});
var myComponent = <MyComponent model={model} />;

React.renderComponent(newComponent, document.body);
model.set('test', 'Hello world!');

Usage through the component

It follows all the principles behind React.Component, though it binds models and collections to the component's props besides giving you a set of extra methods (extend, toHTML, getModel, getCollection, $, etc). Many of the principles found in the following examples are applied to the mixin version as well.

Basic usage

/** @jsx React.DOM */
var MyComponent = Backbone.React.Component.extend({
  render: function () {
    return <div>{this.props.test}</div>;
  }
});
var model = new Backbone.Model();
var newComponent = new MyComponent({
  el: $('body'),
  model: model
});
model.set('test', 'Hello world!');

The Component will listen to any model changes, making it automatically refresh using React's algorithm.

Mounting the component

newComponent.mount();

With a collection

var newComponent = new MyComponent({
  el: $('body'),
  collection: new Backbone.Collection([{helloWorld: 'Hello world!'}])
});

var MyComponent = Backbone.React.Component.extend({
  createEntry: function (entry) {
    return <div>{entry.helloWorld}</div>;
  },
  render: function () {
    return <div>{this.props.collection.map(this.createEntry)}</div>;
  }
});

With multiple models and collections

var newComponent = new MyComponent({
  el: $('body'),
  model: {
    firstModel: new Backbone.Model({helloWorld: 'Hello world!'}),
    secondModel: new Backbone.Model({helloWorld: 'Hello world!'})
  },
  collection: {
    firstCollection: new Backbone.Collection([{helloWorld: 'Hello world!'}]),
    secondCollection: new Backbone.Collection([{helloWorld: 'Hello world!'}])
  }
});

var MyComponent = Backbone.React.Component.extend({
  createEntry: function (entry) {
    return <div>{entry.helloWorld}</div>;
  },
  render: function () {
    return (
      <div>
        {this.props.firstModel.helloWorld}
        {this.props.secondModel.helloWorld}
        {this.props.firstCollection.map(this.createEntry)}
        {this.props.secondCollection.map(this.createEntry)}
      </div>
    );
  }
});

Usage on the server (Node.js)

var Backbone = require('backbone');
var Component = require('backbone-react-component');
var React = require('react');

var model = new Backbone.Model({
  helloWorld: 'Hello world!'
});
var HelloWorld = Component.extend({
  render: function () {
    return React.DOM.div({}, this.props.helloWorld);
  }
});
var helloWorld = new HelloWorld({
  model: model
});
helloWorld.toHTML();
// Updating the model
model.set('helloWorld', 'Hi again!');
helloWorld.toHTML(); 

How it works

Backbone.React.Component is nothing more nothing less than a bridge between Backbone and React.

The following diagram illustrates how the data binding is achieved between our models/collections and a React.Component:

Bridge between Backbone and React

Shared API (Component/Mixin)

The following API is available on both mixin (through Backbone.React.Component.mixin) or Backbone.React.Component (through Backbone.React.Component.extend).

$

Inspired by Backbone.View, it's a shortcut to this.$el.find method.

getCollection()

Crawls to the owner of the component searching for a collection.

getModel()

Crawls to the owner of the component searching for a model.

getOwner()

Gets the component owner (greatest parent component).

Component API

Besides inheriting all the methods from React.Component and Backbone.Events you can find the following methods:

constructor(props, children)

props is an object and may contain el, model and collection properties. Model and collection properties may be multiple by passing an object as their values.

extend(spec)

This is a static method inspired by Backbone, it inherits a component definition (class) to a new one.

mount([el = this.el], [onRender])

• el (DOMElement)
• onRender (Callback) Mounts the component into the DOM.

unmount()

Unmounts the component. Throws an error if the component doesn't unmount successfully.

remove()

Stops component listeners and unmounts the component.

toHTML()

Intended to be used on the server, returns an HTML string representation of the component.

clone(props, children)

Returns a clone of the component.

Examples

• Blog
• Typewriter

Tips

• When using the component instead of the mixin remember your root components start listening to model and collection changes when created. To dispose of them call the remove method (mount/unmount no longer starts/stops listeners). If you're using the mixin you don't have to worry because disposal is automatic when the component unmounts.

TO DO

• Any ideas?