Skip to content

Commit

Permalink
Update docs to align with 0.12 better
Browse files Browse the repository at this point in the history
- Rename React.renderComponent -> React.render
- Remove most references to transferPropsTo
  • Loading branch information
sophiebits committed Oct 22, 2014
1 parent 85a98d4 commit 52494f9
Show file tree
Hide file tree
Showing 27 changed files with 67 additions and 68 deletions.
2 changes: 1 addition & 1 deletion docs/docs/02-displaying-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ var HelloWorld = React.createClass({
});

setInterval(function() {
React.renderComponent(
React.render(
<HelloWorld date={new Date()} />,
document.getElementById('example')
);
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/02-displaying-data.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ var HelloWorld = React.createClass({
});

setInterval(function() {
React.renderComponent(
React.render(
<HelloWorld date={new Date()} />,
document.getElementById('example')
);
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/03-interactivity-and-dynamic-uis.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ var LikeButton = React.createClass({
}
});

React.renderComponent(
React.render(
<LikeButton />,
document.getElementById('example')
);
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/04-multiple-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ var ProfileLink = React.createClass({
}
});

React.renderComponent(
React.render(
<Avatar username="pwh" />,
document.getElementById('example')
);
Expand Down
13 changes: 6 additions & 7 deletions docs/docs/05-reusable-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down Expand Up @@ -180,7 +179,7 @@ var TickTock = React.createClass({
}
});

React.renderComponent(
React.render(
<TickTock />,
document.getElementById('example')
);
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/07-working-with-the-browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ var MyComponent = React.createClass({
}
});

React.renderComponent(
React.render(
<MyComponent />,
document.getElementById('example')
);
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/09.5-clone-with-props.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 3 additions & 3 deletions docs/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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')
);
Expand All @@ -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')
);
Expand Down Expand Up @@ -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')
);
Expand Down
6 changes: 3 additions & 3 deletions docs/docs/getting-started.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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')
);
Expand All @@ -49,7 +49,7 @@ next: tutorial.html
你的 React JSX 代码文件可以写在另外的文件里。新建下面的 `src/helloworld.js`

```javascript
React.renderComponent(
React.render(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
Expand Down Expand Up @@ -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')
);
Expand Down
18 changes: 9 additions & 9 deletions docs/docs/ref-01-top-level-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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.

Expand All @@ -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

Expand Down
10 changes: 5 additions & 5 deletions docs/docs/ref-02-component-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/thinking-in-react.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
14 changes: 7 additions & 7 deletions docs/docs/tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ var CommentBox = React.createClass({
);
}
});
React.renderComponent(
React.render(
<CommentBox />,
document.getElementById('content')
);
Expand All @@ -96,7 +96,7 @@ var CommentBox = React.createClass({displayName: 'CommentBox',
);
}
});
React.renderComponent(
React.render(
CommentBox(null),
document.getElementById('content')
);
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -294,7 +294,7 @@ var CommentBox = React.createClass({
}
});
React.renderComponent(
React.render(
<CommentBox data={data} />,
document.getElementById('content')
);
Expand Down Expand Up @@ -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')
);
Expand Down Expand Up @@ -446,7 +446,7 @@ var CommentBox = React.createClass({
}
});
React.renderComponent(
React.render(
<CommentBox url="comments.json" pollInterval={2000} />,
document.getElementById('content')
);
Expand Down
2 changes: 1 addition & 1 deletion docs/downloads.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/tips/02-inline-styles.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 3 additions & 3 deletions docs/tips/03-if-else-in-JSX.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/tips/06-style-props-value-px.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/tips/07-children-props-type.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ var GenericWrapper = React.createClass({
}
});

React.renderComponent(
React.render(
<GenericWrapper><span/><span/><span/></GenericWrapper>,
mountNode
);
Expand All @@ -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 changes: 2 additions & 2 deletions docs/tips/08-controlled-input-null-value.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
```
Loading

0 comments on commit 52494f9

Please sign in to comment.