diff --git a/docs/07.1-more-about-refs.md b/docs/07.1-more-about-refs.md index fd5fbab6..a62903e0 100644 --- a/docs/07.1-more-about-refs.md +++ b/docs/07.1-more-about-refs.md @@ -39,9 +39,11 @@ Consider the case when you wish to tell an `` element (that exists with ``` -Notice how, in this example, we want to "tell" the input something - something that it cannot infer from it's props over time. In this case we want to "tell" it that it should now become focused. However, there are some challenges. What is returned from render is not your actual composition of "child" components, it is merely a *description* of the children at a particular instance in time - a snapshot, if you will. +Notice how, in this example, we want to "tell" the input something - something that it cannot infer from it's props over time. In this case we want to "tell" it that it should now become focused. However, there are some challenges. What is returned from `render()`` is not your actual composition of "child" components, it is merely a *description* of the children at a particular instance in time - a snapshot, if you will. -NOTE: 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. +> Note: +> +> 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. @@ -64,19 +66,19 @@ In this counterexample, the `` is merely a *description* of an ` ``` -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 this.refs.myInput @@ -113,24 +115,21 @@ It's as simple as: }); ``` -In this example, our render function returns a description of an instance. But the true instance is accessed via `this.refs.theInput`. As long as a child component with `ref="theInput"` is returned from render, `this.refs.theInput` will access the the proper instance. This even works on higher level (non-DOM) components such as . +In this example, our render function returns a description of an `` instance. But the true instance is accessed via `this.refs.theInput`. As long as a child component with `ref="theInput"` is returned from render, `this.refs.theInput` will access the the proper instance. This even works on higher level (non-DOM) components such as ``. ## Summary Refs are a great way to send a message to a particular child instance in a way that would be inconvenient to do via streaming Reactive `props` and `state`. They should, however, not be your go-to abstraction for flowing data through your application. By default, use the Reactive data flow and save `ref`s for use cases that are inherently non-reactive. -**Benefits**: +### Benefits: -- You can define any public method on your component classes (such as a reset method on a Typeahead) and call those public methods through refs (such as this.refs.myTypeahead.reset()). +- You can define any public method on your component classes (such as a reset method on a Typeahead) and call those public methods through refs (such as `this.refs.myTypeahead.reset()`). +- Performing DOM measurements almost always requires reaching out to a "native" component such as `` and accessing its underlying DOM node via `this.refs.myInput.getDOMNode()`. Refs are one of the only practical ways of doing this reliably. +- Refs are automatically book-kept for you! If that child is destroyed, its ref is also destroyed for you. No worrying about memory here (unless you do something crazy to retain a reference yourself). -- Performing DOM measurements almost always requires reaching out to a "native" component such as and accessing its underlying DOM node via this.refs.myInput.getDOMNode(). Refs are one of the only practical ways of doing this reliably. -Refs are automatically book-kept for you! If that child is destroyed, its ref is also destroyed for you. No worrying about memory here (unless you do something crazy to retain a reference yourself). - -**Cautions**: - -- **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. +### Cautions: +- *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.