@samitouri / QOS-React-2 / commits / 030fc752ba

Updated docs examples/recommendations to use findDOMNode instead of getDOMNode

Jim committed Jan 2, 2015 at 14:51 UTC 030fc752bae304870e3cc1d65ce0e4f4b78cf61c

7 files changed +34 -28

docs/docs/08-working-with-the-browser.md

+5 -5

@@ -18,13 +18,13 @@ Additionally, React implements a full synthetic event system such that all event

18 Most of the time you should stay within React's "faked browser" world since it's more performant and easier to reason about. However, sometimes you simply need to access the underlying API, perhaps to work with a third-party library like a jQuery plugin. React provides escape hatches for you to use the underlying DOM API directly.

21 -## Refs and getDOMNode()

21 +## Refs and findDOMNode()

23 -To interact with the browser, you'll need a reference to a DOM node. Every mounted React component has a `getDOMNode()` function which you can call to get a reference to it.

23 +To interact with the browser, you'll need a reference to a DOM node. React has a `React.findDOMNode(component)` function which you can call to get a reference to the component's DOM node.

25 > Note:

26 >

27 -> `getDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `getDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.

27 +> `findDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.

29 In order to get a reference to a React component, you can either use `this` to get the current React component, or you can use refs to refer to a component you own. They work like this:

@@ -32,7 +32,7 @@ In order to get a reference to a React component, you can either use `this` to g

32 var MyComponent = React.createClass({

33 handleClick: function() {

34 // Explicitly focus the text input using the raw DOM API.

35 - this.refs.myTextInput.getDOMNode().focus();

35 + React.findDOMNode(this.refs.myTextInput).focus();

36 },

37 render: function() {

38 // The ref attribute adds a reference to the component to

@@ -97,7 +97,7 @@ React provides lifecycle methods that you can specify to hook into this process.

98 _Mounted_ composite components also support the following methods:

100 -* `getDOMNode(): DOMElement` can be invoked on any mounted component in order to obtain a reference to its rendered DOM node.

100 +* `findDOMNode(): DOMElement` can be invoked on any mounted component in order to obtain a reference to its rendered DOM node.

101 * `forceUpdate()` can be invoked on any mounted component when you know that some deeper aspect of the component's state has changed without using `this.setState()`.

102

103

docs/docs/08.1-more-about-refs.md

+3 -3

@@ -83,7 +83,7 @@ It's as simple as:

83 this.refs.myInput

84 ```

86 - You can access the component's DOM node directly by calling `this.refs.myInput.getDOMNode()`.

86 + You can access the component's DOM node directly by calling `React.findDOMNode(this.refs.myInput)`.

88 ## Completing the Example

@@ -99,7 +99,7 @@ It's as simple as:

99 // Clear the input

100 this.setState({userInput: ''}, function() {

101 // This code executes after the component is re-rendered

102 - this.refs.theInput.getDOMNode().focus(); // Boom! Focused!

102 + React.findDOMNode(this.refs.theInput).focus(); // Boom! Focused!

103 });

104 },

