Updated Docs for new JSX Changes
Moved non-JSX explanation to Displaying Data. Overhauled JSX in Depth. Added JSX Spread Section.
Sebastian Markbage committed
Oct 28, 2014 at 01:21 UTC
9b1ee4de4636fcc9af1cf93099e062a3f6eb96f5
4 files changed
+166
-94
docs/docs/02-displaying-data.md
+41
-3
@@ -77,12 +77,50 @@ React components are very simple. You can think of them as simple function that
77
78
We strongly believe that components are the right way to separate concerns rather than "templates" and "display logic." We think that markup and the code that generates it are intimately tied together. Additionally, display logic is often very complex and using template languages to express it becomes cumbersome.
79
80
-We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a very simple, **optional** HTML-like syntax for the function calls that generate markup called JSX.
80
+We've found that the best solution for this problem is to generate HTML and component trees directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs.
81
82
-**JSX lets you write JavaScript function calls with HTML syntax.** To generate a link in React using pure JavaScript you'd write: `React.createElement('a', {href: 'http://facebook.github.io/react/'}, 'Hello React!')`. With JSX this becomes `<a href="http://facebook.github.io/react/">Hello React!</a>`. We've found this has made building React apps easier and designers tend to prefer the syntax, but everyone has their own workflow, so **JSX is not required to use React.**
82
+In order to make this easier, we've added a very simple, **optional** HTML-like syntax to create these React tree nodes.
83
84
-JSX is very small; the "hello, world" example above uses every feature of JSX. To learn more about it, see [JSX in depth](/react/docs/jsx-in-depth.html). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
84
+**JSX lets you create JavaScript objects using HTML syntax.** To generate a link in React using pure JavaScript you'd write:
85
+
86
+`React.createElement('a', {href: 'http://facebook.github.io/react/'}, 'Hello!')`
87
+
88
+With JSX this becomes:
89
+
90
+`<a href="http://facebook.github.io/react/">Hello!</a>`
91
+
92
+We've found this has made building React apps easier and designers tend to prefer the syntax, but everyone has their own workflow, so **JSX is not required to use React.**
93
+
94
+JSX is very small. To learn more about it, see [JSX in depth](/react/docs/jsx-in-depth.html). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
95
96
JSX is similar to HTML, but not exactly the same. See [JSX gotchas](/react/docs/jsx-gotchas.html) for some key differences.
97
98
The easiest way to get started with JSX is to use the in-browser `JSXTransformer`. We strongly recommend that you don't use this in production. You can precompile your code using our command-line [react-tools](http://npmjs.org/package/react-tools) package.
99
+
100
+
101
+## React without JSX
102
+
103
+JSX is completely optional. You don't have to use JSX with React. You can create these trees through `React.createElement`. The first argument is the tag, pass a properties object as the second argument and children to the third argument.
104
+
105
+```javascript
106
+var child = React.createElement('li', null, 'Text Content');
107
+var root = React.createElement('ul', { className: 'my-list' }, child);
108
+React.render(root, document.body);
109
+```
110
+
111
+As a convenience you can create short-hand factory function to create elements from custom components.
112
+
113
+```javascript
114
+var Factory = React.createFactory(ComponentClass);
115
+...
116
+var root = Factory({ custom: 'prop' });
117
+React.render(root, document.body);
118
+```
119
+
120
+React already have built-in factories for common HTML tags:
121
+
122
+```javascript
123
+var root = React.DOM.ul({ className: 'my-list' },
124
+ React.DOM.li(null, 'Text Content')
125
+ );
126
+```
docs/docs/02.1-jsx-in-depth.md
+53
-90
@@ -3,32 +3,51 @@ id: jsx-in-depth
3
title: JSX in Depth
4
permalink: jsx-in-depth.html
5
prev: displaying-data.html
6
-next: jsx-gotchas.html
6
+next: jsx-spread.html
7
---
8
9
-JSX is a JavaScript XML syntax transform recommended for use
10
-with React.
9
+[JSX](http://facebook.github.io/jsx/) is a JavaScript syntax extension that looks similar to XML. You can use a simple JSX syntactic transform with React.
10
11
## Why JSX?
12
14
-React works out of the box without JSX. Simply construct your markup using the
15
-functions on `React.DOM`. For example, here's how to construct a simple link:
13
+You don't have to use JSX with React. You can just use plain JS. However, we recommend using JSX because it is a concise and familiar syntax for defining tree structures with attributes.
14
+
15
+It's more familiar for casual developers such as designers.
16
+
17
+XML has the benefit of balanced open and closing tags. This helps make large trees easier to read than function calls or object literals.
18
+
19
+It doesn't alter the semantics of JavaScript.
20
+
21
+## HTML Tags vs. React Components
22
+
23
+React can either render HTML tags (strings) or React components (classes).
24
+
25
+To render a HTML tag, just use lower-case tag names in JSX:
26
27
```javascript
18
-var link = React.DOM.a({href: 'http://facebook.github.io/react'}, 'React');
28
+var myDivElement = <div className="foo" />;
29
+React.render(myDivElement, document.body);
30
```
31
21
-We recommend using JSX for many reasons:
32
+To render a React Component, just a local variable that starts with an upper-case letter:
33
23
-* It's easier to visualize the structure of the DOM.
24
-* Designers are more comfortable making changes.
25
-* It's familiar for those who have used MXML or XAML.
34
+```javascript
35
+var MyComponent = React.createClass({/*...*/});
36
+var myElement = <MyComponent someProperty={true} />;
37
+React.render(myElement, document.body);
38
+```
39
+
40
+React's JSX uses the upper vs. lower case convention to distinguish between local component classes and HTML tags.
41
42
+> Note:
43
+>
44
+> Since JSX is JavaScript, identifiers such as `class` and `for` are discouraged
45
+> as XML attribute names. Instead, React DOM components expect DOM property
46
+> names like `className` and `htmlFor`, respectively.
47
48
## The Transform
49
30
-JSX transforms from an XML-like syntax into native JavaScript. XML elements and
31
-attributes are transformed into arguments to `React.createElement`.
50
+React JSX transforms from an XML-like syntax into native JavaScript. XML elements, attributes and children are transformed into arguments to `React.createElement`.
51
52
```javascript
53
var Nav;
@@ -47,7 +66,11 @@ var Nav, Profile;
66
// Input (JSX):
67
var app = <Nav color="blue"><Profile>click</Profile></Nav>;
68
// Output (JS):
50
-var app = React.createElement(Nav, {color:"blue"}, React.createElement(Profile, null, "click"));
69
+var app = React.createElement(
70
+ Nav,
71
+ {color:"blue"},
72
+ React.createElement(Profile, null, "click")
73
+);
74
```
75
76
Use the [JSX Compiler](/react/jsx-compiler.html) to try out JSX and see how it
@@ -55,72 +78,14 @@ desugars into native JavaScript, and the
78
[HTML to JSX converter](/react/html-jsx.html) to convert your existing HTML to
79
JSX.
80
58
-If you want to use JSX, the [Getting Started](/react/docs/getting-started.html) guide shows
59
-how to setup compilation.
81
+If you want to use JSX, the [Getting Started](/react/docs/getting-started.html) guide shows how to setup compilation.
82
83
> Note:
84
>
63
-> Details about the code transform are given here to increase understanding, but
64
-> your code should not rely on these implementation details.
65
-
66
-
67
-## React and JSX
68
-
69
-React and JSX are independent technologies, but JSX was primarily built with
70
-React in mind. The two valid uses of JSX are:
71
-
72
-* To construct instances of React DOM components (`React.DOM.*`).
73
-* To construct instances of composite components created with
74
- `React.createClass()`.
75
-
76
-### React DOM Components
77
-
78
-To construct a `<div>` is to create a variable that refers to `React.DOM.div`.
79
-
80
-```javascript
81
-var div = React.DOM.div;
82
-var app = <div className="appClass">Hello, React!</div>;
83
-```
84
-
85
-### React Composite Components
86
-
87
-To construct an instance of a composite component, create a variable that
88
-references the class.
89
-
90
-```javascript
91
-var MyComponent = React.createClass({/*...*/});
92
-var app = <MyComponent someProperty={true} />;
93
-```
94
-
95
-JSX will infer the component's name from the variable assignment and specify
96
-the class's [displayName](/react/docs/component-specs.html#displayName) accordingly.
97
-
98
-See [Multiple Components](/react/docs/multiple-components.html) to learn more about using composite components.
99
-
100
-> Note:
101
->
102
-> Since JSX is JavaScript, identifiers such as `class` and `for` are discouraged
103
-> as XML attribute names. Instead, React DOM components expect attributes like
104
-> `className` and `htmlFor`, respectively.
105
-
106
-## DOM Convenience
107
-
108
-Having to define variables for every type of DOM element can get tedious
109
-(e.g. `var div, span, h1, h2, ...`). JSX provides a convenience to address this
110
-problem:
111
-
112
-```javascript
113
-var Nav;
114
-// Input (JSX):
115
-var tree = <Nav><span /></Nav>;
116
-// Output (JS):
117
-var tree = Nav(null, React.DOM.span(null));
118
-```
119
-
120
-> Remember:
121
->
122
-> JSX simply transforms elements into function calls and has no notion of the
123
-> DOM.
85
+> The JSX expression always evaluates to a ReactElement. The actual
86
+> implementation details may vary. An optimized mode could inline the
87
+> ReactElement as an object literal to bypass the validation code in
88
+> `React.createElement`.
89
90
## JavaScript Expressions
91
@@ -133,7 +98,10 @@ pair of curly braces (`{}`) instead of quotes (`""`).
98
// Input (JSX):
99
var person = <Person name={window.isLoggedIn ? window.name : ''} />;
100
// Output (JS):
136
-var person = Person({name: window.isLoggedIn ? window.name : ''});
101
+var person = React.createElement(
102
+ Person,
103
+ {name: window.isLoggedIn ? window.name : ''}
104
+);
105
```
106
107
### Child Expressions
@@ -144,7 +112,11 @@ Likewise, JavaScript expressions may be used to express children:
112
// Input (JSX):
113
var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;
114
// Output (JS):
147
-var content = Container(null, window.isLoggedIn ? Nav(null) : Login(null));
115
+var content = React.createElement(
116
+ Container,
117
+ null,
118
+ window.isLoggedIn ? React.createElement(Nav) : React.createElement(Login)
119
+);
120
```
121
122
### Comments
@@ -165,15 +137,6 @@ var content = (
137
);
138
```
139
168
-
169
-## Prior Work
170
-
171
-JSX is similar to several other JavaScript embedded XML language
172
-proposals/projects. Some of the features of JSX that distinguish it from similar
173
-efforts include:
174
-
175
-* JSX is a simple syntactic transform.
176
-* JSX neither provides nor requires a runtime library.
177
-* JSX does not alter or add to the semantics of JavaScript.
178
-
179
-JSX is similar to HTML, but not exactly the same. See [JSX gotchas](/react/docs/jsx-gotchas.html) for some key differences.
140
+> NOTE:
141
+>
142
+> JSX is similar to HTML, but not exactly the same. See [JSX gotchas](/react/docs/jsx-gotchas.html) for some key differences.
docs/docs/02.2-jsx-spread.md
new
+71
@@ -0,0 +1,71 @@
1
+---
2
+id: jsx-spread
3
+title: JSX Spread Attributes
4
+permalink: jsx-spread.html
5
+prev: jsx-in-depth.html
6
+next: jsx-gotchas.html
7
+---
8
+
9
+If you know all the properties that you want to place on a component a head of time, it is easy to use JSX:
10
+
11
+```javascript
12
+ var component = <Component foo={x} bar={y} />;
13
+```
14
+
15
+## Mutating Props is Bad, mkay
16
+
17
+If you don't know which properties you want to set, you might be tempted to add them onto the object later:
18
+
19
+```javascript
20
+ var component = <Component />;
21
+ component.props.foo = x; // bad
22
+ component.props.bar = y; // also bad
23
+```
24
+
25
+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.
26
+
27
+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.
28
+
29
+## Spread Attributes
30
+
31
+Now you can use a new feature of JSX called spread attributes:
32
+
33
+```javascript
34
+ var props = {};
35
+ props.foo = x;
36
+ props.bar = y;
37
+ var component = <Component {...props} />;
38
+```
39
+
40
+The properties of the object that you pass in are copied onto the component's props.
41
+
42
+You can use this multiple times or combine it with other attributes. The specification order is important. Later attributes override previous ones.
43
+
44
+```javascript
45
+ var props = { foo: 'default' };
46
+ var component = <Component {...props} foo={'override'} />;
47
+ console.log(component.props.foo); // 'override'
48
+```
49
+
50
+## What's with the weird `...` notation?
51
+
52
+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).
53
+
54
+In fact, you can already use this in our code base as an experimental syntax:
55
+
56
+```javascript
57
+ var oldObj = { foo: 'hello', bar: 'world' };
58
+ var newObj = { ...oldObj, foo: 'hi' };
59
+ console.log(newObj.foo); // 'hi';
60
+ console.log(newObj.bar); // 'world';
61
+```
62
+
63
+Merging two objects can be expressed as:
64
+
65
+```javascript
66
+ var ab = { ...a, ...b };
67
+```
68
+
69
+> Note:
70
+>
71
+> Activate experimental syntax by using the [JSX command-line tool](http://npmjs.org/package/react-tools) with the `--harmony` flag.
docs/docs/02.3-jsx-gotchas.md
renamed
+1
-1
@@ -2,7 +2,7 @@
2
id: jsx-gotchas
3
title: JSX Gotchas
4
permalink: jsx-gotchas.html
5
-prev: jsx-in-depth.html
5
+prev: jsx-spread.html
6
next: interactivity-and-dynamic-uis.html
7
---
8