Browse Source

Update docs to align with 0.12 better

- Rename React.renderComponent -> React.render
- Remove most references to transferPropsTo
main
Ben Alpert 10 years ago
parent
commit
fb46ad0356
  1. 2
      docs/02-displaying-data.md
  2. 2
      docs/02-displaying-data.zh-CN.md
  3. 2
      docs/03-interactivity-and-dynamic-uis.md
  4. 2
      docs/04-multiple-components.md
  5. 13
      docs/05-reusable-components.md
  6. 2
      docs/07-working-with-the-browser.md
  7. 8
      docs/09.5-clone-with-props.md
  8. 6
      docs/getting-started.md
  9. 6
      docs/getting-started.zh-CN.md
  10. 18
      docs/ref-01-top-level-api.md
  11. 10
      docs/ref-02-component-api.md
  12. 2
      docs/thinking-in-react.md
  13. 14
      docs/tutorial.md
  14. 2
      downloads.md
  15. 2
      tips/02-inline-styles.md
  16. 6
      tips/03-if-else-in-JSX.md
  17. 2
      tips/06-style-props-value-px.md
  18. 4
      tips/07-children-props-type.md
  19. 4
      tips/08-controlled-input-null-value.md
  20. 6
      tips/10-props-in-getInitialState-as-anti-pattern.md
  21. 2
      tips/11-dom-event-listeners.md
  22. 2
      tips/12-initial-ajax.md
  23. 6
      tips/13-false-in-jsx.md
  24. 2
      tips/14-communicate-between-components.md
  25. 2
      tips/15-expose-component-functions.md
  26. 6
      tips/16-references-to-components.md
  27. 2
      tips/17-children-undefined.md

2
docs/02-displaying-data.md

