Merge branch 'master' into develop

Author: Vlad Balin

README.md

@@ -1,15 +1,16 @@
-# nestedreact
-This is React add-on designed to simplify migration to React views in large Backbone applications.
+# NestedReact
+This is React add-on providing advanced state management to React applications and convergence layer for intermixing React components and Backbone Views. 
 
-It allows you:
+Brief feature list:
 
-- To use React component in place of every Backbone View.
-- To use your existing Backbone Views from React components.
-- To use your existing Backbone Models as React component state.
-- Update React components on Backbone events.
-- Data-binding for models and collections
+- Advanced component's state management with [NestedTypes](https://github.com/Volicon/backbone.nestedTypes).
+- Comprehensive two-way data binding - [Guide to Data Binding Use Cases](/example/databinding.md)
+- Transparent interoperation with Backbone Views:
+	- React component can be used as backbone View. `new MyComponent.View({ props })`
+	- Backbone Views can be used as React components. `<React.subview View={ MyView } />`
+	- Simplified refactoring of Backbone Views to React components. `this.$`, `this.$el`, `this.$( sel )`, `this.model` works for React components too, as well as `this.trigger` and `this.listenTo`.
 
-Thus, no refactoring of your application is required. You can start writing UI with React immediately replacing your Backbone Views one-by-one, while keeping your existing models.
+Thus, if you have Bakcbone application and want to start writing with React - you have no excuses any more. Wanna keep some of your cool Views? They works just fine? Keep 'em. And use them in yout new components, written with React, which you will use in other Backbone Views.
 
 # Breaking changes introduced in 0.3
 - `component.createView( props )` doesn't work any more, use `new component.View( props )` instead.
@@ -196,6 +197,9 @@ In addition to standard members `link.requestChange( x )` and `link.value`, link
 
 Most efficient way to work with link is using `link.val()` function, that's how its internally implemented. `val` function is bound, and can be passed around safely.
 
+Here's a brief reference for liks API. Consult [Guide to Data Binding Use Cases](/example/databinding.md) to understand how to use it.
+
+
 ### Link transformations
 
 Attribute's link can be further transformed using extended link API. Link transformations allowing you to use new `stateless functions` component definition style introduced in React 0.14 in most cases.
@@ -232,5 +236,3 @@ attributes : {
 ```
 
 Technically, "watcher" - is just a callback function with a single argument receiving new attribute value, so links are not required here.
-
-[Guide to Data Binding Use Cases](/example/databinding.md)

example/databinding.md

@@ -2,6 +2,16 @@
 
 Here are the set of examples for typical `nestedreact` data binding use cases.
 
+Each section contains custom databound component, model definitions, and usage examples.
+
+Somewhere at the top level component(s) there must be the declaration linking model updates to UI. Either models must be (nested) members of some component's state (which will update UI even in case of deep changes), or you may link component updates to changes of models and collections passed in props. In the last case, you will need to add following line to top or middle-level component definition:
+
+```
+    listenToProps : 'myModel myCollection'
+```
+
+It's generally advised to keep stateful components at the top level, and use `listenToProps` in the middle level for optimization purposes if you want local updates. Keep you bottom-level components pure, and try to do the same for the most of your middle level (`listenToProps` used wisely won't hurt). For further information on this topic consult the top-level guide.
+
 ## Checkboxes
 
 Standard `<input/>` will work. Custom Checkbox component might be implemented like this:
@@ -204,4 +214,4 @@ const InputGroup = ({ model /* instanceof MyModel */ }) => (
         </div>
     );
 };
-```
+```

example/todolist.jsx

@@ -0,0 +1,81 @@
+import React from 'nestedreact'
+import { Model } from 'nestedtypes'
+
+// pre-define model, cause we gonna have recursive definition...
+const TodoItem = Model.extend();
+
+TodoItem.define({
+    defaults : {
+        done : Boolean,
+        desc : String,
+
+        // this is the tree, with components of the same type...
+        subitems : TodoItem.Collection
+    },
+
+    remove(){
+        this.collection.remove( this );
+    },
+
+    addChildren(){
+        this.subitems.push( new TodoItem() );
+    },
+
+    initialize(){
+        // Pin these methods, cause we gonna use them as click handlers...
+        _.bindAll( this, 'remove', 'addChildren' );
+
+        // Sync done state with subitems across the tree...
+        // There won't be loop, 'change' is never fired if there are no actual change.
+        this.listenTo( this, {
+            'change:subitems' : () => {
+                let { subitems } = this;
+
+                if( subitems && subitems.length ){
+                    this.done = subitems.every( item => item.done );
+                }
+            },
+
+            'change:done' : () => {
+                this.subitems.each( item => item.done = this.done );
+            }
+        });
+    }
+});
+
+const App = React.createClass({
+    // define the state...
+    attributes : {
+        // deep changes in this tree structure will be detected,
+        // and this component will be updated automatically.
+        todos : TodoItem.Collection
+    },
+
+    render(){
+        // State is already initialized with default values.
+        // Now, link the state to components...
+        return <Checklist todos={ this.state.todos } />;
+    }
+});
+
+// Everything else gonna be stateless...
+const Checklist = ({ todos } ) => (
+    <div className="checklist">
+        { todos.map( todo => <ToDo key={ todo.cid } todo={ todo } /> )}
+    </div>
+);
+
+const ToDo = ({ todo }) => (
+    <div className="todo-item">
+        <div className='header'>
+            <input type="checkbox"  checkedLink={ todo.getLink( 'done' ) } />
+            <input type="text"        valueLink={ todo.getLink( 'desc' ) } />
+            <div   class='add-children' onClick={ todo.addChildren }> + </div>
+            <div   class='delete'       onClick={ todo.remove } > x </div>
+        </div>
+        { todo.subitems.length && <Checklist todos={ todo.subitems } /> }
+    </div>
+);
+
+// Done.
+export default App;