rb-controllerview v1.0.0
React-Backbone Controller View
A simple mixin to bind Backbone models and collections to React components.
Aims to do four things:
- Embrace React's uni-directional data flow
- Provide a simple declarative approach
- Let you write less code
- Allow for full view control on model/collection changes
### Contents:
## Installation & quick start
### 1. Install the mixin:
npm install rb-controllerview
2. Add the mixin to your components
var React = require('react');
var ControllerView = require('rb-controllerview');
var MyComponent = React.createClass({
mixins: [ ControllerView ],
// Declare any models in the view - any models will get set to state
// by calling `toJSON()` internally.
getModels: function () {
return {
user: new Backbone.Model({ name: 'Chris Houghton '})
};
},
render: function () {
return (
<div>
Hey there, my name is {this.state.user.name}.
</div>
);
}
});
3. Updates automatically happen
Whenever the model updates, the state
will automatically be updated, resulting
in the desired UI updates.
## Inspiration
While there are a number of other Backbone-related React components out there, none of them provide a simple & declarative approach. When looking ourselves, we found that a lot of the components out there seemed to be fighting "the React way", rather than going along with it.
React's concept of uni-directional data flow is crackin'. It adds simplicity to applications, making components simple to understand and debug.
When integrating Backbone with React, there's a few key challenges & questions:
- How can I ensure that views update when the model/collection changes?
- Is it possible to avoid writing
on('change')
andon('sync')
all over the place? - Just which component "owns" the data?
There's a few possible options:
Option | The good & the bad |
---|---|
1. Passing the model directly as a prop , and using a parent "controller" around each component. | Sounds simple, it isn't. The component won't automatically hook into model updates and update the views, so you'll need forceUpdate (bad). Also, if the model is passed to child components, anyone in the hierarchy can update the data, which breaks uni-directional flow. |
2. Declaring the model directly as a property of the component. | This is cleaner, you'll usually declare the model within componentWillMount . Even if you don't pass the model directly to children, there's still the above issue of running forceUpdate . |
3. Set the model's full data to state before mount, and never pass the model to children. | Cleaner still. Also, by setting all data to state, React will automatically update components. The component that "owns" the model can make the updates, if the children need to, then can do so by passing functions as props . (Fits with React uni-directional flow) |
This mixin goes for the third option:
- Models & collections are declared internally within the component before mount
- All data from models and collections is set to
state
- Updates/syncs automatically cause the
state
to update (but they don't have to)
The term "controller-view" was inspired by Flux, where one React component controls the data flow, and acts as the glue between the data models and the UI.
To answer the question:
"Where should the controller view live in the hierarchy?"
It's actually better to ask the question:
"Where should the state live in the hierarchy?"
And to answer this question, read this part of "Thinking in React".
API & usage
Before using this mixin, there's a few things to remember:
- Models & collections should be declared in the
getModels
andgetCollections
functions, returning key-model objects - Models & collections are automatically set to
state
using the key in the declaration above (happens incomponentWillMount
) - Models automatically get re-set to
state
on the Backbone events:sync
,change
- Collections automatically get re-set to
state
on the Backbone events:sync
,change
,add
,remove
- Don't declare models and collections with the same key, or with the key of another state value
### Basic usage
You'll need to declare ControllerView
as a mixin in the React component you'd like to act as a
controller-view, and then declare your Backbone models and collections using getModels
and getCollections
.
For example, you might have a page where you can see a list of skittles that a user owns:
var $ = require('jquery');
var React = require('react');
var ControllerView = require('rb-controllerview');
var user = require('models/user'); // instance, not class
var skittles = require('collections/skittles'); // instance, not class
var UserSkittles = React.createClass({
mixins: [ ControllerView ],
getModels: function () {
return {
user: user
};
},
getCollections: function () {
return {
skittles: skittles
};
},
render: function () {
var skittles = this.state.skittles.map(function (skittle) {
return <li key={skittle.id}>{skittle.color}</li>
});
return (
<div>
{this.state.user.name+"'s"} skittles:
<ul>
{skittles}
</ul>
</div>
);
}
});
module.exports = UserSkittles;
Hooking into model updates to selectively update the state (and the UI)
To intercept the model and collection updates, you can declare modelDidUpdate
or collectionDidUpdate
on the component. Declaring these will entirely prevent the auto-setting to state, so you'll need
to set the data manually:
modelDidUpdate: function (modelKey) {
// don't set user data to state for now
if (modelKey === 'user') {
return;
}
// but do set everything else!
else {
var newState = {};
newState[modelKey] = this.models[modelKey].toJSON();
this.setState(newState);
}
}
Tip: use sparingly.
Working examples
Check out the examples folder. (Clone this repo and run locally)
Changelog
- 1.0.0 initial release w/ unit tests
## Contributing
Got an idea for making this mixin better? Found a bug?
Submit an issue. Pull requests are welcome. Please ensure that any changes
pass linting and unit tests. (Run grunt
)
## License
Licensed under MIT.
8 years ago