@samitouri / QOS-React-2 / commits / 0de35588c1
Fork 0

The library for web and native user interfaces.

jsx gotchas, reference

petehunt committed Jul 14, 2013 at 16:34 UTC 0de35588c1a3ae45ba13d50d2b96533e5b0595af
5 files changed +250 -1
docs/docs/refactor/00-table-of-contents.md
+1 -1
@@ -89,4 +89,4 @@ Reference
89 - API
90 - DOM differences
91 - JSX gotchas
92 -- Antipatterns
92 +
docs/docs/refactor/02-displaying-data.md
+2
@@ -73,4 +73,6 @@ We've found that the best solution for this problem is to generate markup direct
73
74 JSX is very small; the "hello, world" example above uses every feature of JSX. To learn more about it, see [JSX in depth](./02.1-jsx-in-depth.md). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
75
76 +JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./02.2-jsx-gotchas.md) for some key differences.
77 +
78 The easiest way to get started with JSX is to use the in-browser `JSXTransformer`, but in production you'll want to precompile your code using our command-line [react-tools](http://npmjs.org/package/react-tools) package.
\ No newline at end of file
docs/docs/refactor/02.1-jsx-in-depth.md
+2
@@ -159,3 +159,5 @@ efforts include:
159 - JSX is a simple syntactic transform.
160 - JSX neither provides nor requires a runtime library.
161 - JSX does not alter or add to the semantics of JavaScript.
162 +
163 +JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./02.2-jsx-gotchas.md) for some key differences.
docs/docs/refactor/02.2-jsx-gotchas.md new
+89
@@ -0,0 +1,89 @@
1 +# JSX gotchas
2 +
3 +JSX looks like HTML but there are some important differences you may run into.
4 +
5 +## Whitespace removal
6 +
7 +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 `{' '}`.
8 +
9 +```javascript
10 +<div>{this.props.name} {' '} {this.props.surname}</div>
11 +```
12 +
13 +Follow [Issue #65](https://github.com/facebook/react/issues/65) for discussion on this behavior.
14 +
15 +## HTML Entities
16 +
17 +You can insert HTML entities within literal text in JSX:
18 +
19 +```javascript
20 +<div>First &middot; Second</div>
21 +```
22 +
23 +If you want to display an HTML entity within dynamic content, you will run into double escaping issues as React escapes all the strings you are displaying in order to prevent a wide range of XSS attacks by default.
24 +
25 +```javascript
26 +// Bad: It displays "First &middot; Second"
27 +<div>{'First &middot; Second'}</div>
28 +```
29 +
30 +There are various ways to work-around this issue. The easiest one is to write unicode character directly in Javascript. You need to make sure that the file is saved as UTF-8 and that the proper UTF-8 directives are set so the browser will display it correctly.
31 +
32 +```javascript
33 +<div>{'First · Second'}</div>
34 +```
35 +
36 +A safer alternative is to find the [unicode number corresponding to the entity](http://www.fileformat.info/info/unicode/char/b7/index.htm) and use it inside of a JavaScript string.
37 +
38 +```javascript
39 +<div>{'First \u00b7 Second'}</div>
40 +<div>{'First ' + String.fromCharCode(183) + ' Second'}</div>
41 +```
42 +
43 +You can use mixed arrays with strings and JSX elements.
44 +
45 +```javascript
46 +<div>{['First ', <span>&middot;</span>, ' Second']}</div>
47 +```
48 +
49 +As a last resort, you always have the ability to insert raw HTML.
50 +
51 +```javascript
52 +<div dangerouslySetInnerHTML={{'{{'}}__html: 'First &middot; Second'}} />
53 +```
54 +
55 +## Comments
56 +
57 +JSX supports both single-line and multi-line JavaScript comments within a tag declaration:
58 +
59 +```javascript
60 +<div // This is a single-line comment:
61 + /*
62 + And a multi-line
63 + comment
64 + */
65 +/>
66 +```
67 +
68 +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:
69 +
70 +```javascript
71 +// Note: This is not implemented yet!
72 +<div>
73 + {/* This is a comment */}
74 +</div>
75 +```
76 +
77 +## Custom HTML Attributes
78 +
79 +If you pass properties to native HTML elements that do not exist in the HTML specification, React will not render them. If you want to use a custom attribute, you should prefix it with `data-`.
80 +
81 +```javascript
82 +<div data-custom-attribute="foo" />
83 +```
84 +
85 +[Web Accessibility](http://www.w3.org/WAI/intro/aria) attributes starting with `aria-` will be rendered properly.
86 +
87 +```javascript
88 +<div aria-hidden={true} />
89 +```
docs/docs/refactor/09-reference.md new
+156
@@ -0,0 +1,156 @@
1 +# Reference
2 +
3 +## API
4 +
5 +### React
6 +
7 +`React` is the entry point to the React framework. If you're using one of the prebuilt packages it's available as a global; if you're using CommonJS modules you can `require()` it.
8 +
9 +#### React.DOM
10 +
11 +`React.DOM` provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the `/** @jsx React.DOM */` docblock.
12 +
13 +#### React.initializeTouchEvents
14 +
15 +```javascript
16 +initializeTouchEvents(boolean shouldUseTouch)
17 +```
18 +
19 +Configure React's event system to handle touch events on mobile devices.
20 +
21 +#### React.createClass
22 +
23 +```javascript
24 +function createClass(object specification)
25 +```
26 +
27 +Creates a component given a specification. A component implements a `render` method which returns **one single** child. That child may have an arbitrarily deep child structure. One thing that makes components different than a standard prototypal classes is that you don't need to call new on them. They are convenience wrappers that construct backing instances (via new) for you.
28 +
29 +#### React.renderComponent
30 +
31 +```javascript
32 +ReactComponent renderComponent(ReactComponent container, DOMElement container)
33 +```
34 +
35 +Renders a React component into the DOM in the supplied `container`.
36 +
37 +If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
38 +
39 +#### React.unmountAndReleaseReactRootNode
40 +
41 +```javascript
42 +unmountAndReleaseReactRootNode(DOMElement container)
43 +```
44 +
45 +Remove a mounted React component from the DOM and clean up its event handlers and state.
46 +
47 +#### React.renderComponentToString
48 +
49 +```javascript
50 +renderComponentToString(ReactComponent component, function callback)
51 +```
52 +
53 +Render a component to its initial HTML. This should only be used on the server. React will call `callback` with an HTML string when the markup is ready. You can use this method to create static site generators, or you can generate HTML on the server and send it down to have a very fast initial page load. 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.
54 +
55 +### AbstractEvent
56 +
57 +Your event handlers will be passed instances of `AbstractEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event (such as `stopPropagation()` and `preventDefault()`) except they work exactly the same across all browsers.
58 +
59 +If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it.
60 +
61 +### ReactComponent
62 +
63 +Component classses created by `createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming `ReactComponent`s.
64 +
65 +#### getDOMNode
66 +
67 +```javascript
68 +DOMElement getDOMNode()
69 +```
70 +
71 +If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements.
72 +
73 +#### setProps
74 +
75 +```javascript
76 +setProps(object nextProps)
77 +```
78 +
79 +When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `renderComponent()`. Simply call `setProps()` to change its properties and trigger a re-render.
80 +
81 +**Note:** This method can only be called on a root-level component. That is, it's only available on the component passed directly to `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()`.
82 +
83 +#### replaceProps
84 +
85 +```javascript
86 +replaceProps(object nextProps)
87 +```
88 +
89 +Like `setProps()` but deletes any pre-existing props that are not in nextProps.
90 +
91 +#### transferPropsTo
92 +
93 +```javascript
94 +ReactComponent transferPropsTo(ReactComponent targetComponent)
95 +```
96 +
97 +Transfer properties from this component to a target component that have not already been set on the target component. This is usually used to pass down properties to the returned root component. `targetComponent`, now updated with some new props is returned as a convenience.
98 +
99 +#### setState
100 +
101 +```javascript
102 +setState(object nextState[, function callback])
103 +```
104 +
105 +Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once `setState` is completed.
106 +
107 +**Note:** *NEVER* mutate `this.state` directly. As calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
108 +
109 +**Note:** `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value.
110 +
111 +**Note**: There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.
112 +
113 +#### replaceState
114 +
115 +```javascript
116 +replaceState(object nextState[, function callback])
117 +```
118 +
119 +Like `setState()` but deletes any pre-existing state keys that are not in nextState.
120 +
121 +#### forceUpdate()
122 +
123 +```javascript
124 +forceUpdate([function callback])
125 +```
126 +
127 +If your `render()` method reads from something other than `this.props` or `this.state` you'll need to tell React when it needs to re-run `render()`. Use `forceUpdate()` to cause React to automatically re-render. This will cause `render()` to be called on the component and all of its children but React will only update the DOM if the markup changes.
128 +
129 +Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient.
130 +
131 +**Note**: There is no guarantee of synchronous operation of calls to `forceUpdate` and calls may be batched for performance gains.
132 +
133 +#### Lifecycle methods
134 +
135 +```javascript
136 +object getInitialState()
137 +componentWillMount()
138 +componentDidMount(DOMElement domNode)
139 +componentWillReceiveProps(object nextProps)
140 +boolean shouldComponentUpdate(object nextProps, object nextState)
141 +componentWillUpdate(object nextProps, object nextState)
142 +ReactComponent render()
143 +componentDidUpdate(object prevProps, object prevState, DOMElement domNode)
144 +componentWillUnmount()
145 +```
146 +
147 +See the [working with the browser](./07-working-with-the-browser.md) documentation for more details on these lifecycle methods.
148 +
149 +## DOM differences
150 +
151 +React has implemented a browser-independent events and DOM system for performance and cross-browser compatibility reasons. We took the opportunity to clean up a few rough edges in browser DOM implementations.
152 +
153 +* All events (including submit) bubble correctly per the W3C spec
154 +* All event objects conform to the W3C spec
155 +* All DOM properties and attributes (including event handlers) should be camelCased to be consistent with standard JavaScript style. We intentionally break with the spec here, since the spec is inconsistent.
156 +* `onChange` behaves as you would expect it to: whenever a form field is changed this event is fired rather than inconsistently on blur. We intentionally break from existing browser behavior because `onChange` is a misnomer for its behavior and React relies on this event to react to user input in real time.
\ No newline at end of file