@samitouri / QOS-React-2 / commits / dd3167edc9

Reorder reference pages

This order should make more sense; it moves important functions like React.renderComponent up and deprecated/discouraged ones like transferPropsTo and setProps down. No content changes.

Ben Alpert committed Jul 15, 2014 at 23:03 UTC dd3167edc9ade7a6fe8f32d9be20ff39c9d00473
2 files changed +96 -96
docs/docs/ref-01-top-level-api.md
+48 -48
@@ -11,54 +11,6 @@ next: component-api.html
11 `React` is the entry point to the React framework. If you're using one of the prebuilt packages it's available as a global; if you're using CommonJS modules you can `require()` it.
12
13
14 -### React.Children
15 -
16 -`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.
17 -
18 -#### React.Children.map
19 -
20 -```javascript
21 -object React.Children.map(object children, function fn [, object context])
22 -```
23 -
24 -Invoke `fn` on every immediate child contained within `children` with `this` set to `context`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.
25 -
26 -#### React.Children.forEach
27 -
28 -```javascript
29 -React.Children.forEach(object children, function fn [, object context])
30 -```
31 -
32 -Like `React.Children.map()` but does not return an object.
33 -
34 -#### React.Children.only
35 -
36 -```javascript
37 -object React.Children.only(object children)
38 -```
39 -
40 -Return the only child in `children`. Throws otherwise.
41 -
42 -
43 -### React.DOM
44 -
45 -`React.DOM` provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the `/** @jsx React.DOM */` docblock.
46 -
47 -
48 -### React.PropTypes
49 -
50 -`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).
51 -
52 -
53 -### React.initializeTouchEvents
54 -
55 -```javascript
56 -initializeTouchEvents(boolean shouldUseTouch)
57 -```
58 -
59 -Configure React's event system to handle touch events on mobile devices.
60 -
61 -
14 ### React.createClass
15
16 ```javascript
@@ -124,3 +76,51 @@ string renderComponentToStaticMarkup(ReactComponent component)
76 ```
77
78 Similar to `renderComponentToString`, except this doesn't create extra DOM attributes such as `data-react-id`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes.
79 +
80 +
81 +### React.DOM
82 +
83 +`React.DOM` provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the `/** @jsx React.DOM */` docblock.
84 +
85 +
86 +### React.PropTypes
87 +
88 +`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).
89 +
90 +
91 +### React.initializeTouchEvents
92 +
93 +```javascript
94 +initializeTouchEvents(boolean shouldUseTouch)
95 +```
96 +
97 +Configure React's event system to handle touch events on mobile devices.
98 +
99 +
100 +### React.Children
101 +
102 +`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.
103 +
104 +#### React.Children.map
105 +
106 +```javascript
107 +object React.Children.map(object children, function fn [, object context])
108 +```
109 +
110 +Invoke `fn` on every immediate child contained within `children` with `this` set to `context`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.
111 +
112 +#### React.Children.forEach
113 +
114 +```javascript
115 +React.Children.forEach(object children, function fn [, object context])
116 +```
117 +
118 +Like `React.Children.map()` but does not return an object.
119 +
120 +#### React.Children.only
121 +
122 +```javascript
123 +object React.Children.only(object children)
124 +```
125 +
126 +Return the only child in `children`. Throws otherwise.
docs/docs/ref-02-component-api.md
+48 -48
@@ -12,39 +12,61 @@ next: component-specs.html
12 Component classes created by `React.createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming these component objects.
13
14
15 -### getDOMNode
15 +### setState
16
17 ```javascript
18 -DOMElement getDOMNode()
18 +setState(object nextState[, function callback])
19 ```
20
21 -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`.
21 +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.
22 +
23 +> Notes:
24 +>
25 +> *NEVER* mutate `this.state` directly, as calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
26 +>
27 +> `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value.
28 +>
29 +> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.
30
31
24 -### setProps
32 +### replaceState
33
34 ```javascript
27 -setProps(object nextProps[, function callback])
35 +replaceState(object nextState[, function callback])
36 ```
37
30 -When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`.
38 +Like `setState()` but deletes any pre-existing state keys that are not in nextState.
39
32 -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.
40
34 -> Note:
35 ->
36 -> When possible, the declarative approach of calling `React.renderComponent()` again is preferred; it tends to make updates easier to reason about. (There's no significant performance difference between the two approaches.)
37 ->
38 -> This method can only be called on a root-level component. That is, it's only available on the component passed directly to `React.renderComponent()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`.
41 +### forceUpdate()
42 +
43 +```javascript
44 +forceUpdate([function callback])
45 +```
46
47 +If your `render()` method reads from something other than `this.props` or `this.state`, you'll need to tell React when it needs to re-run `render()` by calling `forceUpdate()`. You'll also need to call `forceUpdate()` if you mutate `this.state` directly.
48
41 -### replaceProps
49 +Calling `forceUpdate()` will cause `render()` to be called on the component and its children, but React will still only update the DOM if the markup changes.
50 +
51 +Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient.
52 +
53 +
54 +### getDOMNode
55
56 ```javascript
44 -replaceProps(object nextProps[, function callback])
57 +DOMElement getDOMNode()
58 ```
59
47 -Like `setProps()` but deletes any pre-existing props instead of merging the two objects.
60 +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`.
61 +
62 +
63 +### isMounted()
64 +
65 +```javascript
66 +bool isMounted()
67 +```
68 +
69 +`isMounted()` returns true if the component is rendered into the DOM, false otherwise. You can use this method to guard asynchronous calls to `setState()` or `forceUpdate()`.
70
71
72 ### transferPropsTo
@@ -74,49 +96,27 @@ Properties that are specified directly on the target component instance (such as
96 > Use `transferPropsTo` with caution; it encourages tight coupling and makes it easy to accidentally introduce implicit dependencies between components. When in doubt, it's safer to explicitly copy the properties that you need onto the child component.
97
98
77 -### setState
99 +### setProps
100
101 ```javascript
80 -setState(object nextState[, function callback])
102 +setProps(object nextProps[, function callback])
103 ```
104
83 -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.
105 +When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`.
106
85 -> Notes:
86 ->
87 -> *NEVER* mutate `this.state` directly, as calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
107 +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.
108 +
109 +> Note:
110 >
89 -> `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value.
111 +> When possible, the declarative approach of calling `React.renderComponent()` again is preferred; it tends to make updates easier to reason about. (There's no significant performance difference between the two approaches.)
112 >
91 -> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.
92 -
93 -
94 -### replaceState
95 -
96 -```javascript
97 -replaceState(object nextState[, function callback])
98 -```
99 -
100 -Like `setState()` but deletes any pre-existing state keys that are not in nextState.
101 -
102 -
103 -### forceUpdate()
104 -
105 -```javascript
106 -forceUpdate([function callback])
107 -```
108 -
109 -If your `render()` method reads from something other than `this.props` or `this.state`, you'll need to tell React when it needs to re-run `render()` by calling `forceUpdate()`. You'll also need to call `forceUpdate()` if you mutate `this.state` directly.
110 -
111 -Calling `forceUpdate()` will cause `render()` to be called on the component and its children, but React will still only update the DOM if the markup changes.
112 -
113 -Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient.
113 +> This method can only be called on a root-level component. That is, it's only available on the component passed directly to `React.renderComponent()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`.
114
115
116 -### isMounted()
116 +### replaceProps
117
118 ```javascript
119 -bool isMounted()
119 +replaceProps(object nextProps[, function callback])
120 ```
121
122 -`isMounted()` returns true if the component is rendered into the DOM, false otherwise. You can use this method to guard asynchronous calls to `setState()` or `forceUpdate()`.
122 +Like `setProps()` but deletes any pre-existing props instead of merging the two objects.