105 render: function() {

@@ -129,7 +129,7 @@ Refs are a great way to send a message to a particular child instance in a way t

129 ### Benefits:

130

131 - 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()`).

132 -- Performing DOM measurements almost always requires reaching out to a "native" component such as `<input />` and accessing its underlying DOM node via `this.refs.myInput.getDOMNode()`. Refs are one of the only practical ways of doing this reliably.

132 +- Performing DOM measurements almost always requires reaching out to a "native" component such as `<input />` and accessing its underlying DOM node via `React.findDOMNode(this.refs.myInput)`. Refs are one of the only practical ways of doing this reliably.

133 - 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).

134

135 ### Cautions:

docs/docs/10.4-test-utils.md

+1 -1

@@ -19,7 +19,7 @@ Simulate an event dispatch on a DOM node with optional `eventData` event data. *

19 Example usage:

21 ```javascript

22 -var node = this.refs.input.getDOMNode();

22 +var node = React.findDOMNode(this.refs.input);

23 React.addons.TestUtils.Simulate.click(node);

24 React.addons.TestUtils.Simulate.change(node, {target: {value: 'Hello, world'}});

25 React.addons.TestUtils.Simulate.keyDown(node, {key: "Enter"});

docs/docs/ref-01-top-level-api.md

@@ -110,6 +110,14 @@ boolean isValidElement(* object)

110 Verifies the object is a ReactElement.

111

112

113 +### React.findDOMNode

114 +

115 +```javascript

116 +DOMElement findDOMNode(ReactComponent component)

117 +```

118 +If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. When `render` returns `null` or `false`, `this.getDOMNode()` returns `null`.

119 +

120 +

121 ### React.DOM

122

123 `React.DOM` provides convenience wrappers around `React.createElement` for DOM components. These should only be used when not using JSX. For example, `React.DOM.div(null, 'Hello World!')`

docs/docs/ref-02-component-api.md

@@ -60,6 +60,10 @@ DOMElement getDOMNode()

61 If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. When `render` returns `null` or `false`, `this.getDOMNode()` returns `null`.

63 +> Note:

64 +>

65 +> getDOMNode is deprecated and has been replaced with [React.findDOMNode()](/react/docs/top-level-api.html#react.finddomnode).

66 +

68 ### isMounted

docs/docs/ref-03-component-specs.md

+2 -10

@@ -21,7 +21,7 @@ The `render()` method is required.

22 When called, it should examine `this.props` and `this.state` and return a single child component. This child component can be either a virtual representation of a native DOM component (such as `<div />` or `React.DOM.div()`) or another composite component that you've defined yourself.

24 -You can also return `null` or `false` to indicate that you don't want anything rendered. Behind the scenes, React renders a `<noscript>` tag to work with our current diffing algorithm. When returning `null` or `false`, `this.getDOMNode()` will return `null`.

24 +You can also return `null` or `false` to indicate that you don't want anything rendered. Behind the scenes, React renders a `<noscript>` tag to work with our current diffing algorithm. When returning `null` or `false`, `React.findDOMNode(this)` will return `null`.

26 The `render()` function should be *pure*, meaning that it does not modify component state, it returns the same result each time it's invoked, and it does not read from or write to the DOM or otherwise interact with the browser (e.g., by using `setTimeout`). If you need to interact with the browser, perform your work in `componentDidMount()` or the other lifecycle methods instead. Keeping `render()` pure makes server rendering more practical and makes components easier to think about.

@@ -118,14 +118,10 @@ Invoked once, both on the client and server, immediately before the initial rend

118 componentDidMount()

119 ```

120

121 -Invoked once, only on the client (not on the server), immediately after the initial rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via `this.getDOMNode()`.

121 +Invoked once, only on the client (not on the server), immediately after the initial rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via `React.findDOMNode(this)`.

122

123 If you want to integrate with other JavaScript frameworks, set timers using `setTimeout` or `setInterval`, or send AJAX requests, perform those operations in this method.

124

125 -> Note:

126 ->

127 -> Prior to v0.9, the DOM node was passed in as the last argument. If you were using this, you can still access the DOM node by calling `this.getDOMNode()`.

128 -

125

126 ### Updating: componentWillReceiveProps

127

@@ -199,10 +195,6 @@ Invoked immediately after the component's updates are flushed to the DOM. This m

195

196 Use this as an opportunity to operate on the DOM when the component has been updated.

197

202 -> Note:

203 ->

204 -> Prior to v0.9, the DOM node was passed in as the last argument. If you were using this, you can still access the DOM node by calling `this.getDOMNode()`.

205 -

198

199 ### Unmounting: componentWillUnmount

200

docs/docs/tutorial.md

+11 -9

@@ -487,14 +487,15 @@ Let's make the form interactive. When the user submits the form, we should clear

487 var CommentForm = React.createClass({

488 handleSubmit: function(e) {

489 e.preventDefault();

490 - var author = this.refs.author.getDOMNode().value.trim();

491 - var text = this.refs.text.getDOMNode().value.trim();

490 + var author = React.findDOMNode(this.refs.author).value.trim();

491 + var text = React.findDOMNode(this.refs.text).value.trim();

492 if (!text || !author) {

493 return;

494 }

495 // TODO: send request to the server

496 - this.refs.author.getDOMNode().value = '';

497 - this.refs.text.getDOMNode().value = '';

496 + React.findDOMNode(this.refs.author).value = '';

497 + React.findDOMNode(this.refs.text).value = '';

498 + return;

499 },

500 render: function() {

501 return (

@@ -516,7 +517,7 @@ Call `preventDefault()` on the event to prevent the browser's default action of

517

518 ##### Refs

519

519 -We use the `ref` attribute to assign a name to a child component and `this.refs` to reference the component. We can call `getDOMNode()` on a component to get the native browser DOM element.

520 +We use the `ref` attribute to assign a name to a child component and `this.refs` to reference the component. We can call `React.findDOMNode(component)` on a component to get the native browser DOM element.

521

522 ##### Callbacks as props

523

@@ -568,14 +569,15 @@ Let's call the callback from the `CommentForm` when the user submits the form:

569 var CommentForm = React.createClass({

570 handleSubmit: function(e) {

571 e.preventDefault();

571 - var author = this.refs.author.getDOMNode().value.trim();

572 - var text = this.refs.text.getDOMNode().value.trim();

572 + var author = React.findDOMNode(this.refs.author).value.trim();

573 + var text = React.findDOMNode(this.refs.text).value.trim();

574 if (!text || !author) {

575 return;

576 }

577 this.props.onCommentSubmit({author: author, text: text});

577 - this.refs.author.getDOMNode().value = '';

578 - this.refs.text.getDOMNode().value = '';

578 + React.findDOMNode(this.refs.author).value = '';

579 + React.findDOMNode(this.refs.text).value = '';

580 + return;

581 },

582 render: function() {

583 return (