@samitouri / QOS-React-2 / commits / 364d6029b6

Flesh out reference documentation, more API info

Ben Alpert committed Sep 15, 2013 at 22:30 UTC 364d6029b6e095eeee31525c291b0181d0a78f1a

17 files changed +691 -219

docs/Gemfile

@@ -1,5 +1,7 @@

1 source 'https://rubygems.org'

3 +gem 'rake'

4 +

5 # jekyll, which builds it all

6 gem 'jekyll', '~>1.0'

docs/Gemfile.lock

@@ -28,6 +28,7 @@ GEM

28 pygments.rb (0.5.0)

29 posix-spawn (~> 0.3.6)

30 yajl-ruby (~> 1.1.0)

31 + rake (10.0.4)

32 rb-fsevent (0.9.3)

33 redcarpet (2.2.2)

34 safe_yaml (0.7.1)

@@ -41,6 +42,7 @@ PLATFORMS

42 DEPENDENCIES

43 jekyll (~> 1.0)

44 json

45 + rake

46 rb-fsevent

47 redcarpet

48 sass

docs/_config.yml

+16 -2

@@ -51,5 +51,19 @@ nav_docs_sections:

51 title: More About Refs

52 - id: tooling-integration

53 title: Tooling Integration

54 - - id: reference

55 - title: Reference

54 + - id: examples

55 + title: Examples

56 +- title: Reference

57 + items:

58 + - id: top-level-api

59 + title: Top-Level API

60 + - id: component-api

61 + title: Component API

62 + - id: component-specs

63 + title: Component Specs and Lifecycle

64 + - id: tags-and-attributes

65 + title: Supported Tags and Attributes

66 + - id: events

67 + title: Event System

68 + - id: dom-differences

69 + title: DOM Differences

docs/_css/react.scss

+2 -3