@ -47,7 +47,7 @@ var HelloWorld = React.createClass({
});
setInterval(function() {
React.renderComponent(
React.render(
<HelloWorld date={new Date()} />,
document.getElementById('example')
);

2
docs/02-displaying-data.zh-CN.md

@ -47,7 +47,7 @@ var HelloWorld = React.createClass({
});
setInterval(function() {
React.renderComponent(
React.render(
<HelloWorld date={new Date()} />,
document.getElementById('example')
);

2
docs/03-interactivity-and-dynamic-uis.md

@ -29,7 +29,7 @@ var LikeButton = React.createClass({
}
});
React.renderComponent(
React.render(
<LikeButton />,
document.getElementById('example')
);

2
docs/04-multiple-components.md

@ -48,7 +48,7 @@ var ProfileLink = React.createClass({
}
});
React.renderComponent(
React.render(
<Avatar username="pwh" />,
document.getElementById('example')
);

13
docs/05-reusable-components.md

@ -100,19 +100,18 @@ The result of `getDefaultProps()` will be cached and used to ensure that `this.p
## Transferring Props: A Shortcut
A common type of React component is one that extends a basic HTML in a simple way. Often you'll want to copy any HTML attributes passed to your component to the underlying HTML element to save typing. React provides `transferPropsTo()` to do just this.
A common type of React component is one that extends a basic HTML in a simple way. Often you'll want to copy any HTML attributes passed to your component to the underlying HTML element to save typing. You can use the JSX _spread_ syntax to achieve this:
```javascript
var CheckLink = React.createClass({
render: function() {
// transferPropsTo() will take any props passed to CheckLink
// and copy them to <a>
return this.transferPropsTo(<a>{'√ '}{this.props.children}</a>);
// This takes any props passed to CheckLink and copies them to <a>
return <a {...this.props}>{'√ '}{this.props.children}</a>;
}
});
React.renderComponent(
<CheckLink href="javascript:alert('Hello, world!');">
React.render(
<CheckLink href="/checked.html">
Click here!
</CheckLink>,
document.getElementById('example')
@ -180,7 +179,7 @@ var TickTock = React.createClass({
}
});
React.renderComponent(
React.render(
<TickTock />,
document.getElementById('example')
);

2
docs/07-working-with-the-browser.md

@ -50,7 +50,7 @@ var MyComponent = React.createClass({
}
});
React.renderComponent(
React.render(
<MyComponent />,
document.getElementById('example')
);

8
docs/09.5-clone-with-props.md

@ -10,12 +10,12 @@ In rare situations a component may want to change the props of a component that
#### `ReactComponent React.addons.cloneWithProps(ReactComponent component, object? extraProps)`
Do a shallow copy of `component` and merge any props provided by `extraProps`. Props are merged in the same manner as [`transferPropsTo()`](/react/docs/component-api.html#transferpropsto), so props like `className` will be merged intelligently.
Do a shallow copy of `component` and merge any props provided by `extraProps`. The `className` and `style` props will be merged intelligently.
> Note:
>
> `cloneWithProps` does not transfer the `key` prop to the cloned component. If you wish to preserve the key, add it to the `extraProps` object:
> `cloneWithProps` does not transfer `key` to the cloned component. If you wish to preserve the key, add it to the `extraProps` object:
> ```js
> var clonedComponent = cloneWithProps(originalComponent, { key : originalComponent.props.key });
> var clonedComponent = cloneWithProps(originalComponent, { key : originalComponent.key });
> ```
> `ref` is another prop that is not preserved either.
> `ref` is similarly not preserved.

6
docs/getting-started.md

@ -34,7 +34,7 @@ In the root directory of the starter kit, create a `helloworld.html` with the fo
<body>
<div id="example"></div>
<script type="text/jsx">
React.renderComponent(
React.render(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
@ -50,7 +50,7 @@ The XML syntax inside of JavaScript is called JSX; check out the [JSX syntax](/r
Your React JSX code can live in a separate file. Create the following `src/helloworld.js`.
```javascript
React.renderComponent(
React.render(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
@ -80,7 +80,7 @@ jsx --watch src/ build/
The file `build/helloworld.js` is autogenerated whenever you make a change.
```javascript{2}
React.renderComponent(
React.render(
React.DOM.h1(null, 'Hello, world!'),
document.getElementById('example')
);

6
docs/getting-started.zh-CN.md

@ -33,7 +33,7 @@ next: tutorial.html
<body>
<div id="example"></div>
<script type="text/jsx">
React.renderComponent(
React.render(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
@ -49,7 +49,7 @@ next: tutorial.html
你的 React JSX 代码文件可以写在另外的文件里。新建下面的 `src/helloworld.js`
```javascript
React.renderComponent(
React.render(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
@ -79,7 +79,7 @@ jsx --watch src/ build/
只要你修改了, `build/helloworld.js` 文件会自动生成。
```javascript{2}
React.renderComponent(
React.render(
React.DOM.h1(null, 'Hello, world!'),
document.getElementById('example')
);

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

@ -22,10 +22,10 @@ Create a component given a specification. A component implements a `render` meth
For more information about the specification object, see [Component Specs and Lifecycle](/react/docs/component-specs.html).
### React.renderComponent
### React.render
```javascript
ReactComponent renderComponent(
ReactComponent render(
ReactComponent component,
DOMElement container,
[function callback]
@ -40,7 +40,7 @@ If the optional callback is provided, it will be executed after the component is
> Note:
>
> `React.renderComponent()` replaces the contents of the container node you
> `React.render()` replaces the contents of the container node you
> pass in. In the future, it may be possible to insert a component to an
> existing DOM node without overwriting the existing children.
@ -54,24 +54,24 @@ boolean unmountComponentAtNode(DOMElement container)
Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount.
### React.renderComponentToString
### React.renderToString
```javascript
string renderComponentToString(ReactComponent component)
string renderToString(ReactComponent component)
```
Render a component to its initial HTML. This should only be used on the server. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes.
If you call `React.renderComponent()` on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.
If you call `React.render()` on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.
### React.renderComponentToStaticMarkup
### React.renderToStaticMarkup
```javascript
string renderComponentToStaticMarkup(ReactComponent component)
string renderToStaticMarkup(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.
Similar to `renderToString`, 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.isValidClass

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

@ -8,7 +8,7 @@ next: component-specs.html
## ReactComponent
Instances of a React Component are created internally in React when rendering. These instances are reused in subsequent renders, and can be accessed in your component methods as `this`. The only way to get a handle to a React Component instance outside of React is by storing the return value of `React.renderComponent`. Inside other Components, you may use [refs](/react/docs/more-about-refs.html) to achieve the same result.
Instances of a React Component are created internally in React when rendering. These instances are reused in subsequent renders, and can be accessed in your component methods as `this`. The only way to get a handle to a React Component instance outside of React is by storing the return value of `React.render`. Inside other Components, you may use [refs](/react/docs/more-about-refs.html) to achieve the same result.
### setState
@ -103,15 +103,15 @@ Properties that are specified directly on the target component instance (such as
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()`.
When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.render()`.
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.
Though calling `React.render()` 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.)
> When possible, the declarative approach of calling `React.render()` 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()`.
> This method can only be called on a root-level component. That is, it's only available on the component passed directly to `React.render()` 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

2
docs/thinking-in-react.md

@ -68,7 +68,7 @@ To build a static version of your app that renders your data model you'll want t
You can build top-down or bottom-up. That is, you can either start with building the components higher up in the hierarchy (i.e. starting with `FilterableProductTable`) or with the ones lower in it (`ProductRow`). In simpler examples it's usually easier to go top-down and on larger projects it's easier to go bottom-up and write tests as you build.
At the end of this step you'll have a library of reusable components that render your data model. The components will only have `render()` methods since this is a static version of your app. The component at the top of the hierarchy (`FilterableProductTable`) will take your data model as a prop. If you make a change to your underlying data model and call `renderComponent()` again the UI will be updated. It's easy to see how your UI is updated and where to make changes since there's nothing complicated going on since React's **one-way data flow** (also called *one-way binding*) keeps everything modular, easy to reason about, and fast.
At the end of this step you'll have a library of reusable components that render your data model. The components will only have `render()` methods since this is a static version of your app. The component at the top of the hierarchy (`FilterableProductTable`) will take your data model as a prop. If you make a change to your underlying data model and call `React.render()` again the UI will be updated. It's easy to see how your UI is updated and where to make changes since there's nothing complicated going on since React's **one-way data flow** (also called *one-way binding*) keeps everything modular, easy to reason about, and fast.
Simply refer to the [React docs](http://facebook.github.io/react/docs/) if you need help executing this step.

14
docs/tutorial.md

@ -75,7 +75,7 @@ var CommentBox = React.createClass({
);
}
});
React.renderComponent(
React.render(
<CommentBox />,
document.getElementById('content')
);
@ -96,7 +96,7 @@ var CommentBox = React.createClass({displayName: 'CommentBox',
);
}
});
React.renderComponent(
React.render(
CommentBox(null),
document.getElementById('content')
);
@ -112,7 +112,7 @@ The `<div>` tags are not actual DOM nodes; they are instantiations of React `div
You do not have to return basic HTML. You can return a tree of components that you (or someone else) built. This is what makes React **composable**: a key tenet of maintainable frontends.
`React.renderComponent()` instantiates the root component, starts the framework, and injects the markup into a raw DOM element, provided as the second argument.
`React.render()` instantiates the root component, starts the framework, and injects the markup into a raw DOM element, provided as the second argument.
## Composing components
@ -278,7 +278,7 @@ var data = [
];
```
We need to get this data into `CommentList` in a modular way. Modify `CommentBox` and the `renderComponent()` call to pass this data into the `CommentList` via props:
We need to get this data into `CommentList` in a modular way. Modify `CommentBox` and the `React.render()` call to pass this data into the `CommentList` via props:
```javascript{7,15}
// tutorial9.js
@ -294,7 +294,7 @@ var CommentBox = React.createClass({
}
});
React.renderComponent(
React.render(
<CommentBox data={data} />,
document.getElementById('content')
);
@ -330,7 +330,7 @@ Let's replace the hard-coded data with some dynamic data from the server. We wil
```javascript{3}
// tutorial11.js
React.renderComponent(
React.render(
<CommentBox url="comments.json" />,
document.getElementById('content')
);
@ -446,7 +446,7 @@ var CommentBox = React.createClass({
}
});
React.renderComponent(
React.render(
<CommentBox url="comments.json" pollInterval={2000} />,
document.getElementById('content')
);

2
downloads.md

@ -71,7 +71,7 @@ If you're using an npm-compatible packaging system like browserify or webpack, y
```js
var React = require('react');
React.renderComponent(...);
React.render(...);
```
If you'd like to use any [add-ons](/react/docs/addons.html), use `var React = require('react/addons');` instead.

2
tips/02-inline-styles.md

@ -17,7 +17,7 @@ var divStyle = {
msTransition: 'all' // 'ms' is the only lowercase vendor prefix
};
React.renderComponent(<div style={divStyle}>Hello World!</div>, mountNode);
React.render(<div style={divStyle}>Hello World!</div>, mountNode);
```
Style keys are camelCased in order to be consistent with accessing the properties on DOM nodes from JS (e.g. `node.style.backgroundImage`). Vendor prefixes [other than `ms`](http://www.andismith.com/blog/2012/02/modernizr-prefixed/) should begin with a capital letter. This is why `WebkitTransition` has an uppercase "W".

6
tips/03-if-else-in-JSX.md

@ -11,10 +11,10 @@ next: self-closing-tag.html
```js
// This JSX:
React.renderComponent(<div id="msg">Hello World!</div>, mountNode);
React.render(<div id="msg">Hello World!</div>, mountNode);
// Is transformed to this JS:
React.renderComponent(React.DOM.div({id:"msg"}, "Hello World!"), mountNode);
React.render(React.DOM.div({id:"msg"}, "Hello World!"), mountNode);
```
This means that `if` statements don't fit in. Take this example:
@ -30,7 +30,7 @@ React.DOM.div({id: if (condition) { 'msg' }}, "Hello World!");
That's not valid JS. You probably want to make use of a ternary expression:
```js
React.renderComponent(<div id={condition ? 'msg' : ''}>Hello World!</div>, mountNode);
React.render(<div id={condition ? 'msg' : ''}>Hello World!</div>, mountNode);
```
If a ternary expression isn't robust enough, you can use `if` statements to determine which

2
tips/06-style-props-value-px.md

@ -11,7 +11,7 @@ When specifying a pixel value for your inline `style` prop, React automatically
```js
var divStyle = {height: 10}; // rendered as "height:10px"
React.renderComponent(<div style={divStyle}>Hello World!</div>, mountNode);
React.render(<div style={divStyle}>Hello World!</div>, mountNode);
```
See [Inline Styles](/react/tips/inline-styles.html) for more info.

4
tips/07-children-props-type.md

@ -20,7 +20,7 @@ var GenericWrapper = React.createClass({
}
});
React.renderComponent(
React.render(
<GenericWrapper><span/><span/><span/></GenericWrapper>,
mountNode
);
@ -43,7 +43,7 @@ var GenericWrapper = React.createClass({
}
});
React.renderComponent(<GenericWrapper>hello</GenericWrapper>, mountNode);
React.render(<GenericWrapper>hello</GenericWrapper>, mountNode);
```
To make `this.props.children` easy to deal with, we've provided the [React.Children utilities](/react/docs/top-level-api.html#react.children).

4
tips/08-controlled-input-null-value.md

@ -14,9 +14,9 @@ You might have run into a problem where `value` is specified, but the input can
The snippet below shows this phenomenon; after a second, the text becomes editable.
```js
React.renderComponent(<input value="hi" />, mountNode);
React.render(<input value="hi" />, mountNode);
setTimeout(function() {
React.renderComponent(<input value={null} />, mountNode);
React.render(<input value={null} />, mountNode);
}, 1000);
```

6
tips/10-props-in-getInitialState-as-anti-pattern.md

@ -26,7 +26,7 @@ var MessageBox = React.createClass({
}
});
React.renderComponent(<MessageBox name="Rogers"/>, mountNode);
React.render(<MessageBox name="Rogers"/>, mountNode);
```
Better:
@ -38,7 +38,7 @@ var MessageBox = React.createClass({
}
});
React.renderComponent(<MessageBox name="Rogers"/>, mountNode);
React.render(<MessageBox name="Rogers"/>, mountNode);
```
(For more complex logic, simply isolate the computation in a method.)
@ -62,5 +62,5 @@ var Counter = React.createClass({
}
});
React.renderComponent(<Counter initialCount={7}/>, mountNode);
React.render(<Counter initialCount={7}/>, mountNode);
```

2
tips/11-dom-event-listeners.md

@ -36,7 +36,7 @@ var Box = React.createClass({
}
});
React.renderComponent(<Box />, mountNode);
React.render(<Box />, mountNode);
```
`componentDidMount` is called after the component is mounted and has a DOM representation. This is often a place where you would attach generic DOM events.

2
tips/12-initial-ajax.md

@ -44,7 +44,7 @@ var UserGist = React.createClass({
}
});
React.renderComponent(
React.render(
<UserGist source="https://api.github.com/users/octocat/gists" />,
mountNode
);

6
tips/13-false-in-jsx.md

@ -12,19 +12,19 @@ Here's how `false` renders in different contexts:
Renders as `id="false"`:
```js
React.renderComponent(<div id={false} />, mountNode);
React.render(<div id={false} />, mountNode);
```
String `"false"` as input value:
```js
React.renderComponent(<input value={false} />, mountNode);
React.render(<input value={false} />, mountNode);
```
No child:
```js
React.renderComponent(<div>{false}</div>, mountNode);
React.render(<div>{false}</div>, mountNode);
```
The reason why this one doesn't render as the string `"false"` as a `div` child is to allow the more common use-case: `<div>{x > 1 && 'You have more than one item'}</div>`.

2
tips/14-communicate-between-components.md

@ -31,7 +31,7 @@ var GroceryList = React.createClass({
}
});
React.renderComponent(
React.render(
<GroceryList items={['Apple', 'Banana', 'Cranberry']} />, mountNode
);
```

2
tips/15-expose-component-functions.md

@ -53,7 +53,7 @@ var Todos = React.createClass({
}
});
React.renderComponent(<Todos />, mountNode);
React.render(<Todos />, mountNode);
```
Alternatively, you could have achieved this by passing the `todo` an `isLastUnfinishedItem` prop, let it check this prop in `componentDidUpdate`, then animate itself; however, this quickly gets messy if you pass around different props to control animations.

6
tips/16-references-to-components.md

@ -7,10 +7,10 @@ prev: expose-component-functions.html
next: children-undefined.html
---
If you're using React components in a larger non-React application or transitioning your code to React, you may need to keep references to components. `React.renderComponent` returns a reference to the mounted component:
If you're using React components in a larger non-React application or transitioning your code to React, you may need to keep references to components. `React.render` returns a reference to the mounted component:
```js
var myComponent = React.renderComponent(<MyComponent />, myContainer);
var myComponent = React.render(<MyComponent />, myContainer);
```
Keep in mind, however, that the "constructor" of a component doesn't return a component instance! It's just a **descriptor**: a lightweight representation that tells React what the mounted component should look like.
@ -20,7 +20,7 @@ var myComponent = <MyComponent />; // This is just a descriptor.
// Some code here...
myComponent = React.renderComponent(myComponent, myContainer);
myComponent = React.render(myComponent, myContainer);
```
> Note:

2
tips/17-children-undefined.md

@ -21,7 +21,7 @@ var App = React.createClass({
}
});
React.renderComponent(<App></App>, mountNode);
React.render(<App></App>, mountNode);
```
To access your own subcomponents (the `span`s), place [refs](http://facebook.github.io/react/docs/more-about-refs.html) on them.

Loading…
Cancel
Save