Merge pull request #29 from petehunt/mixin-docs

[docs] Return of mixin docs

docs/_config.yml

@@ -1,14 +1,14 @@
----
-pygments: true
+--- 
+markdown: redcarpet
 name: React
+redcarpet: 
+  extensions: 
+  - fenced_code_blocks
 react_version: 0.3.0
-exclude:
+pygments: true
+exclude: 
 - Gemfile
 - Gemfile.lock
 - README.md
 - Rakefile
-redcarpet:
-  extensions:
-  - fenced_code_blocks
-markdown: redcarpet
 baseurl: /react

docs/_includes/nav_docs.html

@@ -17,6 +17,7 @@ <h3>Reference</h3>
       <li><a href="/react/docs/component-lifecycle.html"{% if page.id == 'docs-component-lifecycle' %} class="active"{% endif %}>Component Lifecycle</a></li>
       <li><a href="/react/docs/event-handling.html"{% if page.id == 'docs-event-handling' %} class="active"{% endif %}>Event Handling</a></li>
       <li><a href="/react/docs/advanced-components.html"{% if page.id == 'docs-advanced-components' %} class="active"{% endif %}>Advanced Components</a></li>
+      <li><a href="/react/docs/mixins.html"{% if page.id == 'docs-mixins' %} class="active"{% endif %}>Mixins</a></li>
       <li><a href="/react/docs/api.html"{% if page.id == 'docs-api' %} class="active"{% endif %}>API</a></li>
     </ul>
   </div>

docs/docs/advanced-components.md

@@ -4,7 +4,7 @@ title: Advanced Components
 description: How to build advanced composite components.
 layout: docs
 prev: event-handling.html
-next: api.html
+next: mixins.html
 ---
 
 Composite components extend a `ReactCompositeComponent` base class that provides

docs/docs/api.md

@@ -2,7 +2,7 @@
 id: docs-api
 title: React API
 layout: docs
-prev: advanced-components.html
+prev: mixins.html
 ---
 
 ## React

docs/docs/mixins.md

@@ -0,0 +1,65 @@
+---
+id: docs-mixins
+title: Mixins
+layout: docs
+prev: advanced-components.html
+next: api.html
+---
+
+Mixins allow code to be shared between multiple React components. They are pretty similar to mixins
+in Python or traits in PHP. Let's look at a simple example:
+
+```javascript
+var MyMixin = {
+  getMessage: function() {
+    return 'hello world';
+  }
+};
+
+var MyComponent = React.createClass({
+  mixins: [MyMixin],
+  render: function() {
+    return <div>{this.getMessage()}</div>;
+  }
+});
+```
+
+A class can use multiple mixins, but no two mixins can define the same method. Two mixins can, however,
+implement the same [lifecycle method](component-lifecycle.html). In this case, each implementation will be invoked one after another.
+
+The only exception is the `shouldComponentUpdate` lifecycle method. This method may only be implemented once
+(either by a mixin or by the component).
+
+```javascript
+var Mixin1 = {
+  componentDidMount: function() {
+    console.log('Mixin1.componentDidMount()');
+  }
+};
+
+var Mixin2 = {
+  componentDidMount: function() {
+    console.log('Mixin2.componentDidMount()');
+  }
+};
+
+
+var MyComponent = React.createClass({
+  mixins: [Mixin1, Mixin2],
+  render: function() {
+    return <div>hello world</div>;
+  }
+});
+```
+
+When `MyComponent` is mounted into the page, the following text will print to the console:
+
+```
+Mixin1.componentDidMount()
+Mixin2.componentDidMount()
+```
+
+## When should you use mixins?
+
+In general, add a mixin whenever you want a component to share some utility methods, public interface,
+or lifecycle behavior. Often it's appropriate to use them as you would use a superclass in another OOP language.