@@ -199,8 +199,7 @@ li {

199 font-size: 14px;

200 // position: fixed;

201 float: left;

202 - top: 100px;

203 - width: 180px;

202 + width: 210px;

203

204 ul {

205 list-style: none;

@@ -702,4 +701,4 @@ p code {

701 .next {

702 float: right;

703 }

705 -}

\ No newline at end of file

704 +}

docs/_posts/2013-07-23-community-roundup-5.md

+1 -1

@@ -96,4 +96,4 @@ React.renderComponent(

96 > * [Working With the Browser](/react/docs/working-with-the-browser.html)

97 > * [More About Refs](/react/docs/more-about-refs.html)

98 > * [Tooling integration](/react/docs/tooling-integration.html)

99 -> * [Reference](/react/docs/reference.html)

99 +> * [Reference](/react/docs/core-api.html)

docs/docs/04-multiple-components.md

+1 -1

@@ -144,7 +144,7 @@ In React, data flows from owner to owned component through `props` as discussed

144

145 You may be thinking that it's expensive to react to changing data if there are a large number of nodes under an owner. The good news is that JavaScript is fast and `render()` methods tend to be quite simple, so in most applications this is extremely fast. Additionally, the bottleneck is almost always the DOM mutation and not JS execution and React will optimize this for you using batching and change detection.

146

147 -However, sometimes you really want to have fine-grained control over your performance. In that case, simply override `shouldComponentUpdate()` to return false when you want React to skip processing of a subtree. See [the React reference docs](./reference.html) for more information.

147 +However, sometimes you really want to have fine-grained control over your performance. In that case, simply override `shouldComponentUpdate()` to return false when you want React to skip processing of a subtree. See [the React reference docs](component-specs.html) for more information.

148

149 > Note:

150 >

docs/docs/08-tooling-integration.md

+1 -1

@@ -4,7 +4,7 @@ title: Tooling Integration

4 layout: docs

5 permalink: tooling-integration.html

6 prev: more-about-refs.html

7 -next: reference.html

7 +next: examples.html

8 ---

10 Every project uses a different system for building and deploying JavaScript. We've tried to make React as environment-agnostic as possible.

docs/docs/09-examples.md new

+22

@@ -0,0 +1,22 @@

1 +---

2 +id: examples

3 +title: Examples

4 +layout: docs

5 +permalink: examples.html

6 +prev: tooling-integration.html

7 +---

8 +

9 +### Production Apps

10 +

11 +* All of [Instagram.com](http://instagram.com/) is built on React.

12 +* Many components on [Facebook.com](http://www.facebook.com/), including the commenting interface, ads creation flows, and page insights.

13 +* [Khan Academy](http://khanacademy.org/) is using React for its question editor.

14 +

15 +

16 +### Sample Code

17 +

18 +* We've included [a step-by-step comment box tutorial](./tutorial.html).

19 +* [The React starter kit](/react/downloads.html) includes several examples which you can [view online in our GitHub repository](https://github.com/facebook/react/tree/master/examples/).

20 +* [React Page](https://github.com/facebook/react-page) is a simple React project creator to get you up-and-running quickly with React. It supports both server-side and client-side rendering, source transform and packaging JSX files using CommonJS modules, and instant reload.

21 +* [React one-hour email](https://github.com/petehunt/react-one-hour-email/commits/master) goes step-by-step from a static HTML mock to an interactive email reader (written in just one hour!)

22 +* [Rendr + React app template](https://github.com/petehunt/rendr-react-template/) demonstrates how to use React's server rendering capabilities.

docs/docs/09-reference.md deleted

-209

@@ -1,209 +0,0 @@

1 ----

2 -id: reference

3 -title: Reference

4 -layout: docs

5 -permalink: reference.html

6 -prev: tooling-integration.html

7 ----

8 -

9 -## Examples

10 -

11 -

12 -### Production Apps

13 -

14 -* All of [Instagram.com](http://instagram.com/) is built on React.

15 -* Many components on [Facebook.com](http://www.facebook.com/), including the commenting interface, ads creation flows, and page insights.

16 -* [Khan Academy](http://khanacademy.org/) is using React for its question editor.

17 -

18 -

19 -### Sample Code

20 -

21 -* We've included [a step-by-step comment box tutorial](./tutorial.html).

22 -* [The React starter kit](/react/downloads.html) includes several examples which you can [view online in our GitHub repository](https://github.com/facebook/react/tree/master/examples/).

23 -* [reactapp](https://github.com/jordwalke/reactapp) is a simple app template to get you up-and-running quickly with React.

24 -* [React one-hour email](https://github.com/petehunt/react-one-hour-email/commits/master) goes step-by-step from a static HTML mock to an interactive email reader (written in just one hour!)

25 -* [Rendr + React app template](https://github.com/petehunt/rendr-react-template/) demonstrates how to use React's server rendering capabilities.

26 -

27 -

28 -## API

29 -

30 -### React

31 -

32 -`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.

33 -

34 -

35 -#### React.DOM

36 -

37 -`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.

38 -

39 -

40 -#### React.initializeTouchEvents

41 -

42 -```javascript

43 -initializeTouchEvents(boolean shouldUseTouch)

44 -```

45 -

46 -Configure React's event system to handle touch events on mobile devices.

47 -

48 -

49 -#### React.createClass

50 -

51 -```javascript

52 -function createClass(object specification)

53 -```

54 -

55 -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 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.

56 -

57 -

58 -#### React.renderComponent

59 -

60 -```javascript

61 -ReactComponent renderComponent(ReactComponent container, DOMElement container)

62 -```

63 -

64 -Renders a React component into the DOM in the supplied `container`.

65 -

66 -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.

67 -

68 -

69 -#### React.unmountAndReleaseReactRootNode

70 -

71 -```javascript

72 -unmountAndReleaseReactRootNode(DOMElement container)

73 -```

74 -

75 -Remove a mounted React component from the DOM and clean up its event handlers and state.

76 -

77 -

78 -#### React.renderComponentToString

79 -

80 -```javascript

81 -renderComponentToString(ReactComponent component, function callback)

82 -```

83 -

84 -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.

85 -

86 -

87 -### AbstractEvent

88 -

89 -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.

90 -

91 -If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it.

92 -

93 -

94 -### ReactComponent

95 -

96 -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.

97 -

98 -

99 -#### getDOMNode

100 -

101 -```javascript

102 -DOMElement getDOMNode()

103 -```

104 -

105 -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.

106 -

107 -

108 -#### setProps

109 -

110 -```javascript

111 -setProps(object nextProps)

112 -```

113 -

114 -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.

115 -

116 -> Note:

117 ->

118 -> 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()`.

119 -

120 -

121 -#### replaceProps

122 -

123 -```javascript

124 -replaceProps(object nextProps)

125 -```

126 -

127 -Like `setProps()` but deletes any pre-existing props that are not in nextProps.

128 -

129 -

130 -#### transferPropsTo

131 -

132 -```javascript

133 -ReactComponent transferPropsTo(ReactComponent targetComponent)

134 -```

135 -

136 -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.

137 -

138 -

139 -#### setState

140 -

141 -```javascript

142 -setState(object nextState[, function callback])

143 -```

144 -

145 -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.

146 -

147 -> Note:

148 ->

149 -> *NEVER* mutate `this.state` directly. As calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.

150 -

151 -> Note:

152 ->

153 -> `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.

154 -

155 -> Note:

156 ->

157 -> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.

158 -

159 -

160 -#### replaceState

161 -

162 -```javascript

163 -replaceState(object nextState[, function callback])

164 -```

165 -

166 -Like `setState()` but deletes any pre-existing state keys that are not in nextState.

167 -

168 -

169 -#### forceUpdate()

170 -

171 -```javascript

172 -forceUpdate([function callback])

173 -```

174 -

175 -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.

176 -

177 -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.

178 -

179 -> Note:

180 ->

181 -> There is no guarantee of synchronous operation of calls to `forceUpdate` and calls may be batched for performance gains.

182 -

183 -

184 -#### Lifecycle methods

185 -

186 -```javascript

187 -object getInitialState()

188 -componentWillMount()

189 -componentDidMount(DOMElement domNode)

190 -componentWillReceiveProps(object nextProps)

191 -boolean shouldComponentUpdate(object nextProps, object nextState)

192 -componentWillUpdate(object nextProps, object nextState)

193 -ReactComponent render()

194 -componentDidUpdate(object prevProps, object prevState, DOMElement domNode)

195 -componentWillUnmount()

196 -```

197 -

198 -See the [working with the browser](./working-with-the-browser.html) documentation for more details on these lifecycle methods.

199 -

200 -

201 -## DOM Differences

202 -

203 -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.

204 -

205 -* All events (including submit) bubble correctly per the W3C spec

206 -* All event objects conform to the W3C spec

207 -* 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.

208 -* The `style` attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM `style` JavaScript property, is more efficient, and prevents XSS security holes.

209 -* `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.

docs/docs/ref-01-top-level-api.md new

+73

@@ -0,0 +1,73 @@

1 +---

2 +id: top-level-api

3 +title: Top-Level API

4 +layout: docs

5 +permalink: top-level-api.html

6 +next: component-api.html

7 +---

8 +

9 +## React

10 +

11 +`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.

12 +

13 +

14 +### React.DOM

15 +

16 +`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.

17 +

18 +

19 +### React.initializeTouchEvents

20 +

21 +```javascript

22 +initializeTouchEvents(boolean shouldUseTouch)

23 +```

24 +

25 +Configure React's event system to handle touch events on mobile devices.

26 +

27 +

28 +### React.createClass

29 +

30 +```javascript

31 +function createClass(object specification)

32 +```

33 +

34 +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 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.

35 +

36 +For more information about the specification object, see [Component Specs and Lifecycle](component-specs.html).

37 +

38 +

39 +### React.renderComponent

40 +

41 +```javascript

42 +ReactComponent renderComponent(

43 + ReactComponent component,

44 + DOMElement container,

45 + [function callback]

46 +)

47 +```

48 +

49 +Renders a React component into the DOM in the supplied `container`.

50 +

51 +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.

52 +

53 +If the optional callback is provided, it will be executed after the component is rendered or updated.

54 +

55 +

56 +### React.unmountAndReleaseReactRootNode

57 +

58 +```javascript

59 +unmountAndReleaseReactRootNode(DOMElement container)

60 +```

61 +

62 +Remove a mounted React component from the DOM and clean up its event handlers and state.

63 +

64 +

65 +### React.renderComponentToString

66 +

67 +```javascript

68 +renderComponentToString(ReactComponent component, function callback)

69 +```

70 +

71 +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 can 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.

72 +

73 +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.

docs/docs/ref-02-component-api.md new

+109

@@ -0,0 +1,109 @@

1 +---

2 +id: component-api

3 +title: Component API

4 +layout: docs

5 +permalink: component-api.html

6 +prev: top-level-api.html

7 +next: component-specs.html

8 +---

9 +

10 +## ReactComponent

11 +

12 +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 these component objects.

13 +

14 +

15 +### getDOMNode

16 +

17 +```javascript

18 +DOMElement getDOMNode()

19 +```

20 +

21 +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.

22 +

23 +

24 +### setProps

25 +

26 +```javascript

27 +setProps(object nextProps)

28 +```

29 +

30 +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.

31 +

32 +> Note:

33 +>

34 +> 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()`.

35 +

36 +

37 +### replaceProps

38 +

39 +```javascript

40 +replaceProps(object nextProps)

41 +```

42 +

43 +Like `setProps()` but deletes any pre-existing props instead of merging the two objects.

44 +

45 +

46 +### transferPropsTo

47 +

48 +```javascript

49 +ReactComponent transferPropsTo(ReactComponent targetComponent)

50 +```

51 +

52 +Transfer properties from this component to a target component that have not already been set on the target component. After the props are updated, `targetComponent` is returned as a convenience. This function is useful when creating simple HTML-like components:

53 +

54 +```javascript

55 +var Avatar = React.createClass({

56 + render: function() {

57 + return this.transferPropsTo(

58 + <img src={"/avatars/" + this.props.userId + ".png"} userId={null} />

59 + );

60 + }

61 +});

62 +

63 +// <AvatarImage userId={17} width={200} height={200} />

64 +```

65 +

66 +Properties that are specified directly on the target component instance (such as `src` and `userId` in the above example) will not be overwritten by `transferPropsTo`.

67 +

68 +> Note:

69 +>

70 +> Use `transferPropsTo` with caution; it encourages tight coupling and makes it easy to accidentally introduce implicit dependencies between components. When in doubt, it's safer to explicitly copy the properties that you need onto the child component.

71 +

72 +

73 +### setState

74 +

75 +```javascript

76 +setState(object nextState[, function callback])

77 +```

78 +

79 +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.

80 +

81 +> Notes:

82 +>

83 +> *NEVER* mutate `this.state` directly, as calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.

84 +>

85 +> `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.

86 +>

87 +> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.

88 +

89 +

90 +### replaceState

91 +

92 +```javascript

93 +replaceState(object nextState[, function callback])

94 +```

95 +

96 +Like `setState()` but deletes any pre-existing state keys that are not in nextState.

97 +

98 +

99 +### forceUpdate()

100 +

101 +```javascript

102 +forceUpdate([function callback])

103 +```

104 +

105 +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()` by calling `forceUpdate()`. You'll also need to call `forceUpdate()` if you mutate `this.state` directly.

106 +

107 +Calling `forceUpdate()` will cause `render()` to be called on the component and its children, but React will still only update the DOM if the markup changes.

108 +

109 +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.

docs/docs/ref-03-component-specs.md new

+176

@@ -0,0 +1,176 @@

1 +---

2 +id: component-specs

3 +title: Component Specs and Lifecycle

4 +layout: docs

5 +permalink: component-specs.html

6 +prev: component-api.html

7 +next: tags-and-attributes.html

8 +---

9 +

10 +## Component Specifications

11 +

12 +When creating a component class by invoking `React.createClass()`, you should provide a specification object that contains a `render` method and can optionally contain other lifecycle methods described here.

13 +

14 +

15 +### render

16 +

17 +```javascript

18 +ReactComponent render()

19 +```

20 +

21 +The `render()` method is required.

22 +

23 +When called, it should examine `this.props` and `this.state` and return a single child component. This child component can be either a native DOM component (such as `<div>`) or another composite component that you've defined yourself.

24 +

25 +The `render()` function should be *pure*, meaning that it does not modify component state, it returns the same result each time it's invoked, and it does not read from or write to the DOM or otherwise interact with the browser (e.g., by using `setTimeout`). If you need to interact with the browser, perform your work in `componentDidMount()` or the other lifecycle methods instead. Keeping `render()` pure makes server rendering more practical and makes components easier to think about.

26 +

27 +

28 +### getInitialState

29 +

30 +```javascript

31 +object getInitialState()

32 +```

33 +

34 +Invoked once when the component is mounted. The return value will be used as the initial value of `this.state`.

35 +

36 +

37 +### getDefaultProps

38 +

39 +```javascript

40 +object getDefaultProps()

41 +```

42 +

43 +Invoked once when the component is mounted. Values in the mapping will be set on `this.props` if that prop is not specified by the parent component (i.e. using an `in` check).

44 +

45 +This method is invoked before `getInitialState` and therefore cannot rely on `this.state` or use `this.setState`.

46 +

47 +

48 +### propTypes

49 +

50 +```javascript

51 +object propTypes

52 +```

53 +

54 +The `propTypes` object allows you to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](reusable-components.html).

55 +

56 +

57 +

58 +

59 +### mixins

60 +

61 +```javascript

62 +array mixins

63 +```

64 +

65 +The `mixins` array allows you to use mixins to share behavior among multiple components. For more information about mixins, see [Reusable Components](reusable-components.html).

66 +

67 +

68 +

69 +

70 +## Lifecycle Methods

71 +

72 +Various methods are executed at specific points in a component's lifecycle.

73 +

74 +

75 +### Mounting: componentWillMount

76 +

77 +```javascript

78 +componentWillMount()

79 +```

80 +

81 +Invoked immediately before rendering occurs. If you call `setState` within this method, `render()` will see the updated state and will be executed only once despite the state change.

82 +

83 +

84 +### Mounting: componentDidMount

85 +

86 +```javascript

87 +componentDidMount(DOMElement rootNode)

88 +```

89 +

90 +Invoked immediately after rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via the `rootNode` argument or by calling `this.getDOMNode()`.

91 +

92 +If you want to integrate with other JavaScript frameworks, set timers using `setTimeout` or `setInterval`, or send AJAX requests, perform those operations in this method.

93 +

94 +

95 +### Updating: componentWillReceiveProps

96 +

97 +```javascript

98 +componentWillReceiveProps(object nextProps)

99 +```

100 +

101 +Invoked when a component is receiving new props. This method is not called for the initial render.

102 +

103 +Use this as an opportunity to react to a prop transition before `render()` is called by updating the state using `this.setState()`. The old props can be accessed via `this.props`. Calling `this.setState()` within this function will not trigger an additional render.

104 +

105 +```javascript

106 +componentWillReceiveProps: function(nextProps) {

107 + this.setState({

108 + likesIncreasing: nextProps.likeCount > this.props.likeCount

109 + });

110 +}

111 +```

112 +

113 +> Note:

114 +>

115 +> There is no analogous method `componentWillReceiveState`. An incoming prop transition may cause a state change, but the opposite is not true. If you need to perform operations in response to a state change, use `componentWillUpdate`.

116 +

117 +

118 +### Updating: shouldComponentUpdate

119 +

120 +```javascript

121 +boolean shouldComponentUpdate(object nextProps, object nextState)

122 +```

123 +

124 +Invoked before rendering when new props or state are being received. This method is not called for the initial render or when `forceUpdate` is used.

125 +

126 +Use this as an opportunity to `return false` when you're certain that the

127 +transition to the new props and state will not require a component update.

128 +

129 +```javascript

130 +shouldComponentUpdate: function(nextProps, nextState) {

131 + return !equal(nextProps, this.props) || !equal(nextState, this.state);

132 +}

133 +```

134 +

135 +If `shouldComponentUpdate` returns false, then `render()` will be completely skipped until the next state change. (In addition, `componentWillUpdate` and `componentDidUpdate` will not be called.)

136 +

137 +By default, `shouldComponentUpdate` always returns true to prevent subtle bugs when `state` is mutated in place, but if you are careful to always treat `state` as immutable and to read only from `props` and `state` in `render()` then you can override `shouldComponentUpdate` with an implementation that compares the old props and state to their replacements.

138 +

139 +If performance is a bottleneck, especially with dozens or hundreds of components, use `shouldComponentUpdate` to speed up your app.

140 +

141 +

142 +### Updating: componentWillUpdate

143 +

144 +```javascript

145 +componentWillUpdate(object nextProps, object nextState)

146 +```

147 +

148 +Invoked immediately before rendering when new props or state are being received. This method is not called for the initial render.

149 +

150 +Use this as an opportunity to perform preparation before an update occurs.

151 +

152 +> Note:

153 +>

154 +> You *cannot* use `this.setState()` in this method. If you need to update state in response to a prop change, use `componentWillReceiveProps` instead.

155 +

156 +

157 +### Updating: componentDidUpdate

158 +

159 +```javascript

160 +componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)

161 +```

162 +

163 +Invoked immediately after updating occurs. This method is not called for the initial render.

164 +

165 +Use this as an opportunity to operate on the DOM when the component has been updated.

166 +

167 +

168 +### Unmounting: componentWillUnmount

169 +

170 +```javascript

171 +componentWillUnmount()

172 +```

173 +

174 +Invoked immediately before a component is unmounted from the DOM.

175 +

176 +Perform any necessary cleanup in this method, such as invalidating timers or cleaning up any DOM elements that were created in `componentDidMount`.

docs/docs/ref-04-tags-and-attributes.md new

+65

@@ -0,0 +1,65 @@

1 +---

2 +id: tags-and-attributes

3 +title: Tags and Attributes

4 +layout: docs

5 +permalink: tags-and-attributes.html

6 +prev: component-specs.html

7 +next: events.html

8 +---

9 +

10 +## Supported Tags

11 +

12 +React attempts to support all common elements. If you need an element that isn't listed here, please file an issue.

13 +

14 +The following elements are supported:

15 +

16 +

17 +### HTML Elements

18 +

19 +```

20 +a abbr address area article aside audio b base bdi bdo big blockquote body br

21 +button canvas caption cite code col colgroup data datalist dd del details dfn

22 +div dl dt em embed fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6

23 +head header hr html i iframe img input ins kbd keygen label legend li link

24 +main map mark menu menuitem meta meter nav noscript object ol optgroup option

25 +output p param pre progress q rp rt ruby s samp script section select small

26 +source span strong style sub summary sup table tbody td textarea tfoot th

27 +thead time title tr track u ul var video wbr

28 +```

29 +

30 +### SVG elements

31 +

32 +```

33 +circle g line path polyline rect svg text

34 +```

35 +

36 +

37 +## Supported Attributes

38 +

39 +React supports all `data-*` and `aria-*` attributes as well as every attribute

40 +in the following lists. Note that all attributes are camel-cased and the attributes `class` and `for` are `className` and `htmlFor`, respectively, to match the DOM API specification.

41 +

42 +For a list of events, see [Supported Events](events.html).

43 +

44 +### HTML Attributes

45 +

46 +```

47 +accessKey accept action ajaxify allowFullScreen allowTransparency alt

48 +autoComplete autoFocus autoPlay cellPadding cellSpacing charSet checked

49 +className colSpan content contentEditable contextMenu controls data dateTime

50 +dir disabled draggable encType form frameBorder height hidden href htmlFor

51 +httpEquiv icon id label lang list max maxLength method min multiple name

52 +pattern poster preload placeholder radioGroup rel readOnly required role

53 +rowSpan scrollLeft scrollTop selected size spellCheck src step style tabIndex

54 +target title type value width wmode

55 +```

56 +

57 +In addition, the non-standard `autoCapitalize` attribute is supported for Mobile Safari.

58 +

59 +### SVG Attributes

60 +

61 +```

62 +cx cy d fill fx fy points r stroke strokeLinecap strokeWidth transform x x1 x2

63 +version viewBox y y1 y2 spreadMethod offset stopColor stopOpacity

64 +gradientUnits gradientTransform

65 +```

docs/docs/ref-05-events.md new

+205

@@ -0,0 +1,205 @@

1 +---

2 +id: events

3 +title: Event System

4 +layout: docs

5 +permalink: events.html

6 +prev: tags-and-attributes.html

7 +next: dom-differences.html

8 +---

9 +

10 +## SyntheticEvent

11 +

12 +Your event handlers will be passed instances of `SyntheticEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event, including `stopPropagation()` and `preventDefault()`, except the events work identically across all browsers.

13 +

14 +If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it. Every `SyntheticEvent` object has the following attributes:

15 +

16 +```javascript

17 +boolean bubbles

18 +boolean cancelable

19 +DOMEventTarget currentTarget

20 +boolean defaultPrevented

21 +Number eventPhase

22 +boolean isTrusted

23 +DOMEvent nativeEvent

24 +void preventDefault()

25 +void stopPropagation()

26 +DOMEventTarget target

27 +Date timeStamp

28 +String type

29 +```

30 +

31 +

32 +## Supported Events

33 +

34 +React normalizes events so that they have consistent properties across

35 +different browsers.

36 +

37 +

38 +### Clipboard Events

39 +

40 +Event names:

41 +

42 +```

43 +onCopy onCut onPaste

44 +```

45 +

46 +Properties:

47 +

48 +```javascript

49 +DOMDataTransfer clipboardData

50 +```

51 +

52 +

53 +### Keyboard Events

54 +

55 +Event names:

56 +

57 +```

58 +onKeyDown onKeyPress onKeyUp

59 +```

60 +

61 +Properties:

62 +

63 +```javascript

64 +boolean altKey

65 +String char

66 +boolean ctrlKey

67 +String key

68 +String locale

69 +Number location

70 +boolean metaKey

71 +boolean repeat

72 +boolean shiftKey

73 +```

74 +

75 +

76 +### Focus Events

77 +

78 +Event names:

79 +

80 +```

81 +onFocus onBlur

82 +```

83 +

84 +Properties:

85 +

86 +```javascript

87 +DOMEventTarget relatedTarget

88 +```

89 +

90 +

91 +### Form Events

92 +

93 +Event names:

94 +

95 +```

96 +onChange onInput onSubmit

97 +```

98 +

99 +For more information about the onChange event, see [Forms](forms.html).

100 +

101 +

102 +### Mouse Events

103 +

104 +Event names:

105 +

106 +```

107 +onClick onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave

108 +onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave

109 +onMouseMove onMouseUp

110 +```

111 +

112 +Properties:

113 +

114 +```javascript

115 +boolean altKey

116 +Number button

117 +Number buttons

118 +Number clientX

119 +Number clientY

120 +boolean ctrlKey

121 +boolean metaKey

122 +Number pageX

123 +Number pageY

124 +DOMEventTarget relatedTarget

125 +Number screenX

126 +Number screenY

127 +boolean shiftKey

128 +```

129 +

130 +

131 +### Mutation Events

132 +

133 +Event names:

134 +

135 +```

136 +onDOMCharacterDataModified

137 +```

138 +

139 +Properties:

140 +

141 +```javascript

142 +Number attrChange

143 +String attrName

144 +String newValue

145 +String prevValue

146 +Node relatedNode

147 +```

148 +

149 +

150 +### Touch events

151 +

152 +To enable touch events, call `React.initializeTouchEvents(true)` before

153 +rendering any component.

154 +

155 +Event names:

156 +

157 +```

158 +onTouchCancel onTouchEnd onTouchMove onTouchStart

159 +```

160 +

161 +Properties:

162 +

163 +```javascript

164 +boolean altKey

165 +DOMTouchList changedTouches

166 +boolean ctrlKey

167 +boolean metaKey

168 +boolean shiftKey

169 +DOMTouchList targetTouches

170 +DOMTouchList touches

171 +```

172 +

173 +

174 +### UI Events

175 +

176 +Event names:

177 +

178 +```

179 +onScroll

180 +```

181 +

182 +Properties:

183 +

184 +```javascript

185 +Number detail

186 +DOMAbstractView view

187 +```

188 +

189 +

190 +### Wheel Events

191 +

192 +Event names:

193 +

194 +```

195 +onWheel

196 +```

197 +

198 +Properties:

199 +

200 +```javascript

201 +Number deltaX

202 +Number deltaMode

203 +Number deltaY

204 +Number deltaZ

205 +```

docs/docs/ref-06-dom-differences.md new

+14

@@ -0,0 +1,14 @@

1 +---

2 +id: dom-differences

3 +title: DOM Differences

4 +layout: docs

5 +permalink: dom-differences.html

6 +prev: events.html

7 +---

8 +

9 +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.

10 +

11 +* 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.

12 +* The `style` attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM `style` JavaScript property, is more efficient, and prevents XSS security holes.

13 +* All event objects conform to the W3C spec, and all events (including submit) bubble correctly per the W3C spec. See [Event System](events.html) for more details.

14 +* The `onChange` event 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. See [Forms](forms.html) for more details.

docs/docs/tutorial.md

+1 -1

@@ -687,4 +687,4 @@ var CommentBox = React.createClass({

687

688 ### Congrats!

689

690 -You have just built a comment box in a few simple steps. Learn more about [why to use React](why-react.html), or dive into the [API reference](reference.html) and start hacking! Good luck!

690 +You have just built a comment box in a few simple steps. Learn more about [why to use React](why-react.html), or dive into the [API reference](core-api.html) and start hacking! Good luck!

src/event/synthetic/SyntheticTouchEvent.js

+1 -1

@@ -23,7 +23,7 @@ var SyntheticUIEvent = require('SyntheticUIEvent');

24 /**

25 * @interface TouchEvent

26 - * @see http://www.w3.org/TR/DOM-Level-3-Events/

26 + * @see http://www.w3.org/TR/touch-events/

27 */

28 var TouchEventInterface = {

29 touches: null,