From 4088f2449b1d72581087b60c3eb206ab35e59918 Mon Sep 17 00:00:00 2001 From: Ben Alpert Date: Tue, 15 Jul 2014 23:03:37 -0700 Subject: [PATCH] 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. --- docs/ref-01-top-level-api.md | 96 +++++++++++++-------------- docs/ref-02-component-api.md | 124 +++++++++++++++++------------------ 2 files changed, 110 insertions(+), 110 deletions(-) diff --git a/docs/ref-01-top-level-api.md b/docs/ref-01-top-level-api.md index 53e7399c4..055003967 100644 --- a/docs/ref-01-top-level-api.md +++ b/docs/ref-01-top-level-api.md @@ -11,54 +11,6 @@ next: component-api.html `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. -### React.Children - -`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure. - -#### React.Children.map - -```javascript -object React.Children.map(object children, function fn [, object context]) -``` - -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. - -#### React.Children.forEach - -```javascript -React.Children.forEach(object children, function fn [, object context]) -``` - -Like `React.Children.map()` but does not return an object. - -#### React.Children.only - -```javascript -object React.Children.only(object children) -``` - -Return the only child in `children`. Throws otherwise. - - -### React.DOM - -`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. - - -### React.PropTypes - -`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). - - -### React.initializeTouchEvents - -```javascript -initializeTouchEvents(boolean shouldUseTouch) -``` - -Configure React's event system to handle touch events on mobile devices. - - ### React.createClass ```javascript @@ -124,3 +76,51 @@ string renderComponentToStaticMarkup(ReactComponent component) ``` 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. + + +### React.DOM + +`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. + + +### React.PropTypes + +`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). + + +### React.initializeTouchEvents + +```javascript +initializeTouchEvents(boolean shouldUseTouch) +``` + +Configure React's event system to handle touch events on mobile devices. + + +### React.Children + +`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure. + +#### React.Children.map + +```javascript +object React.Children.map(object children, function fn [, object context]) +``` + +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. + +#### React.Children.forEach + +```javascript +React.Children.forEach(object children, function fn [, object context]) +``` + +Like `React.Children.map()` but does not return an object. + +#### React.Children.only + +```javascript +object React.Children.only(object children) +``` + +Return the only child in `children`. Throws otherwise. diff --git a/docs/ref-02-component-api.md b/docs/ref-02-component-api.md index ce64972ad..0fa8ac1cd 100644 --- a/docs/ref-02-component-api.md +++ b/docs/ref-02-component-api.md @@ -12,68 +12,6 @@ next: component-specs.html 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. -### getDOMNode - -```javascript -DOMElement getDOMNode() -``` - -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`. - - -### setProps - -```javascript -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 and the component is re-rendered. - -> Note: -> -> 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.) -> -> 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()`. - - -### replaceProps - -```javascript -replaceProps(object nextProps[, function callback]) -``` - -Like `setProps()` but deletes any pre-existing props instead of merging the two objects. - - -### transferPropsTo - -```javascript -ReactComponent transferPropsTo(ReactComponent targetComponent) -``` - -Transfer properties from this component to a target component that have not already been set on the target component. After the props are updated, `targetComponent` is returned as a convenience. This function is useful when creating simple HTML-like components: - -```javascript -var Avatar = React.createClass({ - render: function() { - return this.transferPropsTo( - - ); - } -}); - -// -``` - -Properties that are specified directly on the target component instance (such as `src` and `userId` in the above example) will not be overwritten by `transferPropsTo`. - -> Note: -> -> 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. - - ### setState ```javascript @@ -113,6 +51,15 @@ Calling `forceUpdate()` will cause `render()` to be called on the component and 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. +### getDOMNode + +```javascript +DOMElement getDOMNode() +``` + +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`. + + ### isMounted() ```javascript @@ -120,3 +67,56 @@ bool isMounted() ``` `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()`. + + +### transferPropsTo + +```javascript +ReactComponent transferPropsTo(ReactComponent targetComponent) +``` + +Transfer properties from this component to a target component that have not already been set on the target component. After the props are updated, `targetComponent` is returned as a convenience. This function is useful when creating simple HTML-like components: + +```javascript +var Avatar = React.createClass({ + render: function() { + return this.transferPropsTo( + + ); + } +}); + +// +``` + +Properties that are specified directly on the target component instance (such as `src` and `userId` in the above example) will not be overwritten by `transferPropsTo`. + +> Note: +> +> 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. + + +### setProps + +```javascript +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 and the component is re-rendered. + +> Note: +> +> 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.) +> +> 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()`. + + +### replaceProps + +```javascript +replaceProps(object nextProps[, function callback]) +``` + +Like `setProps()` but deletes any pre-existing props instead of merging the two objects.