From 43ecc6a7f0a361cc5bea2967806d670dceee91e1 Mon Sep 17 00:00:00 2001 From: Ben Alpert Date: Tue, 17 Jun 2014 23:19:45 -0700 Subject: [PATCH] Clarify refs and setState callback documentation --- docs/07.1-more-about-refs.md | 25 +++++++++++++++---------- docs/ref-02-component-api.md | 4 ++-- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/07.1-more-about-refs.md b/docs/07.1-more-about-refs.md index 20ba51e0..fa92805d 100644 --- a/docs/07.1-more-about-refs.md +++ b/docs/07.1-more-about-refs.md @@ -72,17 +72,19 @@ React supports a very special property that you can attach to any component that It's as simple as: -**1.** Assign a `ref` attribute to anything returned from `render` such as: +1. Assign a `ref` attribute to anything returned from `render` such as: -```html - -``` + ```html + + ``` -**2.** In some other code (typically event handler code), access the **backing instance** via `this.refs` as in: +2. In some other code (typically event handler code), access the **backing instance** via `this.refs` as in: -```javascript + ```javascript this.refs.myInput -``` + ``` + + You can access the component's DOM node directly by calling `this.refs.myInput.getDOMNode()`. ## Completing the Example @@ -95,8 +97,11 @@ It's as simple as: this.setState({userInput: e.target.value}); }, clearAndFocusInput: function() { - this.setState({userInput: ''}); // Clear the input - this.refs.theInput.getDOMNode().focus(); // Boom! Focused! + // Clear the input + this.setState({userInput: ''}, function() { + // This code executes after the component is re-rendered + this.refs.theInput.getDOMNode().focus(); // Boom! Focused! + }); }, render: function() { return ( @@ -132,4 +137,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. +- 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. diff --git a/docs/ref-02-component-api.md b/docs/ref-02-component-api.md index 4b457b2d..ce64972a 100644 --- a/docs/ref-02-component-api.md +++ b/docs/ref-02-component-api.md @@ -29,7 +29,7 @@ setProps(object nextProps[, function callback]) When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`. -Though calling `React.renderComponent()` again on the same node is the preferred way to update a root-level component, you can also call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed. +Though calling `React.renderComponent()` again on the same node is the preferred way to update a root-level component, you can also call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed and the component is re-rendered. > Note: > @@ -80,7 +80,7 @@ Properties that are specified directly on the target component instance (such as setState(object nextState[, function callback]) ``` -Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once `setState` is completed. +Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once `setState` is completed and the component is re-rendered. > Notes: >