Paul O’Shannessy
10 years ago
42 changed files with 872 additions and 280 deletions
@ -1,14 +1,14 @@ |
|||
var HELLO_COMPONENT = "\ |
|||
var HelloMessage = React.createClass({\n\ |
|||
render: function() {\n\ |
|||
return <div>Hello {this.props.name}</div>;\n\ |
|||
}\n\ |
|||
});\n\ |
|||
\n\ |
|||
React.renderComponent(<HelloMessage name=\"John\" />, mountNode);\ |
|||
"; |
|||
var HELLO_COMPONENT = ` |
|||
var HelloMessage = React.createClass({ |
|||
render: function() { |
|||
return <div>Hello {this.props.name}</div>; |
|||
} |
|||
}); |
|||
|
|||
React.renderComponent( |
|||
React.render(<HelloMessage name="John" />, mountNode); |
|||
`;
|
|||
|
|||
React.render( |
|||
<ReactPlayground codeText={HELLO_COMPONENT} />, |
|||
document.getElementById('helloExample') |
|||
); |
|||
|
|||
@ -1,37 +1,37 @@ |
|||
var MARKDOWN_COMPONENT = "\ |
|||
var converter = new Showdown.converter();\n\ |
|||
\n\ |
|||
var MarkdownEditor = React.createClass({\n\ |
|||
getInitialState: function() {\n\ |
|||
return {value: 'Type some *markdown* here!'};\n\ |
|||
},\n\ |
|||
handleChange: function() {\n\ |
|||
this.setState({value: this.refs.textarea.getDOMNode().value});\n\ |
|||
},\n\ |
|||
render: function() {\n\ |
|||
return (\n\ |
|||
<div className=\"MarkdownEditor\">\n\ |
|||
<h3>Input</h3>\n\ |
|||
<textarea\n\ |
|||
onChange={this.handleChange}\n\ |
|||
ref=\"textarea\"\n\ |
|||
defaultValue={this.state.value} />\n\ |
|||
<h3>Output</h3>\n\ |
|||
<div\n\ |
|||
className=\"content\"\n\ |
|||
dangerouslySetInnerHTML={{\n\ |
|||
__html: converter.makeHtml(this.state.value)\n\ |
|||
}}\n\ |
|||
/>\n\ |
|||
</div>\n\ |
|||
);\n\ |
|||
}\n\ |
|||
});\n\ |
|||
\n\ |
|||
React.renderComponent(<MarkdownEditor />, mountNode);\ |
|||
"; |
|||
var MARKDOWN_COMPONENT = ` |
|||
var converter = new Showdown.converter(); |
|||
|
|||
React.renderComponent( |
|||
var MarkdownEditor = React.createClass({ |
|||
getInitialState: function() { |
|||
return {value: 'Type some *markdown* here!'}; |
|||
}, |
|||
handleChange: function() { |
|||
this.setState({value: this.refs.textarea.getDOMNode().value}); |
|||
}, |
|||
render: function() { |
|||
return ( |
|||
<div className="MarkdownEditor"> |
|||
<h3>Input</h3> |
|||
<textarea |
|||
onChange={this.handleChange} |
|||
ref="textarea" |
|||
defaultValue={this.state.value} /> |
|||
<h3>Output</h3> |
|||
<div |
|||
className="content" |
|||
dangerouslySetInnerHTML={{ |
|||
__html: converter.makeHtml(this.state.value) |
|||
}} |
|||
/> |
|||
</div> |
|||
); |
|||
} |
|||
}); |
|||
|
|||
React.render(<MarkdownEditor />, mountNode); |
|||
`;
|
|||
|
|||
React.render( |
|||
<ReactPlayground codeText={MARKDOWN_COMPONENT} />, |
|||
document.getElementById('markdownExample') |
|||
); |
|||
|
|||
@ -1,28 +1,28 @@ |
|||
var TIMER_COMPONENT = "\ |
|||
var Timer = React.createClass({\n\ |
|||
getInitialState: function() {\n\ |
|||
return {secondsElapsed: 0};\n\ |
|||
},\n\ |
|||
tick: function() {\n\ |
|||
this.setState({secondsElapsed: this.state.secondsElapsed + 1});\n\ |
|||
},\n\ |
|||
componentDidMount: function() {\n\ |
|||
this.interval = setInterval(this.tick, 1000);\n\ |
|||
},\n\ |
|||
componentWillUnmount: function() {\n\ |
|||
clearInterval(this.interval);\n\ |
|||
},\n\ |
|||
render: function() {\n\ |
|||
return (\n\ |
|||
<div>Seconds Elapsed: {this.state.secondsElapsed}</div>\n\ |
|||
);\n\ |
|||
}\n\ |
|||
});\n\ |
|||
\n\ |
|||
React.renderComponent(<Timer />, mountNode);\ |
|||
"; |
|||
var TIMER_COMPONENT = ` |
|||
var Timer = React.createClass({ |
|||
getInitialState: function() { |
|||
return {secondsElapsed: 0}; |
|||
}, |
|||
tick: function() { |
|||
this.setState({secondsElapsed: this.state.secondsElapsed + 1}); |
|||
}, |
|||
componentDidMount: function() { |
|||
this.interval = setInterval(this.tick, 1000); |
|||
}, |
|||
componentWillUnmount: function() { |
|||
clearInterval(this.interval); |
|||
}, |
|||
render: function() { |
|||
return ( |
|||
<div>Seconds Elapsed: {this.state.secondsElapsed}</div> |
|||
); |
|||
} |
|||
}); |
|||
|
|||
React.renderComponent( |
|||
React.render(<Timer />, mountNode); |
|||
`;
|
|||
|
|||
React.render( |
|||
<ReactPlayground codeText={TIMER_COMPONENT} />, |
|||
document.getElementById('timerExample') |
|||
); |
|||
|
|||
@ -1,42 +1,43 @@ |
|||
var TODO_COMPONENT = "\ |
|||
var TodoList = React.createClass({\n\ |
|||
render: function() {\n\ |
|||
var createItem = function(itemText) {\n\ |
|||
return <li>{itemText}</li>;\n\ |
|||
};\n\ |
|||
return <ul>{this.props.items.map(createItem)}</ul>;\n\ |
|||
}\n\ |
|||
});\n\ |
|||
var TodoApp = React.createClass({\n\ |
|||
getInitialState: function() {\n\ |
|||
return {items: [], text: ''};\n\ |
|||
},\n\ |
|||
onChange: function(e) {\n\ |
|||
this.setState({text: e.target.value});\n\ |
|||
},\n\ |
|||
handleSubmit: function(e) {\n\ |
|||
e.preventDefault();\n\ |
|||
var nextItems = this.state.items.concat([this.state.text]);\n\ |
|||
var nextText = '';\n\ |
|||
this.setState({items: nextItems, text: nextText});\n\ |
|||
},\n\ |
|||
render: function() {\n\ |
|||
return (\n\ |
|||
<div>\n\ |
|||
<h3>TODO</h3>\n\ |
|||
<TodoList items={this.state.items} />\n\ |
|||
<form onSubmit={this.handleSubmit}>\n\ |
|||
<input onChange={this.onChange} value={this.state.text} />\n\ |
|||
<button>{'Add #' + (this.state.items.length + 1)}</button>\n\ |
|||
</form>\n\ |
|||
</div>\n\ |
|||
);\n\ |
|||
}\n\ |
|||
});\n\ |
|||
React.renderComponent(<TodoApp />, mountNode);\ |
|||
"; |
|||
var TODO_COMPONENT = ` |
|||
var TodoList = React.createClass({ |
|||
render: function() { |
|||
var createItem = function(itemText) { |
|||
return <li>{itemText}</li>; |
|||
}; |
|||
return <ul>{this.props.items.map(createItem)}</ul>; |
|||
} |
|||
}); |
|||
var TodoApp = React.createClass({ |
|||
getInitialState: function() { |
|||
return {items: [], text: ''}; |
|||
}, |
|||
onChange: function(e) { |
|||
this.setState({text: e.target.value}); |
|||
}, |
|||
handleSubmit: function(e) { |
|||
e.preventDefault(); |
|||
var nextItems = this.state.items.concat([this.state.text]); |
|||
var nextText = ''; |
|||
this.setState({items: nextItems, text: nextText}); |
|||
}, |
|||
render: function() { |
|||
return ( |
|||
<div> |
|||
<h3>TODO</h3> |
|||
<TodoList items={this.state.items} /> |
|||
<form onSubmit={this.handleSubmit}> |
|||
<input onChange={this.onChange} value={this.state.text} /> |
|||
<button>{'Add #' + (this.state.items.length + 1)}</button> |
|||
</form> |
|||
</div> |
|||
); |
|||
} |
|||
}); |
|||
|
|||
React.renderComponent( |
|||
React.render(<TodoApp />, mountNode); |
|||
`;
|
|||
|
|||
React.render( |
|||
<ReactPlayground codeText={TODO_COMPONENT} />, |
|||
document.getElementById('todoExample') |
|||
); |
|||
|
|||
@ -0,0 +1,127 @@ |
|||
--- |
|||
title: React v0.12 |
|||
author: Paul O’Shannessy |
|||
--- |
|||
|
|||
We're happy to announce the availability of React v0.12! After over a week of baking as the release candidate, we uncovered and fixed a few small issues. Thanks to all of you who upgraded and gave us feedback! |
|||
|
|||
We have talked a lot about some of the bigger changes in this release. [We introduced new terminology](/react/blog/2014/10/14/introducing-react-elements.html) and changed APIs to clean up and simplify some of the concepts of React. [We also made several changes to JSX](/react/blog/2014/10/16/react-v0.12-rc1.html) and deprecated a few functions. We won't go into depth about these changes again but we encourage you to read up on these changes in the linked posts. We'll summarize these changes and discuss some of the other changes and how they may impact you below. As always, a full changelog is also included below. |
|||
|
|||
|
|||
The release is available for download: |
|||
|
|||
* **React** |
|||
Dev build with warnings: <http://fb.me/react-0.12.0.js> |
|||
Minified build for production: <http://fb.me/react-0.12.0.min.js> |
|||
* **React with Add-Ons** |
|||
Dev build with warnings: <http://fb.me/react-with-addons-0.12.0.js> |
|||
Minified build for production: <http://fb.me/react-with-addons-0.12.0.min.js> |
|||
* **In-Browser JSX transformer** |
|||
<http://fb.me/JSXTransformer-0.12.0.js> |
|||
|
|||
We've also published version `0.12.0` of the `react` and `react-tools` packages on npm and the `react` package on bower. |
|||
|
|||
## New Terminology & Updated APIs |
|||
|
|||
v0.12 is bringing about some new terminology. [We introduced](/react/blog/2014/10/14/introducing-react-elements.html) this 2 weeks ago and we've also documented it in [a new section of the documentation](/react/docs/glossary.html). As a part of this, we also corrected many of our top-level APIs to align with the terminology. `Component` has been removed from all of our `React.render*` methods. While at one point the argument you passed to these functions was called a Component, it no longer is. You are passing ReactElements. To align with `render` methods in your component classes, we decided to keep the top-level functions short and sweet. `React.renderComponent` is now `React.render`. |
|||
|
|||
We also corrected some other misnomers. `React.isValidComponent` actually determines if the argument is a ReactElement, so it has been renamed to `React.isValidElement`. In the same vein, `React.PropTypes.component` is now `React.PropTypes.element` and `React.PropTypes.renderable` is now `React.PropTypes.node`. |
|||
|
|||
The old methods will still work but will warn upon first use. They will be removed in v0.13. |
|||
|
|||
## JSX Changes |
|||
|
|||
[We talked more in depth about these before](/react/blog/2014/10/16/react-v0.12-rc1.html#jsx-changes), so here are the highlights. |
|||
|
|||
* No more `/** @jsx React.DOM */`! |
|||
* We no longer transform to a straight function call. `<Component/>` now becomes `React.createElement(Component)` |
|||
* DOM components don't make use of `React.DOM`, instead we pass the tag name directly. `<div/>` becomes `React.createElement('div')` |
|||
* We introduced spread attributes as a quick way to transfer props. |
|||
|
|||
## DevTools Improvements, No More `__internals` |
|||
|
|||
For months we've gotten complaints about the React DevTools message. It shouldn't have logged the up-sell message when you were already using the DevTools. Unfortunately this was because the way we implemented these tools resulted in the DevTools knowing about React, but not the reverse. We finally gave this some attention and enabled React to know if the DevTools are installed. We released an update to the devtools several weeks ago making this possible. Extensions in Chrome should auto-update so you probably already have the update installed! |
|||
|
|||
As a result of this update, we no longer need to expose several internal modules to the world. If you were taking advantage of this implementation detail, your code will break. `React.__internals` is no more. |
|||
|
|||
## License Change - BSD |
|||
|
|||
We updated the license on React to the BSD 3-Clause license with an explicit patent grant. Previously we used the Apache 2 license. These licenses are very similar and our extra patent grant is equivalent to the grant provided in the Apache license. You can still use React with the confidence that we have granted the use of any patents covering it. This brings us in line with the same licensing we use across the majority of our open source projects at Facebook. |
|||
|
|||
You can read the full text of the [LICENSE](https://github.com/facebook/react/blob/master/LICENSE) and [`PATENTS`](https://github.com/facebook/react/blob/master/PATENTS) files on GitHub. |
|||
|
|||
- - - |
|||
|
|||
## Changelog |
|||
|
|||
### React Core |
|||
|
|||
#### Breaking Changes |
|||
|
|||
* `key` and `ref` moved off props object, now accessible on the element directly |
|||
* React is now BSD licensed with accompanying Patents grant |
|||
* Default prop resolution has moved to Element creation time instead of mount time, making them effectively static |
|||
* `React.__internals` is removed - it was exposed for DevTools which no longer needs access |
|||
* Composite Component functions can no longer be called directly - they must be wrapped with `React.createFactory` first. This is handled for you when using JSX. |
|||
|
|||
#### New Features |
|||
|
|||
* Spread operator (`{...}`) introduced to deprecate `this.transferPropsTo` |
|||
* Added support for more HTML attributes: `acceptCharset`, `classID`, `manifest` |
|||
|
|||
#### Deprecations |
|||
|
|||
* `React.renderComponent` --> `React.render` |
|||
* `React.renderComponentToString` --> `React.renderToString` |
|||
* `React.renderComponentToStaticMarkup` --> `React.renderToStaticMarkup` |
|||
* `React.isValidComponent` --> `React.isValidElement` |
|||
* `React.PropTypes.component` --> `React.PropTypes.element` |
|||
* `React.PropTypes.renderable` --> `React.PropTypes.node` |
|||
* **DEPRECATED** `React.isValidClass` |
|||
* **DEPRECATED** `instance.transferPropsTo` |
|||
* **DEPRECATED** Returning `false` from event handlers to preventDefault |
|||
* **DEPRECATED** Convenience Constructor usage as function, instead wrap with `React.createFactory` |
|||
* **DEPRECATED** use of `key={null}` to assign implicit keys |
|||
|
|||
#### Bug Fixes |
|||
|
|||
* Better handling of events and updates in nested results, fixing value restoration in "layered" controlled components |
|||
* Correctly treat `event.getModifierState` as case sensitive |
|||
* Improved normalization of `event.charCode` |
|||
* Better error stacks when involving autobound methods |
|||
* Removed DevTools message when the DevTools are installed |
|||
* Correctly detect required language features across browsers |
|||
* Fixed support for some HTML attributes: |
|||
* `list` updates correctly now |
|||
* `scrollLeft`, `scrollTop` removed, these should not be specified as props |
|||
* Improved error messages |
|||
|
|||
### React With Addons |
|||
|
|||
#### New Features |
|||
|
|||
* `React.addons.batchedUpdates` added to API for hooking into update cycle |
|||
|
|||
#### Breaking Changes |
|||
|
|||
* `React.addons.update` uses `assign` instead of `copyProperties` which does `hasOwnProperty` checks. Properties on prototypes will no longer be updated correctly. |
|||
|
|||
#### Bug Fixes |
|||
|
|||
* Fixed some issues with CSS Transitions |
|||
|
|||
### JSX |
|||
|
|||
#### Breaking Changes |
|||
|
|||
* Enforced convention: lower case tag names are always treated as HTML tags, upper case tag names are always treated as composite components |
|||
* JSX no longer transforms to simple function calls |
|||
|
|||
#### New Features |
|||
|
|||
* `@jsx React.DOM` no longer required |
|||
* spread (`{...}`) operator introduced to allow easier use of props |
|||
|
|||
#### Bug Fixes |
|||
|
|||
* JSXTransformer: Make sourcemaps an option when using APIs directly (eg, for react-rails) |
|||
@ -0,0 +1,71 @@ |
|||
--- |
|||
id: jsx-spread |
|||
title: JSX Spread Attributes |
|||
permalink: jsx-spread.html |
|||
prev: jsx-in-depth.html |
|||
next: jsx-gotchas.html |
|||
--- |
|||
|
|||
If you know all the properties that you want to place on a component a head of time, it is easy to use JSX: |
|||
|
|||
```javascript |
|||
var component = <Component foo={x} bar={y} />; |
|||
``` |
|||
|
|||
## Mutating Props is Bad, mkay |
|||
|
|||
If you don't know which properties you want to set, you might be tempted to add them onto the object later: |
|||
|
|||
```javascript |
|||
var component = <Component />; |
|||
component.props.foo = x; // bad |
|||
component.props.bar = y; // also bad |
|||
``` |
|||
|
|||
This is an anti-pattern because it means that we can't help you check the right propTypes until way later. This means that your propTypes errors end up with a cryptic stack trace. |
|||
|
|||
The props should be considered immutable at this point. Mutating the props object somewhere else could cause unexpected consequences so ideally it would be a frozen object at this point. |
|||
|
|||
## Spread Attributes |
|||
|
|||
Now you can use a new feature of JSX called spread attributes: |
|||
|
|||
```javascript |
|||
var props = {}; |
|||
props.foo = x; |
|||
props.bar = y; |
|||
var component = <Component {...props} />; |
|||
``` |
|||
|
|||
The properties of the object that you pass in are copied onto the component's props. |
|||
|
|||
You can use this multiple times or combine it with other attributes. The specification order is important. Later attributes override previous ones. |
|||
|
|||
```javascript |
|||
var props = { foo: 'default' }; |
|||
var component = <Component {...props} foo={'override'} />; |
|||
console.log(component.props.foo); // 'override' |
|||
``` |
|||
|
|||
## What's with the weird `...` notation? |
|||
|
|||
The `...` operator (or spread operator) is already supported for [arrays in ES6](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator). There is also an ES7 proposal for [Object Rest and Spread Properties](https://github.com/sebmarkbage/ecmascript-rest-spread). |
|||
|
|||
In fact, you can already use this in our code base as an experimental syntax: |
|||
|
|||
```javascript |
|||
var oldObj = { foo: 'hello', bar: 'world' }; |
|||
var newObj = { ...oldObj, foo: 'hi' }; |
|||
console.log(newObj.foo); // 'hi'; |
|||
console.log(newObj.bar); // 'world'; |
|||
``` |
|||
|
|||
Merging two objects can be expressed as: |
|||
|
|||
```javascript |
|||
var ab = { ...a, ...b }; |
|||
``` |
|||
|
|||
> Note: |
|||
> |
|||
> Use the [JSX command-line tool](http://npmjs.org/package/react-tools) with the `--harmony` flag to activate the experimental ES7 syntax. |
|||
@ -0,0 +1,159 @@ |
|||
--- |
|||
id: transferring-props |
|||
title: Transferring Props |
|||
permalink: transferring-props.html |
|||
prev: reusable-components.html |
|||
next: forms.html |
|||
--- |
|||
|
|||
It's a common pattern in React to wrap a component in an abstraction. The outer component exposes a simple property to do something that might have more complex implementation details. |
|||
|
|||
You can use [JSX spread attributes](/react/docs/jsx-spread.html) to merge the old props with additional values: |
|||
|
|||
```javascript |
|||
return <Component {...this.props} more="values" />; |
|||
``` |
|||
|
|||
If you don't use JSX, you can use any object helper such as ES6 `Object.assign` or Underscore `_.extend`: |
|||
|
|||
```javascript |
|||
return Component(Object.assign({}, this.props, { more: 'values' })); |
|||
``` |
|||
|
|||
The rest of this tutorial explains best practices. It uses JSX and experimental ES7 syntax. |
|||
|
|||
## Manual Transfer |
|||
|
|||
Most of the time you should explicitly pass the properties down. That ensures that you only exposes a subset of the inner API, one that you know will work. |
|||
|
|||
```javascript |
|||
var FancyCheckbox = React.createClass({ |
|||
render: function() { |
|||
var fancyClass = this.props.checked ? 'FancyChecked' : 'FancyUnchecked'; |
|||
return ( |
|||
<div className={fancyClass} onClick={this.props.onClick}> |
|||
{this.props.children} |
|||
</div> |
|||
); |
|||
} |
|||
}); |
|||
React.renderComponent( |
|||
<FancyCheckbox checked={true} onClick={console.log}> |
|||
Hello world! |
|||
</FancyCheckbox>, |
|||
document.body |
|||
); |
|||
``` |
|||
|
|||
But what about the `name` prop? Or the `title` prop? Or `onMouseOver`? |
|||
|
|||
## Transferring with `...` in JSX |
|||
|
|||
Sometimes it's fragile and tedious to pass every property along. In that case you can use [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) with rest properties to extract a set of unknown properties. |
|||
|
|||
List out all the properties that you would like to consume, followed by `...other`. |
|||
|
|||
```javascript |
|||
var { checked, ...other } = this.props; |
|||
``` |
|||
|
|||
This ensures that you pass down all the props EXCEPT the ones you're consuming yourself. |
|||
|
|||
```javascript |
|||
var FancyCheckbox = React.createClass({ |
|||
render: function() { |
|||
var { checked, ...other } = this.props; |
|||
var fancyClass = checked ? 'FancyChecked' : 'FancyUnchecked'; |
|||
// `other` contains { onClick: console.log } but not the checked property |
|||
return ( |
|||
<div {...other} className={fancyClass} /> |
|||
); |
|||
} |
|||
}); |
|||
React.renderComponent( |
|||
<FancyCheckbox checked={true} onClick={console.log}> |
|||
Hello world! |
|||
</FancyCheckbox>, |
|||
document.body |
|||
); |
|||
``` |
|||
|
|||
> NOTE: |
|||
> |
|||
> In the example above, the `checked` prop is also a valid DOM attribute. If you didn't use destructuring in this way you might inadvertently pass it along. |
|||
|
|||
Always use the destructuring pattern when transferring unknown `other` props. |
|||
|
|||
```javascript |
|||
var FancyCheckbox = React.createClass({ |
|||
render: function() { |
|||
var fancyClass = this.props.checked ? 'FancyChecked' : 'FancyUnchecked'; |
|||
// ANTI-PATTERN: `checked` would be passed down to the inner component |
|||
return ( |
|||
<div {...this.props} className={fancyClass} /> |
|||
); |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
## Consuming and Transferring the Same Prop |
|||
|
|||
If your component wants to consume a property but also pass it along, you can repass it explicitly `checked={checked}`. This is preferable to passing the full `this.props` object since it's easier to refactor and lint. |
|||
|
|||
```javascript |
|||
var FancyCheckbox = React.createClass({ |
|||
render: function() { |
|||
var { checked, title, ...other } = this.props; |
|||
var fancyClass = checked ? 'FancyChecked' : 'FancyUnchecked'; |
|||
var fancyTitle = checked ? 'X ' + title : 'O ' + title; |
|||
return ( |
|||
<label> |
|||
<input {...other} |
|||
checked={checked} |
|||
className={fancyClass} |
|||
type="checkbox" |
|||
/> |
|||
{fancyTitle} |
|||
</label> |
|||
); |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
> NOTE: |
|||
> |
|||
> Order matters. By putting the `{...other}` before your JSX props you ensure that the consumer of your component can't override them. In the example above we have guaranteed that the input will be of type `"checkbox"`. |
|||
|
|||
## Rest and Spread Properties `...` |
|||
|
|||
Rest properties allow you to extract the remaining properties from an object into a new object. It excludes every other property listed in the destructuring pattern. |
|||
|
|||
This is an experimental implementation of an [ES7 proposal](https://github.com/sebmarkbage/ecmascript-rest-spread). |
|||
|
|||
```javascript |
|||
var { x, y, ...z } = { x: 1, y: 2, a: 3, b: 4 }; |
|||
x; // 1 |
|||
y; // 2 |
|||
z; // { a: 3, b: 4 } |
|||
``` |
|||
|
|||
> Note: |
|||
> |
|||
> Use the [JSX command-line tool](http://npmjs.org/package/react-tools) with the `--harmony` flag to activate the experimental ES7 syntax. |
|||
|
|||
## Transferring with Underscore |
|||
|
|||
If you don't use JSX, you can use a library to achieve the same pattern. Underscore supports `_.omit` to filter out properties and `_.extend` to copy properties onto a new object. |
|||
|
|||
```javascript |
|||
var FancyCheckbox = React.createClass({ |
|||
render: function() { |
|||
var checked = this.props.checked; |
|||
var other = _.omit(this.props, 'checked'); |
|||
var fancyClass = checked ? 'FancyChecked' : 'FancyUnchecked'; |
|||
return ( |
|||
React.DOM.div(_.extend({}, other, { className: fancyClass })) |
|||
); |
|||
} |
|||
}); |
|||
``` |
|||
@ -0,0 +1,192 @@ |
|||
--- |
|||
id: glossary |
|||
title: React (Virtual) DOM Terminology |
|||
permalink: glossary.html |
|||
prev: reconciliation.html |
|||
--- |
|||
|
|||
In React's terminology, there are five core types that are important to distinguish: |
|||
|
|||
- [ReactElement / ReactElement Factory](#react-elements) |
|||
- [ReactNode](#react-nodes) |
|||
- [ReactComponent / ReactComponent Class](#react-components) |
|||
|
|||
## React Elements |
|||
|
|||
The primary type in React is the `ReactElement`. It has four properties: `type`, `props`, `key` and `ref`. It has no methods and nothing on the prototype. |
|||
|
|||
You can create one of these object through `React.createElement`. |
|||
|
|||
```javascript |
|||
var root = React.createElement('div'); |
|||
``` |
|||
|
|||
To render a new tree into the DOM, you create `ReactElement`s and pass them to `React.render` a long with a regular DOM `Element` (`HTMLElement` or `SVGElement`). `ReactElement`s are not to be confused with DOM `Element`s. A `ReactElement` is a light, stateless, immutable, virtual representation of a DOM `Element`. It is a virtual DOM. |
|||
|
|||
```javascript |
|||
React.render(root, document.body); |
|||
``` |
|||
|
|||
To add properties to a DOM element, pass a properties object as the second argument and children to the third argument. |
|||
|
|||
```javascript |
|||
var child = React.createElement('li', null, 'Text Content'); |
|||
var root = React.createElement('ul', { className: 'my-list' }, child); |
|||
React.render(root, document.body); |
|||
``` |
|||
|
|||
If you use React JSX, then these `ReactElement`s are created for you. So this is equivalent: |
|||
|
|||
```javascript |
|||
var root = <ul className="my-list"> |
|||
<li>Text Content</li> |
|||
</ul>; |
|||
React.render(root, document.body); |
|||
``` |
|||
|
|||
__Factories__ |
|||
|
|||
A `ReactElement`-factory is simply a function that generates a `ReactElement` with a particular `type` property. React has a built-in helper for you to create factories. It's effectively just: |
|||
|
|||
```javascript |
|||
function createFactory(type){ |
|||
return React.createElement.bind(null, type); |
|||
} |
|||
``` |
|||
|
|||
It allows you to create a convenient short-hand instead of typing out `React.createElement('div')` all the time. |
|||
|
|||
```javascript |
|||
var div = React.createFactory('div'); |
|||
var root = div({ className: 'my-div' }); |
|||
React.render(root, document.body); |
|||
``` |
|||
|
|||
React already have built-in factories for common HTML tags: |
|||
|
|||
```javascript |
|||
var root = React.DOM.ul({ className: 'my-list' }, |
|||
React.DOM.li(null, 'Text Content') |
|||
); |
|||
``` |
|||
|
|||
If you are using JSX you have no need for factories. JSX already provides a convenient short-hand for creating `ReactElement`s. |
|||
|
|||
|
|||
## React Nodes |
|||
|
|||
A `ReactNode` can be either: |
|||
- `ReactElement` |
|||
- `string` (aka `ReactText`) |
|||
- `number` (aka `ReactText`) |
|||
- Array of `ReactNode`s (aka `ReactFragment`) |
|||
|
|||
These are used as properties of other `ReactElement`s to represent children. Effectively they create a tree of `ReactElement`s. |
|||
|
|||
|
|||
## React Components |
|||
|
|||
You can use React using only `ReactElement`s but to really take advantage of React, you'll want to use `ReactComponent`s to create encapsulations with embedded state. |
|||
|
|||
A `ReactComponent` Class is simply just a JavaScript class (or "constructor function"). |
|||
|
|||
```javascript |
|||
var MyComponent = React.createClass({ |
|||
render: function() { |
|||
... |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
When this constructor is invoked it is expected to return an object with at least a `render` method on it. This object is referred to as a `ReactComponent`. |
|||
|
|||
```javascript |
|||
var component = new MyComponent(props); // never do this |
|||
``` |
|||
|
|||
Other than for testing, you would normally __never__ call this constructor yourself. React calls it for you. |
|||
|
|||
Instead, you pass the `ReactComponent` Class to `createElement` you get a `ReactElement`. |
|||
|
|||
```javascript |
|||
var element = React.createElement(MyComponent); |
|||
``` |
|||
|
|||
OR using JSX: |
|||
|
|||
```javascript |
|||
var element = <MyComponent />; |
|||
``` |
|||
|
|||
When this is passed to `React.render`, React will call the constructor for you and create a `ReactComponent`, which returned. |
|||
|
|||
```javascript |
|||
var component = React.render(element, document.body); |
|||
``` |
|||
|
|||
If you keep calling `React.render` with the same type of `ReactElement` and the same container DOM `Element` it always returns the same instance. This instance is stateful. |
|||
|
|||
```javascript |
|||
var componentA = React.render(<MyComponent />, document.body); |
|||
var componentB = React.render(<MyComponent />, document.body); |
|||
componentA === componentB; // true |
|||
``` |
|||
|
|||
This is why you shouldn't construct your own instance. Instead, `ReactElement` is a virtual `ReactComponent` before it gets constructed. An old and new `ReactElement` can be compared to see if a new `ReactComponent` instance is created or if the existing one is reused. |
|||
|
|||
The `render` method of a `ReactComponent` is expected to return another `ReactElement`. This allows these components to be composed. Ultimately the render resolves into `ReactElement` with a `string` tag which instantiates a DOM `Element` instance and inserts it into the document. |
|||
|
|||
|
|||
## Formal Type Definitions |
|||
|
|||
__Entry Point__ |
|||
|
|||
``` |
|||
React.render = (ReactElement, HTMLElement | SVGElement) => ReactComponent; |
|||
``` |
|||
|
|||
__Nodes and Elements__ |
|||
|
|||
``` |
|||
type ReactNode = ReactElement | ReactFragment | ReactText; |
|||
|
|||
type ReactElement = ReactComponentElement | ReactDOMElement; |
|||
|
|||
type ReactDOMElement = { |
|||
type : string, |
|||
props : { |
|||
children : ReactNodeList, |
|||
className : string, |
|||
etc. |
|||
}, |
|||
key : string | boolean | number | null, |
|||
ref : string | null |
|||
}; |
|||
|
|||
type ReactComponentElement<TProps> = { |
|||
type : ReactClass<TProps>, |
|||
props : TProps, |
|||
key : string | boolean | number | null, |
|||
ref : string | null |
|||
}; |
|||
|
|||
type ReactFragment = Array<ReactNode | ReactEmpty>; |
|||
|
|||
type ReactNodeList = ReactNode | ReactEmpty; |
|||
|
|||
type ReactText = string | number; |
|||
|
|||
type ReactEmpty = null | undefined | boolean; |
|||
``` |
|||
|
|||
__Classes and Components__ |
|||
|
|||
``` |
|||
type ReactClass<TProps> = (TProps) => ReactComponent<TProps>; |
|||
|
|||
type ReactComponent<TProps> = { |
|||
props : TProps, |
|||
render : () => ReactElement |
|||
}; |
|||
``` |
|||
|
|||
Loading…
Reference in new issue