Added documentation for stateless components, condensed the two pages about refs into a single page.

jimfb · jimfb · commit 80eab352cf93 · 2015-09-25T14:37:59.000-07:00
diff --git a/docs/_data/nav_tips.yml b/docs/_data/nav_tips.yml
@@ -30,8 +30,6 @@
     title: Communicate Between Components
   - id: expose-component-functions
     title: Expose Component Functions
-  - id: references-to-components
-    title: References to Components
   - id: children-undefined
     title: this.props.children undefined
   - id: use-react-with-other-libraries
diff --git a/docs/docs/05-reusable-components.md b/docs/docs/05-reusable-components.md
@@ -232,3 +232,33 @@ Methods follow the same semantics as regular ES6 classes, meaning that they don'
 ### No Mixins
 
 Unfortunately ES6 launched without any mixin support. Therefore, there is no support for mixins when you use React with ES6 classes. Instead, we're working on making it easier to support such use cases without resorting to mixins.
+
+
+
+## Stateless Functions
+
+You may also define your React classes as a plain JavaScript function. For example using the stateless function syntax:
+
+```javascript
+function HelloMessage(props) {
+  return <div>Hello {props.name}</div>;
+}
+React.render(<HelloMessage name="Sebastian" />, mountNode);
+```
+
+Or using the new ES6 arrow syntax:
+
+```javascript
+var HelloMessage = (props) => <div>Hello {props.name}</div>;
+React.render(<HelloMessage name="Sebastian" />, mountNode);
+```
+
+
+This simplified component API is intended for components that are pure functions of their props.  These components must not retain internal state, do not have backing instances, and do not have the component lifecycle methods.  They are pure functional transforms of their input, with zero boilerplate.
+
+> NOTE:
+> 
+> Because stateless functions don't have a backing instance, you can't attach a ref to a stateless function component.  Normally this isn't an issue, since stateless functions do not provide an imperative API, there really isn't much you could do with an instance anyway.  However, if a user wants to find the DOM node of a stateless function component, they must wrap the component in a stateful component (eg. ES6 class component) and attach the ref to the stateful wrapper component.
+
+In an ideal world, most of your components would be stateless functions because these stateless components can follow a faster code path within the React core.  This is the recommended pattern, when possible.
+
diff --git a/docs/docs/08.1-more-about-refs.md b/docs/docs/08.1-more-about-refs.md
@@ -1,13 +1,97 @@
 ---
 id: more-about-refs
-title: More About Refs
+title: References to Components
 permalink: more-about-refs.html
 prev: working-with-the-browser.html
 next: tooling-integration.html
 ---
-After returning the structure of your UI from the render method, you may find yourself wanting to "reach out" and invoke methods on component instances returned from `render()`. Often, doing something like this isn't necessary for making data flow through your application, because the Reactive data flow always ensures that the most recent `props` are sent to each child that is output from `render()`. However, there are a few cases where it still might be necessary or beneficial.
+After building your component, you may find yourself wanting to "reach out" and invoke methods on component instances returned from `render()`.  In most cases, this is ideally unnecessary (and should be avoided) because the reactive data flow always ensures that the most recent props are sent to each child that is output from render().  However, there are a few cases where it still might be necessary or beneficial, so React provides an escape hatch known as `refs`.  These `refs` (references) are especially useful when you need to find the DOM markup rendered by a component (for instance, to position it absolutely), when using React components in a larger non-React application, or when transitioning your code to React.
 
