+ Hello, ! + It is {this.props.date.toTimeString()} +
+ ); + } +}); + +setInterval(function() { + React.renderComponent( +` is to create a variable that refers to `React.DOM.div`.
@@ -81,7 +82,7 @@ var div = React.DOM.div;
var app = {window.isLoggedIn ? : ;
// Output (JS):
-var content = Container(null, window.isLoggedIn ? Nav(null, null) : Login(null, null));
+var content = Container(null, window.isLoggedIn ? Nav(null) : Login(null));
+```
+
+### Comments
+
+It's easy to add comments within your JSX; they're just JS expressions:
+```javascript
+var content = {/* this is a comment */} ;
```
## Tooling
Beyond the compilation step, JSX does not require any special tools.
-- Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
-- Linting provides accurate line numbers after compiling without sourcemaps.
-- Elements use standard scoping so linters can find usage of out-of-scope
+* Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
+* Linting provides accurate line numbers after compiling without sourcemaps.
+* Elements use standard scoping so linters can find usage of out-of-scope
components.
## Prior Work
@@ -163,6 +171,8 @@ JSX is similar to several other JavaScript embedded XML language
proposals/projects. Some of the features of JSX that distinguish it from similar
efforts include:
-- JSX is a simple syntactic transform.
-- JSX neither provides nor requires a runtime library.
-- JSX does not alter or add to the semantics of JavaScript.
+* JSX is a simple syntactic transform.
+* JSX neither provides nor requires a runtime library.
+* JSX does not alter or add to the semantics of JavaScript.
+
+JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./jsx-gotchas.html) for some key differences.
diff --git a/docs/docs/jsx-is-not-html.md b/docs/docs/02.2-jsx-gotchas.md
similarity index 77%
rename from docs/docs/jsx-is-not-html.md
rename to docs/docs/02.2-jsx-gotchas.md
index 42013e9196..0b89ad18db 100644
--- a/docs/docs/jsx-is-not-html.md
+++ b/docs/docs/02.2-jsx-gotchas.md
@@ -1,14 +1,16 @@
---
-id: docs-jsx-is-not-html
-title: JSX is not HTML
-description: Differences between JSX and HTML.
+id: jsx-gotchas
+title: JSX Gotchas
layout: docs
-prev: api.html
+permalink: jsx-gotchas.html
+prev: jsx-in-depth.html
+next: interactivity-and-dynamic-uis.html
---
JSX looks like HTML but there are some important differences you may run into.
-## Whitespace removal
+
+## Whitespace Removal
JSX doesn't follow the same whitespace elimination rules as HTML. JSX removes all whitespace between two curly braces expressions. If you want to have whitespace, simply add `{' '}`.
@@ -18,6 +20,7 @@ JSX doesn't follow the same whitespace elimination rules as HTML. JSX removes al
Follow [Issue #65](https://github.com/facebook/react/issues/65) for discussion on this behavior.
+
## HTML Entities
You can insert HTML entities within literal text in JSX:
@@ -58,27 +61,6 @@ As a last resort, you always have the ability to insert raw HTML.
```
-## Comments
-
-JSX supports both single-line and multi-line JavaScript comments within a tag declaration:
-
-```javascript
-
-```
-
-As of React 0.3, there is no good way to insert comments within the children section. [Issue #82](https://github.com/facebook/react/issues/82) is tracking progress to enable the following:
-
-```javascript
-// Note: This is not implemented yet!
-
+ );
+ }
+});
+
+var ProfileLink = React.createClass({
+ render: function() {
+ return (
+
+ {this.props.username}
+
+ );
+ }
+});
+
+React.renderComponent(
+
+
+// Render Pass 2
+
+
+```
+
+Intuitively, `
+
+// Render Pass 2
+
+
+```
+
+
+### Dynamic Children
+
+The situation gets more complicated when the children are shuffled around (as in search results) or if new components are added onto the front of the list (as in streams). In these cases where the identity and state of each child must be maintained across render passes, you can uniquely identify each child by assigning it a `key`:
+
+```javascript
+ render: function() {
+ var results = this.props.results;
+ return (
+
+ Click here!
+ ,
+ document.getElementById('example')
+);
+```
+
+
+## Mixins
+
+Components are the best way to reuse code in React, but sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](http://en.wikipedia.org/wiki/Cross-cutting_concern). React provides `mixins` to solve this problem.
+
+One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](./working-with-the-browser.html) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed.
+
+```javascript
+/** @jsx React.DOM */
+
+var SetIntervalMixin = {
+ componentWillMount: function() {
+ this.intervals = [];
+ },
+ setInterval: function() {
+ this.intervals.push(setInterval.apply(null, arguments));
+ },
+ componentWillUnmount: function() {
+ this.intervals.map(clearInterval);
+ }
+};
+
+var TickTock = React.createClass({
+ mixins: [SetIntervalMixin], // Use the mixin
+ getInitialState: function() {
+ return {seconds: 0};
+ },
+ componentDidMount: function() {
+ this.setInterval(this.tick, 1000); // Call a method on the mixin
+ },
+ tick: function() {
+ this.setState({seconds: this.state.seconds + 1});
+ },
+ render: function() {
+ return (
+
+ Hello, React!
;
```
-**React Component Components**
+### React Component Components
To construct an instance of a composite component, create a variable that
references the class.
@@ -114,7 +115,7 @@ var Nav;
// Input (JSX):
var tree = ;
// Output (JS):
-var tree = Nav(null, React.DOM.span(null, null));
+var tree = Nav(null, React.DOM.span(null));
```
> Remember:
@@ -125,7 +126,7 @@ var tree = Nav(null, React.DOM.span(null, null));
## JavaScript Expressions
-#### Attribute Expressions
+### Attribute Expressions
To use a JavaScript expression as an attribute value, wrap the expression in a
pair of curly braces (`{}`) instead of quotes (`""`).
@@ -137,7 +138,7 @@ var person =
- {/* This is a comment */}
-
-```
## Custom HTML Attributes
diff --git a/docs/docs/03-interactivity-and-dynamic-uis.md b/docs/docs/03-interactivity-and-dynamic-uis.md
new file mode 100644
index 0000000000..f679bf9843
--- /dev/null
+++ b/docs/docs/03-interactivity-and-dynamic-uis.md
@@ -0,0 +1,89 @@
+---
+id: interactivity-and-dynamic-uis
+title: Interactivity and Dynamic UIs
+layout: docs
+permalink: interactivity-and-dynamic-uis.html
+prev: jsx-gotchas.html
+next: multiple-components.html
+---
+
+You've already [learned how to display data](./displaying-data.html) with React. Now let's look at how to make our UIs interactive.
+
+
+## A Simple Example
+
+```javascript
+/** @jsx React.DOM */
+
+var LikeButton = React.createClass({
+ getInitialState: function() {
+ return {liked: false};
+ },
+ handleClick: function(event) {
+ this.setState({liked: !this.state.liked});
+ },
+ render: function() {
+ var text = this.state.liked ? 'like' : 'unlike';
+ return (
+ + You {text} this. Click to toggle. +
+ ); + } +}); + +React.renderComponent( +
+
+ );
+ }
+});
+
+var ProfilePic = React.createClass({
+ render: function() {
+ return (
+ Paragraph 1
+Paragraph 2
+Paragraph 2
+Paragraph 1
` was removed. Instead, React will reconcile the DOM by changing the text content of the first child and destroying the last child. React reconciles according to the *order* of the children. + + +### Stateful Children + +For most components, this is not a big deal. However, for stateful components that maintain data in `this.state` across render passes, this can be very problematic. + +In most cases, this can be sidestepped by hiding elements instead of destroying them: + +```html +// Render Pass 1 +Paragraph 1
+Paragraph 2
+Paragraph 1
+Paragraph 2
+-
+ {this.results.map(function(result) {
+ return
- {result.text} ; + })} +
+ React has been running for {this.state.seconds} seconds. +
+ ); + } +}); + +React.renderComponent( +