-Consider the case, when you wish to tell an `<input />` element (that exists within your instances sub-hierarchy) to focus after you update its value to be the empty string, `''`.
+Consider the case, when you wish to tell an `<input />` element (that exists within your instances sub-hierarchy) to focus after you update its value to be the empty string, `''`.  That is to say, we want to implement an imperative function that will reset your application's input field to the empty state.  This is a reasonable use case for refs, and one which we will explore in a moment, but first we'll look at the various options for getting a reference.
+
+## The ref returned from React.render
+
+No to be confused with the `render()` function that you define on your component (and which returns a virtual DOM element), [React.render()](/react/docs/top-level-api.html#react.render) will return a reference to your component's **backing instance** (or null for [stateless components](/react/docs/reusable-components.html#stateless-functions)).
+
+
+```js
+var myComponent = React.render(<MyComponent />, myContainer);
+```
+
+Keep in mind, however, that the JSX doesn't return a component instance! It's just a **ReactElement**: a lightweight representation that tells React what the mounted component should look like.
+
+```js
+var myComponentElement = <MyComponent />; // This is just a ReactElement.
+
+// Some code here...
+
+var myComponentInstance = React.render(myComponentElement, myContainer);
+myComponentInstance.doSomething();
+```
+
+> Note:
+>
+> This should only ever be used at the top level. Inside components, let your `props` and `state` handle communication with child components, or use one of the other methods of getting a ref (string attribute or callbacks).
+
+
+## The ref Callback Attribute
+
+React supports a very special attribute that you can attach to any component.  The `ref` attribute can be a callback function, and this callback will be executed immediately after the component is mounted.  The referenced component will be passed in as a parameter, and the callback function may use the component immediately, or save the reference for future use (or both).
+
+It's as simple as adding a `ref` attribute to anything returned from `render` by using an ES6 arrow function:
+
+```html
+  render: function() {
+    return <TextInput ref={(c) => this._input = c} />;
+  },
+  componentDidMount: function() {
+    this._input.focus();
+  },
+```
+
+or
+
+```html
+  render: function() {
+    return (
+      <TextInput
+        ref={function(input) {
+          if (input != null) {
+            input.focus();
+          }
+        }} />
+    );
+  },
+```
+
+  Note that when the referenced component is unmounted and whenever the ref changes, the old ref will be called with `null` as an argument. This prevents memory leaks in the case that the instance is stored, as in the first example. Note that when writing refs with inline function expressions as in the examples here, React sees a different function object each time so on every update, ref will be called with `null` immediately before it's called with the component instance.
+
+  You can access the component's DOM node directly by calling `React.findDOMNode(argumentToYourCallback)`.
+
+
+## The ref String Attribute
+
+ React also supports using a string (instead of a callback) as a ref prop on any component, although this approach is mostly legacy at this point.
+
+1. Assign a `ref` attribute to anything returned from `render` such as:
+
+    ```html
+    <input ref="myInput" />
+    ```
+
+2. In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
+
+    ```javascript
+    this.refs.myInput
+    ```
+
+  You can access the component's DOM node directly by calling `React.findDOMNode(this.refs.myInput)`.
+
+
+## A Complete Example
+
+
+Consider the case, when you wish to tell an `<input />` element (that exists within your instances sub-hierarchy) to focus after you update its value to be the empty string, `''`.  That is to say, we want to implement an imperative function that will reset your application's input field to the empty state.
 
 ```javascript
   var App = React.createClass({
@@ -19,7 +103,7 @@ Consider the case, when you wish to tell an `<input />` element (that exists wit
     },
     clearAndFocusInput: function() {
       this.setState({userInput: ''}); // Clear the input
-      // We wish to focus the <input /> now!
+      // TODO: We wish to focus the <input /> now!
     },
     render: function() {
       return (
@@ -44,7 +128,6 @@ Notice how, in this example, we want to "tell" the input something - something t
 >
 > Remember, what you return from `render()` is not your *actual* rendered children instances. What you return from `render()` is merely a *description* of the children instances in your component's sub-hierarchy at a particular moment in time.
 
-
 This means that you should never "hold onto" something that you return from `render()` and then expect it to be anything meaningful.
 
 ```javascript
@@ -65,61 +148,6 @@ In this example, the `<input />` is merely a *description* of an `<input />`. Th
 
 So how do we talk to the *real* backing instance of the input?
 
-## The ref String Attribute
-
-React supports a very special property that you can attach to any component that is output from `render()`. This special property allows you to refer to the corresponding **backing instance** of anything returned from `render()`. It is always guaranteed to be the proper instance, at any point in time.
-
-It's as simple as:
-
-1. Assign a `ref` attribute to anything returned from `render` such as:
-
-    ```html
-    <input ref="myInput" />
-    ```
-
-2. In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
-
-    ```javascript
-    this.refs.myInput
-    ```
-
-  You can access the component's DOM node directly by calling `React.findDOMNode(this.refs.myInput)`.
-
-
-## The ref Callback Attribute
-
-The `ref` attribute can be a callback function instead of a name.  This callback will be executed immediately after the component is mounted.  The referenced component will be passed in as a parameter, and the callback function may use the component immediately, or save the reference for future use (or both).
-
-It's as simple as adding a `ref` attribute to anything returned from `render` by using an ES6 arrow function:
-
-```html
-  render: function() {
-    return <TextInput ref={(c) => this._input = c} />;
-  },
-  componentDidMount: function() {
-    this._input.focus();
-  },
-```
-
-or
-
-```html
-  render: function() {
-    return (
-      <TextInput
-        ref={function(input) {
-          if (input != null) {
-            input.focus();
-          }
-        }} />
-    );
-  },
-```
-
-Note that when the referenced component is unmounted and whenever the ref changes, the old ref will be called with `null` as an argument. This prevents memory leaks in the case that the instance is stored, as in the first example. Note that when writing refs with inline function expressions as in the examples here, React sees a different function object each time so on every update, ref will be called with `null` immediately before it's called with the component instance.
-
-
-## Completing the Example
 
 ```javascript
   var App = React.createClass({
@@ -171,3 +199,4 @@ Refs are a great way to send a message to a particular child instance in a way t
 - *Never* access refs inside of any component's render method - or while any component's render method is even running anywhere in the call stack.
 - If you want to preserve Google Closure Compiler Crushing resilience, make sure to never access as a property what was specified as a string. This means you must access using `this.refs['myRefString']` if your ref was defined as `ref="myRefString"`.
 - If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" – instead, the data flow will usually accomplish your goal.
+- Refs may not be attached to a [stateless function](/react/docs/reusable-components.html#stateless-functions), because the component does not have a backing instance.  You can always wrap a stateless component in a standard composite component and attach a ref to the composite component.
diff --git a/docs/docs/ref-01-top-level-api.md b/docs/docs/ref-01-top-level-api.md
@@ -81,7 +81,7 @@ ReactComponent render(
 )
 ```
 
-Render a ReactElement into the DOM in the supplied `container` and return a reference to the component.
+Render a ReactElement into the DOM in the supplied `container` and return a [reference](/react/docs/more-about-refs.html) to the component (or returns null for [stateless components](/react/docs/reusable-components.html#stateless-functions)).
 
 If the ReactElement was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
 
diff --git a/docs/tips/15-expose-component-functions.md b/docs/tips/15-expose-component-functions.md
@@ -4,7 +4,7 @@ title: Expose Component Functions
 layout: tips
 permalink: expose-component-functions.html
 prev: communicate-between-components.html
-next: references-to-components.html
+next: children-undefined.html
 ---
 
 There's another (uncommon) way of [communicating between components](/react/tips/communicate-between-components.html): simply expose a method on the child component for the parent to call.
diff --git a/docs/tips/16-references-to-components.md b/docs/tips/16-references-to-components.md
@@ -7,22 +7,4 @@ prev: expose-component-functions.html
 next: children-undefined.html
 ---
 
-If you're using React components in a larger non-React application or transitioning your code to React, you may need to keep references to components. `React.render` returns a reference to the mounted component:
-
-```js
-var myComponent = React.render(<MyComponent />, myContainer);
-```
-
-Keep in mind, however, that the JSX doesn't return a component instance! It's just a **ReactElement**: a lightweight representation that tells React what the mounted component should look like.
-
-```js
-var myComponentElement = <MyComponent />; // This is just a ReactElement.
-
-// Some code here...
-
-var myComponentInstance = React.render(myComponentElement, myContainer);
-```
-
-> Note:
->
-> This should only ever be used at the top level. Inside components, let your `props` and `state` handle communication with child components, and only reference components via [refs](/react/docs/more-about-refs.html).
+This page has moved to: [refs](/react/docs/more-about-refs.html).
diff --git a/docs/tips/17-children-undefined.md b/docs/tips/17-children-undefined.md
@@ -3,7 +3,7 @@ id: children-undefined
 title: this.props.children undefined
 layout: tips
 permalink: children-undefined.html
-prev: references-to-components.html
+prev: expose-component-functions.html
 next: use-react-with-other-libraries.html
 ---
 

Original file line number	Diff line number	Diff line change
`@@ -81,7 +81,7 @@ ReactComponent render(`
`81`	`81`	`)`
`82`	`82`	```
`83`	`83`
`84`		-Render a ReactElement into the DOM in the supplied `container` and return a reference to the component.
	`84`	+Render a ReactElement into the DOM in the supplied `container` and return a [reference](/react/docs/more-about-refs.html) to the component (or returns null for [stateless components](/react/docs/reusable-components.html#stateless-functions)).
`85`	`85`
`86`	`86`	If the ReactElement was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
`87`	`87`