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

The library for web and native user interfaces.

delete old docs

petehunt committed Jul 14, 2013 at 17:57 UTC d7cf1c509b8c63b914ee69b4887eb6115893938a
11 files changed -1274
docs/docs/advanced-components.md deleted
-119
@@ -1,119 +0,0 @@
1 ----
2 -id: docs-advanced-components
3 -title: Advanced Components
4 -description: How to build advanced composite components.
5 -layout: docs
6 -prev: event-handling.html
7 -next: mixins.html
8 ----
9 -
10 -Composite components extend a `ReactCompositeComponent` base class that provides
11 -a very powerful API that makes React flexible and able to easily work with other
12 -libraries and frameworks.
13 -
14 -## Lifecycle Methods
15 -
16 -Composite components can optionally implement lifecycle methods that are invoked
17 -at various stages in the [component lifecycle](component-lifecycle.html) that
18 -each have unique guarantees.
19 -
20 -### Mounting
21 -
22 - - `getInitialState(): object` is invoked before a component is mounted.
23 - Stateful components should implement this and return the initial state data.
24 - - `componentWillMount()` is invoked immediately before mounting occurs.
25 - - `componentDidMount(DOMElement rootNode)` is invoked immediately after
26 - mounting occurs. Initialization that requires DOM nodes should go here.
27 -
28 -### Updating
29 -
30 - - `componentWillReceiveProps(object nextProps)` is invoked when a mounted
31 - component receives new props. This method should be used to compare
32 - `this.props` and `nextProps` to perform state transitions using
33 - `this.setState()`.
34 - - `shouldComponentUpdate(object nextProps, object nextState): boolean` is
35 - invoked when a component decides whether any changes warrant an update to the
36 - DOM. Implement this as an optimization to compare `this.props` with
37 - `nextProps` and `this.state` with `nextState` and return false if React
38 - should skip updating.
39 - - `componentWillUpdate(object nextProps, object nextState)` is invoked
40 - immediately before updating occurs. You cannot call `this.setState()` here.
41 - - `componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)`
42 - is invoked immediately after updating occurs.
43 -
44 -### Unmounting
45 -
46 - - `componentWillUnmount()` is invoked immediately before a component is
47 - unmounted and destroyed. Cleanup should go here.
48 -
49 -## Mounted Methods
50 -
51 -_Mounted_ composite components also support the following methods:
52 -
53 - - `getDOMNode(): DOMElement` can be invoked on any mounted component in order
54 - to obtain a reference to its rendered DOM node.
55 - - `forceUpdate()` can be invoked on any mounted component when you know that
56 - some deeper aspect of the component's state has changed without using
57 - `this.setState()`.
58 -
59 -> Note:
60 ->
61 -> The `DOMElement rootNode` argument of `componentDidMount()` and
62 -> `componentDidUpdate()` is a convenience. The same node can be obtained by
63 -> calling `this.getDOMNode()`.
64 -
65 -## Component Refs
66 -
67 -A common use case of event callbacks or the lifecycle methods is to operate on a
68 -component returned by `render()`. For example, consider a search component that
69 -should auto-focus the input once mounted:
70 -
71 -```javascript
72 -var SearchForm = React.createClass({
73 - render: function() {
74 - return (
75 - <form action={this.props.action}>
76 - <input type="search" placeholder="Search..." />
77 - </form>
78 - );
79 - },
80 - componentDidMount: function(rootNode) {
81 - var searchInput = rootNode.firstChild;
82 - searchInput.focus();
83 - }
84 -});
85 -```
86 -
87 -Although this implementation works, it is fragile because `componentDidMount()`
88 -now relies on `render()` returning a particular DOM structure.
89 -
90 -React provides a better way for composite components to reference components
91 -that it constructs in its `render()` method through the use of refs. A component
92 -can assign a `ref` to any component it constructs. This will create a reference
93 -to those components on `this.refs`. For example:
94 -
95 -```javascript{5,10}
96 -var SearchForm = React.createClass({
97 - render: function() {
98 - return (
99 - <form action={this.props.action}>
100 - <input type="search" placeholder="Search..." ref="searchInput" />
101 - </form>
102 - );
103 - },
104 - componentDidMount: function(rootNode) {
105 - var searchInput = this.refs.searchInput.getDOMNode();
106 - searchInput.focus();
107 - }
108 -});
109 -```
110 -
111 -In this example, `this.refs.searchInput` will reference the `<input>` component
112 -and is available in most lifecycle methods and event callbacks. We obtain a
113 -reference to the `<input>`'s DOM node using `getDOMNode()`.
114 -
115 -> Note:
116 ->
117 -> If you want to preserve compatibility with Google Closure Compiler's
118 -> property crushing in `ADVANCED_OPTIMIZATIONS` mode, make sure to use string
119 -> literals with `this.refs`.
docs/docs/api.md deleted
-153
@@ -1,153 +0,0 @@
1 ----
2 -id: docs-api
3 -title: React API
4 -layout: docs
5 -prev: mixins.html
6 -next: jsx-is-not-html.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 -#### React.DOM
14 -
15 -`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.
16 -
17 -#### React.initializeTouchEvents
18 -
19 -```javascript
20 -initializeTouchEvents(boolean shouldUseTouch)
21 -```
22 -
23 -Configure React's event system to handle touch events on mobile devices.
24 -
25 -#### React.autoBind
26 -
27 -```javascript
28 -function autoBind(function method)
29 -```
30 -
31 -Marks the provided function to be automatically bound to each React component instance created. This allows React components to define automatically bound methods and ensure that when called they will always reference their current instance.
32 -
33 -Example:
34 -
35 -```javascript
36 -React.createClass({
37 - click: React.autoBind(function(evt) {
38 - this.setState({jumping: true});
39 - }),
40 - render: function() {
41 - // Look: no bind!
42 - return <a onClick={this.click}>Jump</a>;
43 - }
44 -});
45 -```
46 -
47 -#### React.createClass
48 -
49 -```javascript
50 -function createClass(object specification)
51 -```
52 -
53 -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.
54 -
55 -#### React.renderComponent
56 -
57 -```javascript
58 -ReactComponent renderComponent(ReactComponent container, DOMElement mountPoint)
59 -```
60 -
61 -Renders a React component into the DOM in the supplied `container`.
62 -
63 -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.
64 -
65 -## AbstractEvent
66 -
67 -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.
68 -
69 -If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it.
70 -
71 -## ReactComponent
72 -
73 -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.
74 -
75 -#### getDOMNode
76 -
77 -```javascript
78 -DOMElement getDOMNode()
79 -```
80 -
81 -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.
82 -
83 -#### setProps
84 -
85 -```javascript
86 -setProps(object nextProps)
87 -```
88 -
89 -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.
90 -
91 -**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()`.
92 -
93 -#### replaceProps
94 -
95 -```javascript
96 -replaceProps(object nextProps)
97 -```
98 -
99 -Like `setProps()` but deletes any pre-existing props that are not in nextProps.
100 -
101 -#### transferPropsTo
102 -
103 -```javascript
104 -ReactComponent transferPropsTo(ReactComponent targetComponent)
105 -```
106 -
107 -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.
108 -
109 -#### setState
110 -
111 -```javascript
112 -setState(object nextState[, function callback])
113 -```
114 -
115 -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.
116 -
117 -**Note:** *NEVER* mutate `this.state` directly. As calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
118 -
119 -**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.
120 -
121 -**Note**: There is no guarantee of synchronous operation of calls to `setState` and calls may eventually be batched for performance gains.
122 -
123 -#### replaceState
124 -
125 -```javascript
126 -replaceState(object nextState)
127 -```
128 -
129 -Like `setState()` but deletes any pre-existing state keys that are not in nextState.
130 -
131 -#### forceUpdate()
132 -
133 -```javascript
134 -forceUpdate()
135 -```
136 -
137 -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.
138 -
139 -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.
140 -
141 -```javascript
142 -object getInitialState()
143 -componentWillMount()
144 -componentDidMount(DOMElement domNode)
145 -componentWillReceiveProps(object nextProps)
146 -boolean shouldComponentUpdate(object nextProps, object nextState)
147 -componentWillUpdate(object nextProps, object nextState)
148 -ReactComponent render()
149 -componentDidUpdate(object prevProps, object prevState, DOMElement domNode)
150 -componentWillUnmount()
151 -```
152 -
153 -See the [advanced components](advanced-components.html) documentation for more details on these lifecycle methods.
docs/docs/common-questions.md deleted
-29
@@ -1,29 +0,0 @@
1 ----
2 -id: docs-common-questions
3 -title: Common Questions
4 -layout: docs
5 -prev: tutorial.html
6 -next: syntax.html
7 ----
8 -
9 -### What browsers does React support?
10 -
11 -React supports the latest two Chrome, Firefox, Safari, and Internet Explorer versions. React can work with Internet Explorer 8 with polyfills.
12 -
13 -### How do I get React to support Internet Explorer 8?
14 -
15 -React requires ES5 JavaScript shims to run in Internet Explorer 8. Include the [ES5 Shims and shams](https://github.com/kriskowal/es5-shim)
16 -and [console-polyfill)(https://github.com/paulmillr/console-polyfill/) to implement these shims.
17 -
18 -### Who uses React?
19 -
20 -The [Instagram](http://instagram.com/) website is built entirely in React. The [Facebook](https://www.facebook.com/) website is also increasingly using React, including the common commenting plugin across the site.
21 -
22 -### I don't get it. React is confusing!
23 -
24 -[This blog post by a member of the React team](http://www.quora.com/Pete-Hunt/Posts/React-Under-the-Hood) talks about some of the reasons
25 -why React is designed the way that it is.
26 -
27 -### Can I integrate with other JavaScript libraries?
28 -
29 -Absolutely! In fact, we encourage it! See [our GitHub repo](http://github.com/facebook/react/) for a [TodoMVC example using Backbone](https://github.com/facebook/react/tree/master/examples/todomvc-backbone) and a [jQuery + Bootstrap modal demo](https://github.com/facebook/react/tree/master/examples/jquery-bootstrap).
docs/docs/component-basics.md deleted
-73
@@ -1,73 +0,0 @@
1 ----
2 -id: docs-component-basics
3 -title: Component Basics
4 -description: What are components?
5 -layout: docs
6 -next: component-data.html
7 -prev: syntax.html
8 ----
9 -
10 -_Components_ are the basic units of composition in React. Components encapsulate
11 -the logic necessary to take input parameters and render markup. Components can
12 -be rendered into an existing DOM element on the page by using
13 -`React.renderComponent`:
14 -
15 -```javascript
16 -// Replaces everything in `document.body` with <div>Hello, world!</div>;
17 -React.renderComponent(<div>Hello, world!</div>, document.body);
18 -```
19 -
20 -Keep in mind that `<div>` is **not** a DOM element! Keep reading...
21 -
22 -## Types of Components
23 -
24 -There are two types of components:
25 -
26 - - **Composite Components**
27 - - **DOM Components**
28 -
29 -### Composite Components <small>such as `TodoApp` and `Typeahead`.</small>
30 -
31 -The majority of your React code will be implementing composite components.
32 -
33 -Composite components are higher-level components with custom rendering logic
34 -that may compose other composite components or DOM components.
35 -
36 -```javascript
37 -/** @jsx React.DOM */
38 -var LinkButton = React.createClass({
39 - render: function() {
40 - return <a className="btn" />;
41 - }
42 -});
43 -
44 -var myButton = <LinkButton />;
45 -```
46 -
47 -This example defines a `LinkButton` component class using `React.createClass()`,
48 -and its `render()` method composes the `<a>` DOM component.
49 -
50 -### DOM Components <small>such as `div` and `span`.</small>
51 -
52 -DOM components are the set of classes that correspond to browser DOM elements.
53 -They are defined in `React.DOM` and can be brought "into scope" by setting
54 -`@jsx React.DOM` in the docblock. See [JSX Syntax](syntax.html) for more
55 -details.
56 -
57 -Although `React.DOM` components look like browser DOM elements, they differ in a
58 -few ways:
59 -
60 -- All property names, including event handlers, are camelCased.
61 -- JavaScript identifiers should be used, namely `className` and `htmlFor`.
62 -- The `style` prop expects an object instead of a string. The object should map
63 - camelCased style properties to values, e.g. `{backgroundColor: '#fff'}`.
64 -
65 -Here is an example of a React link styled as a button with a click handler:
66 -
67 -```javascript
68 -/** @jsx React.DOM */
69 -var handleClick = function() {alert('Clicked!');};
70 -var inlineStyle = {textDecoration: 'none'};
71 -
72 -var myLink = <a className="btn" onClick={handleClick} style={inlineStyle} />;
73 -```
docs/docs/component-data.md deleted
-145
@@ -1,145 +0,0 @@
1 ----
2 -id: docs-component-data
3 -title: Component Data
4 -description: How is data passed into a component?
5 -layout: docs
6 -prev: component-basics.html
7 -next: component-lifecycle.html
8 ----
9 -
10 -## Props
11 -
12 -Components use data to determine what should be rendered. For example:
13 -
14 -```javascript
15 -var LikeLink = React.createClass({
16 - render: function() {
17 - var text = this.props.liked ? 'Liked' : 'Like';
18 - return <a>{text}</a>;
19 - }
20 -});
21 -var myLikeLink = <LikeLink liked={false} />;
22 -```
23 -
24 -In this example, `LikeLink` takes `liked` as boolean data. This type of data
25 -that is passed in is called a "prop". Examples of props on DOM components
26 -include `className` and `onClick`.
27 -
28 -Whenever a component's props change, its `render()` function will be
29 -re-evaluated and the DOM will be updated. React will ensure that the DOM is
30 -always kept up-to-date.
31 -
32 -## State
33 -
34 -Let's build a small `LikeApp` application that makes use of the `<LikeLink>`
35 -component from above. It should start off unliked and we should be able to like
36 -it by clicking the link:
37 -
38 -```javascript
39 -var LikeApp = React.createClass({
40 - render: function() {
41 - var isClicked = false;
42 - return <LikeLink liked={isClicked} onClick={this.handleClick.bind(this)} />;
43 - },
44 - handleClick: function() {
45 - // Somehow update `isClicked`.
46 - }
47 -});
48 -```
49 -
50 -This renders a `<LikeLink>` with a click listener. However, it is not clear how
51 -`handleClick` should update `isClicked` to true. `LikeApp` needs a way to store
52 -**state** about whether or not it has been clicked.
53 -
54 -### State vs. Props
55 -
56 -State is data that is managed _internally_ by a composite component. Like props,
57 -the `render()` function will be re-evaluated whenever state changes. Props and
58 -state differ in that:
59 -
60 - - Props are passed in from the creator.
61 - - State is private to and managed by the component.
62 -
63 -### Managing State
64 -
65 -Let's update our `LikeApp` component using state:
66 -
67 -```javascript{2-4,6,10}
68 -var LikeApp = React.createClass({
69 - getInitialState: function() {
70 - return {isClicked: false};
71 - },
72 - render: function() {
73 - var isClicked = this.state.isClicked;
74 - return <LikeLink liked={isClicked} onClick={this.handleClick.bind(this)} />;
75 - },
76 - handleClick: function() {
77 - this.setState({isClicked: true});
78 - }
79 -});
80 -```
81 -
82 -There's a lot going on here, so let's work our way from top to bottom:
83 -
84 - - `getInitialState()` describes what state data looks like when the component
85 - is created.
86 - - In `render()`, state data can be accessed via `this.state`.
87 - - When the link is clicked, we update state using `setState()`.
88 -
89 -Now when we click the link, the `<LikeLink>` will get updated, right? Wrong.
90 -
91 -## Transferring Props
92 -
93 -If you have been following carefully, you may have noticed that although we pass
94 -a click handler into `<LikeLink>` as a prop, `LikeLink` does not do anything
95 -with `this.props.onClick`! Let's fix that.
96 -
97 -```javascript{4}
98 -var LikeLink = React.createClass({
99 - render: function() {
100 - var text = this.props.liked ? 'Liked' : 'Like';
101 - return <a onClick={this.props.onClick}>{text}</a>;
102 - }
103 -});
104 -```
105 -
106 -Although this works, realize that this would quickly become tedious if we wanted
107 -to also transfer `href`, `title`, `target`, and other events from `this` to the
108 -rendered `<a>`. React provides a convenience method, `transferPropsTo()`, for
109 -transferring props:
110 -
111 -```javascript{4}
112 -var LikeLink = React.createClass({
113 - render: function() {
114 - var text = this.props.liked ? 'Liked' : 'Like';
115 - return this.transferPropsTo(<a>{text}</a>);
116 - }
117 -});
118 -```
119 -
120 -This will transfer all props from `this` to the specified component (including
121 -`onClick`).
122 -
123 -## Summary
124 -
125 -Now we are done. `LikeApp` renders an unliked link which, when clicked, will:
126 -
127 -1. Update the internal state of `LikeApp`.
128 -2. Change the props passed into `LikeLink`.
129 -3. Change the return value of `render()`.
130 -4. Trigger an update to the DOM.
131 -
132 -It's worth noting that React will handle new return values of `render()` by
133 -making the minimal set of mutations necessary to bring the DOM up-to-date. In
134 -this case, only the `textContent` of the rendered link will be mutated.
135 -
136 -In summary:
137 -
138 - - Props are passed in whereas state is managed internally by a component.
139 - - Never mutate `this.props` or `this.state`. You should pass props into other
140 - components and mutate state using `setState()`.
141 - - State is private. Never read `state` or call `setState()` on
142 - anything but `this`.
143 - - Whenever props or state changes, `render()` will be re-evaluated and the DOM
144 - updated. Also, `render()` should not depend on anything besides `this.props`
145 - and `this.state`.
docs/docs/component-lifecycle.md deleted
-85
@@ -1,85 +0,0 @@
1 ----
2 -id: docs-component-lifecycle
3 -title: Component Lifecycle
4 -description: What happens when I render a React component?
5 -layout: docs
6 -prev: component-data.html
7 -next: event-handling.html
8 ----
9 -
10 -## Mounting
11 -
12 -[We have previously seen](component-basics.html) how to render components into
13 -existing DOM elements on the page:
14 -
15 -```javascript
16 -React.renderComponent(<div>Hello, world!</div>, document.body);
17 -```
18 -
19 -In this one simple line, we have accomplished the following:
20 -
21 - - A `<div>` (defined by `React.DOM.div`) component is instantiated.
22 - - The component is **mounted** into `document.body`.
23 -
24 -**Mounting** is the process of initializing a React component by creating its
25 -DOM nodes and inserting them into a supplied container node.
26 -
27 -At this point, the entire page consists of a single `<div>` with "Hello,
28 -world!".
29 -
30 -## Updating
31 -
32 -Let's add a second call to `React.renderComponent()` after three
33 -seconds:
34 -
35 -```javascript{2-4}
36 -React.renderComponent(<div>Hello, world!</div>, document.body);
37 -setTimeout(function() {
38 - React.renderComponent(<div>Goodbye, world.</div>, document.body);
39 -}, 3000);
40 -```
41 -
42 -The second call to `React.renderComponent()` will trigger the following:
43 -
44 - - The `<div>` component will check the new props to see if anything changed.
45 - - The set of changes are used to **update** the DOM node as necessary.
46 -
47 -**Updating** is the process of mutating the rendered DOM nodes and occurs
48 -whenever either props or state has changed. This ensures that the rendered DOM
49 -is consistent with the data.
50 -
51 -## Unmounting
52 -
53 -Let's add one final call to `React.renderComponent()` after another three
54 -seconds:
55 -
56 -```javascript{5-7}
57 -React.renderComponent(<div>Hello, world!</div>, document.body);
58 -setTimeout(function() {
59 - React.renderComponent(<div>Goodbye, world.</div>, document.body);
60 -}, 3000);
61 -setTimeout(function() {
62 - React.renderComponent(<img src="/images/fin.png" />, document.body);
63 -}, 6000);
64 -```
65 -
66 -The third call to `React.renderComponent()` will trigger the following:
67 -
68 - - An `<img>` (defined by `React.DOM.img`) component is instantiated.
69 - - React will compare the `<div>` component with the `<img>` component.
70 - - Since the component class is different, the `<div>` component will be
71 - **unmounted**.
72 - - The `<img>` component will then be mounted into `document.body`.
73 -
74 -**Unmounting** is the process of releasing resources that have been allocated by
75 -a component. This allows user interfaces built with React to live long without
76 -memory leaks.
77 -
78 -Components can also be unmounted using
79 -`React.unmountAndReleaseReactRootNode()`:
80 -
81 -```javascript
82 -React.unmountAndReleaseReactRootNode(document.body);
83 -```
84 -
85 -This will unmount any components mounted immediately within `document.body`.
docs/docs/event-handling.md deleted
-224
@@ -1,224 +0,0 @@
1 ----
2 -id: docs-event-handling
3 -title: Event Handling
4 -description: How do events work with React components?
5 -layout: docs
6 -prev: component-lifecycle.html
7 -next: advanced-components.html
8 ----
9 -
10 -Events in React work the way they do with HTML, except the event names are
11 -camelCased.
12 -
13 -```javascript
14 -var Clicker = React.createClass({
15 - render: function() {
16 - return <span onClick={this.handleClick}>Click me!</span>;
17 - },
18 - handleClick: function(event) {
19 - alert('You clicked me!');
20 - }
21 -});
22 -```
23 -
24 -When `<Clicker>` is clicked, the `handleClick()` function will get fired. Under
25 -the hood, React uses top-level event delegation to achieve high performance.
26 -
27 -## Automatically Binding Callbacks
28 -
29 -Just like any callback in JavaScript, if you want to refer to the component as
30 -`this` from the callback, you need to bind the callback to the component:
31 -
32 -```javascript{3}
33 -var Clicker = React.createClass({
34 - render: function() {
35 - var handleClick = this.handleClick.bind(this);
36 - return <span onClick={handleClick}>Click me!</span>;
37 - },
38 - handleClick: function(event) {
39 - alert(this.ALERT_MESSAGE);
40 - },
41 - ALERT_MESSAGE: 'You clicked me!'
42 -});
43 -```
44 -
45 -React provides a convenient and _efficient_ way to bind methods using
46 -`React.autoBind()`:
47 -
48 -```javascript{3,5-7}
49 -var Clicker = React.createClass({
50 - render: function() {
51 - return <span onClick={this.handleClick}>Click me!</span>;
52 - },
53 - handleClick: React.autoBind(function(event) {
54 - alert(this.ALERT_MESSAGE);
55 - }),
56 - ALERT_MESSAGE: 'You clicked me!'
57 -});
58 -```
59 -
60 -> Note:
61 ->
62 -> Binding a function allocates memory to create a new bound function. Since
63 -> `render()` may be invoked many times, it is a bad place to bind functions.
64 -> `React.autoBind()` sidesteps this issue by only binding once at instantiation
65 -> time.
66 -
67 -## DOM Events
68 -
69 -React uses [top-level event delegation](http://davidwalsh.name/event-delegate)
70 -to achieve high performance when implementing DOM events. For each type of DOM
71 -event, React adds a single top-level listener and determines which event
72 -handlers to execute by simulating event capturing and bubbling.
73 -
74 -DOM event handlers are called with a normalized `AbstractEvent` object that has
75 -cross-browser compatible implementations of `stopPropagation` and
76 -`preventDefault()`. If you need access to the raw browser event, you can use the
77 -`nativeEvent` property.
78 -
79 -> Note:
80 ->
81 -> The `AbstractEvent` object is JSON serializable so that React applications can
82 -> be executed inside web workers.
83 -
84 -### Touch Events
85 -
86 -If you want to use touch events, you must configure React's event system to
87 -initialize them:
88 -
89 -```javascript
90 -// Invoke before calling `React.renderComponent()`.
91 -React.initializeTouchEvents(true);
92 -```
93 -
94 -## Custom Events
95 -
96 -Notice that event listeners are attached by simply passing them into components
97 -as props. For DOM components, events are handled using top-level event
98 -delegation. For composite components, event handling is up to the component's
99 -implementation.
100 -
101 -Here is an example of a toggle link that fires a custom `onToggle` event:
102 -
103 -```javascript
104 -var ToggleLink = React.createClass({
105 - getInitialState: function() {
106 - return {isEnabled: false};
107 - },
108 - render: function() {
109 - return <a onClick={this.handleClick}>Toggle</a>;
110 - },
111 - handleClick: React.autoBind(function() {
112 - var willEnable = !this.state.isEnabled;
113 - if (this.props.onToggle) {
114 - this.props.onToggle(willEnable)
115 - }
116 - this.setState({isEnabled: willEnable});
117 - })
118 -});
119 -
120 -var handleToggle = function(enabled) {
121 - alert(enabled ? 'Enabled.' : 'Disabled.');
122 -};
123 -var myToggleLink = <ToggleLink onToggle={handleToggle} />;
124 -```
125 -
126 -### Common Patterns
127 -
128 -With React your event handlers should be quite small. Large event handlers may
129 -be symptomatic of code that should be moved into helpers or into `render()`.
130 -Here are some common usage patterns for event handlers.
131 -
132 -#### Updating State
133 -
134 -The most common thing to do in response to a user action is to call
135 -`this.setState()` to update the component's state, which will in turn trigger
136 -an update to the rendered component.
137 -
138 -#### Server Requests
139 -
140 -Many event handlers will issue a server request to read or write some data in
141 -response to an event. The response handler for the request will often call
142 -`this.setState()`.
143 -
144 -#### Invoke a Callback
145 -
146 -Your component will often be a small, reusable building block that does not know
147 -how to respond to a user action. In these situations, we delegate the
148 -responsibility to the owner by exposing a handler on `this.props`. This is what
149 -the `ToggleLink` example above is doing.
150 -
151 -#### Inter-component Communication
152 -
153 -A common scenario involves communicating to **Component A** that a user action
154 -has occurred on **Component B**. To solve this problem, a common parent to
155 -both components should listen for the event on **Component B**, update its
156 -internal state, and pass that data into **Component A**.
157 -
158 -For example, say we have two components: **Clicker**, a component that fires an
159 -`onCountChange` custom event, and **ClickCountLabel**, a component that displays
160 -the number of clicks that have happened:
161 -
162 -```javascript
163 -var Clicker = React.createClass({
164 - getInitialState: function() {
165 - return {count: 0};
166 - },
167 - render: function() {
168 - return <span onClick={this.handleClick}>Click me!</span>;
169 - },
170 - handleClick: React.autoBind(function() {
171 - this.setState({count: this.state.count + 1});
172 - if (this.props.onCountChange) {
173 - this.props.onCountChange(this.state.count);
174 - }
175 - })
176 -});
177 -
178 -var ClickCountLabel = React.createClass({
179 - render: function() {
180 - return <p>You have clicked <strong>{this.props.count}</strong> times.</p>;
181 - }
182 -});
183 -
184 -var ClickApp = React.createClass({
185 - render: function() {
186 - var count = 0;
187 - return (
188 - <div>
189 - <Clicker onCountChange={this.handleCountChange} />
190 - <ClickCountLabel count={count} />
191 - </div>
192 - );
193 - },
194 - handleCountChange: React.autoBind(function(count) {
195 - // Somehow update `count`.
196 - })
197 -});
198 -```
199 -
200 -In order to communicate the click count from `Clicker` to `ClickCountLabel`, we
201 -modify `ClickApp` to maintain state that will be passed into `ClickCountLabel`:
202 -
203 -```javascript{2-4,6,15}
204 -var ClickApp = React.createClass({
205 - getInitialState: function() {
206 - return {count: 0};
207 - },
208 - render: function() {
209 - var count = this.state.count;
210 - return (
211 - <div>
212 - <Clicker onCountChange={this.handleCountChange} />
213 - <ClickCountLabel count={count} />
214 - </div>
215 - );
216 - },
217 - handleCountChange: React.autoBind(function(count) {
218 - this.setState({count: count});
219 - })
220 -});
221 -```
222 -
223 -Now when `Clicker` fires the `onCountChange` event, the `ClickCountLabel` will
224 -get updated!
docs/docs/getting-started.md deleted
-118
@@ -1,118 +0,0 @@
1 ----
2 -id: docs-getting-started
3 -title: Getting Started
4 -layout: docs
5 -next: tutorial.html
6 ----
7 -
8 -## JSFiddle
9 -
10 -The easiest way to start hacking on React is using the following JSFiddle Hello Worlds
11 -
12 - * **[React JSFiddle](http://jsfiddle.net/vjeux/kb3gN/)**
13 - * [React JSFiddle without JSX](http://jsfiddle.net/vjeux/VkebS/)
14 -
15 -## Starter Kit
16 -
17 -Download the starter kit to get started.
18 -
19 -<div class="buttons-unit downloads">
20 - <a href="/react/downloads/react-{{site.react_version}}.zip" class="button">
21 - Download Starter Kit {{site.react_version}}
22 - </a>
23 -</div>
24 -
25 -In the root directory of the starter kit, create a `helloworld.html` with the following contents.
26 -
27 -```html
28 -<!DOCTYPE html>
29 -<html>
30 - <head>
31 - <script src="build/react.min.js"></script>
32 - <script src="build/JSXTransformer.js"></script>
33 - </head>
34 - <body>
35 - <div id="example"></div>
36 - <script type="text/jsx">
37 - /** @jsx React.DOM */
38 - React.renderComponent(
39 - <h1>Hello, world!</h1>,
40 - document.getElementById('example')
41 - );
42 - </script>
43 - </body>
44 -</html>
45 -```
46 -
47 -The XML syntax inside of JavaScript is called JSX; check out the [JSX syntax](syntax.html) to learn more about it. In order to translate it to vanilla JavaScript we use `<script type="text/jsx">` and include `JSXTransformer.js` to actually perform the transformation in the browser.
48 -
49 -### Separate File
50 -
51 -Your React JSX file can live in a separate file. Create the following `src/helloworld.js`.
52 -
53 -```javascript
54 -/** @jsx React.DOM */
55 -React.renderComponent(
56 - <h1>Hello, world!</h1>,
57 - document.getElementById('example')
58 -);
59 -```
60 -Then reference it from `helloworld.html`:
61 -
62 -```html{10}
63 -<script type="text/jsx" src="src/helloworld.js"></script>
64 -```
65 -
66 -### Offline Transform
67 -
68 -First install the command-line tools (requires [npm](http://npmjs.org/)):
69 -
70 -```
71 -npm install -g react-tools
72 -```
73 -
74 -Then, translate your `src/helloworld.js` file to plain JavaScript:
75 -
76 -```
77 -jsx --watch src/ build/
78 -
79 -```
80 -
81 -The file `build/helloworld.js` is autogenerated whenever you make a change.
82 -
83 -```javascript{3}
84 -/** @jsx React.DOM */
85 -React.renderComponent(
86 - React.DOM.h1(null, 'Hello, world!'),
87 - document.getElementyById('example')
88 -);
89 -```
90 -
91 -> Note:
92 ->
93 -> The comment parser is very strict right now, in order for it to pick up the `@jsx` modifier, two conditions are required. The `@jsx` comment block must be the first comment on the file. The comment must start with `/**` (`/*` and `//` will not work). If the parser can't find the `@jsx` comment, it will output the file without transforming it.
94 -
95 -Update your HTML file as below:
96 -
97 -```html{6,10}
98 -<!DOCTYPE html>
99 -<html>
100 - <head>
101 - <title>Hello React!</title>
102 - <script src="build/react.min.js"></script>
103 - <!-- No need for JSXTransformer! -->
104 - </head>
105 - <body>
106 - <div id="example"></div>
107 - <script src="build/helloworld.js"></script>
108 - </body>
109 -</html>
110 -```
111 -
112 -## Want CommonJS?
113 -
114 -If you want to use React within a module system, [fork our repo](http://github.com/facebook/react), `npm install` and run `grunt`. A nice set of CommonJS modules will be generated. Our `jsx` build tool can be integrated into most packaging systems (not just CommonJS) quite easily.
115 -
116 -## Next Steps
117 -
118 -Check out [the tutorial](tutorial.html) and the other examples in the `/examples` directory to learn more. Good luck, and welcome!
docs/docs/jsx-is-not-html.md deleted
-95
@@ -1,95 +0,0 @@
1 ----
2 -id: docs-jsx-is-not-html
3 -title: JSX is not HTML
4 -description: Differences between JSX and HTML.
5 -layout: docs
6 -prev: api.html
7 ----
8 -
9 -JSX looks like HTML but there are some important differences you may run into.
10 -
11 -## Whitespace removal
12 -
13 -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 `{' '}`.
14 -
15 -```javascript
16 -<div>{this.props.name} {' '} {this.props.surname}</div>
17 -```
18 -
19 -Follow [Issue #65](https://github.com/facebook/react/issues/65) for discussion on this behavior.
20 -
21 -## HTML Entities
22 -
23 -You can insert HTML entities within literal text in JSX:
24 -
25 -```javascript
26 -<div>First &middot; Second</div>
27 -```
28 -
29 -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.
30 -
31 -```javascript
32 -// Bad: It displays "First &middot; Second"
33 -<div>{'First &middot; Second'}</div>
34 -```
35 -
36 -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.
37 -
38 -```javascript
39 -<div>{'First · Second'}</div>
40 -```
41 -
42 -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.
43 -
44 -```javascript
45 -<div>{'First \u00b7 Second'}</div>
46 -<div>{'First ' + String.fromCharCode(183) + ' Second'}</div>
47 -```
48 -
49 -You can use mixed arrays with strings and JSX elements.
50 -
51 -```javascript
52 -<div>{['First ', <span>&middot;</span>, ' Second']}</div>
53 -```
54 -
55 -As a last resort, you always have the ability to insert raw HTML.
56 -
57 -```javascript
58 -<div dangerouslySetInnerHTML={{'{{'}}__html: 'First &middot; Second'}} />
59 -```
60 -
61 -## Comments
62 -
63 -JSX supports both single-line and multi-line JavaScript comments within a tag declaration:
64 -
65 -```javascript
66 -<div // This is a single-line comment:
67 - /*
68 - And a multi-line
69 - comment
70 - */
71 -/>
72 -```
73 -
74 -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:
75 -
76 -```javascript
77 -// Note: This is not implemented yet!
78 -<div>
79 - {/* This is a comment */}
80 -</div>
81 -```
82 -
83 -## Custom HTML Attributes
84 -
85 -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-`.
86 -
87 -```javascript
88 -<div data-custom-attribute="foo" />
89 -```
90 -
91 -[Web Accessibility](http://www.w3.org/WAI/intro/aria) attributes starting with `aria-` will be rendered properly.
92 -
93 -```javascript
94 -<div aria-hidden={true} />
95 -```
docs/docs/mixins.md deleted
-65
@@ -1,65 +0,0 @@
1 ----
2 -id: docs-mixins
3 -title: Mixins
4 -layout: docs
5 -prev: advanced-components.html
6 -next: api.html
7 ----
8 -
9 -Mixins allow code to be shared between multiple React components. They are pretty similar to mixins
10 -in Python or traits in PHP. Let's look at a simple example:
11 -
12 -```javascript
13 -var MyMixin = {
14 - getMessage: function() {
15 - return 'hello world';
16 - }
17 -};
18 -
19 -var MyComponent = React.createClass({
20 - mixins: [MyMixin],
21 - render: function() {
22 - return <div>{this.getMessage()}</div>;
23 - }
24 -});
25 -```
26 -
27 -A class can use multiple mixins, but no two mixins can define the same method. Two mixins can, however,
28 -implement the same [lifecycle method](component-lifecycle.html). In this case, each implementation will be invoked one after another.
29 -
30 -The only exception is the `shouldComponentUpdate` lifecycle method. This method may only be implemented once
31 -(either by a mixin or by the component).
32 -
33 -```javascript
34 -var Mixin1 = {
35 - componentDidMount: function() {
36 - console.log('Mixin1.componentDidMount()');
37 - }
38 -};
39 -
40 -var Mixin2 = {
41 - componentDidMount: function() {
42 - console.log('Mixin2.componentDidMount()');
43 - }
44 -};
45 -
46 -
47 -var MyComponent = React.createClass({
48 - mixins: [Mixin1, Mixin2],
49 - render: function() {
50 - return <div>hello world</div>;
51 - }
52 -});
53 -```
54 -
55 -When `MyComponent` is mounted into the page, the following text will print to the console:
56 -
57 -```
58 -Mixin1.componentDidMount()
59 -Mixin2.componentDidMount()
60 -```
61 -
62 -## When should you use mixins?
63 -
64 -In general, add a mixin whenever you want a component to share some utility methods, public interface,
65 -or lifecycle behavior. Often it's appropriate to use them as you would use a superclass in another OOP language.
docs/docs/syntax.md deleted
-168
@@ -1,168 +0,0 @@
1 ----
2 -id: docs-syntax
3 -title: JSX Syntax
4 -description: Writing JavaScript with XML syntax.
5 -layout: docs
6 -prev: common-questions.html
7 -next: component-basics.html
8 ----
9 -
10 -JSX is a JavaScript XML syntax transform recommended (but not required) for use
11 -with React.
12 -
13 -## Why JSX?
14 -
15 -First of all, **don't use JSX if you don't like it!**
16 -
17 -React works out of the box without JSX. Simply construct your markup using the
18 -functions on `React.DOM`. For example, here's how to construct a simple link:
19 -
20 -```javascript
21 -var link = React.DOM.a({href: 'http://facebook.github.io/react'}, 'React');
22 -```
23 -
24 -We recommend using JSX for many reasons:
25 -
26 -- It's easier to visualize the structure of the DOM.
27 -- Designers are more comfortable making changes.
28 -- It's familiar for those who have used MXML or XAML.
29 -
30 -## The Transform
31 -
32 -JSX transforms XML-like syntax into native JavaScript. It turns XML elements and
33 -attributes into function calls and objects, respectively.
34 -
35 -```javascript
36 -var Nav;
37 -// Input (JSX):
38 -var app = <Nav color="blue" />;
39 -// Output (JS):
40 -var app = Nav({color:'blue'}, null);
41 -```
42 -
43 -Notice that in order to use `<Nav />`, the `Nav` variable must be in scope.
44 -
45 -JSX also allows specifying children using XML syntax:
46 -
47 -```javascript
48 -var Nav, Profile;
49 -// Input (JSX):
50 -var app = <Nav color="blue"><Profile>click</Profile></Nav>;
51 -// Output (JS):
52 -var app = Nav({color:'blue'}, Profile(null, 'click'));
53 -```
54 -
55 -Use the [JSX Compiler](/react/jsx-compiler.html) to try out JSX and see how it
56 -desugars into native JavaScript.
57 -
58 -If you want to use JSX, the [Getting Started](getting-started.html) guide shows
59 -how to setup compilation.
60 -
61 -> Note:
62 ->
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 -## React and JSX
67 -
68 -React and JSX are independent technologies, but JSX was primarily built with
69 -React in mind. The two valid uses of JSX are:
70 -
71 -- To construct instances of React DOM components (`React.DOM.*`).
72 -- To construct instances of composite components created with
73 - `React.createClass()`.
74 -
75 -**React DOM Components**
76 -
77 -To construct a `<div>` is to create a variable that refers to `React.DOM.div`.
78 -
79 -```javascript
80 -var div = React.DOM.div;
81 -var app = <div className="appClass">Hello, React!</div>;
82 -```
83 -
84 -**React Component Components**
85 -
86 -To construct an instance of a composite component, create a variable that
87 -references the class.
88 -
89 -```javascript
90 -var MyComponent = React.createClass({/*...*/});
91 -var app = <MyComponent someProperty={true} />;
92 -```
93 -
94 -See [Component Basics](component-basics.html) to learn more about components.
95 -
96 -> Note:
97 ->
98 -> Since JSX is JavaScript, identifiers such as `class` and `for` are discouraged
99 -> as XML attribute names. Instead, React DOM components expect attributes like
100 -> `className` and `htmlFor`, respectively.
101 -
102 -## DOM Convenience
103 -
104 -Having to define variables for every type of DOM element can get tedious
105 -(e.g. `var div, span, h1, h2, ...`). JSX provides a convenience to address this
106 -problem by allowing you to specify a variable in an `@jsx` docblock field. JSX
107 -will use that field to find DOM components.
108 -
109 -```javascript
110 -/**
111 - * @jsx React.DOM
112 - */
113 -var Nav;
114 -// Input (JSX):
115 -var tree = <Nav><span /></Nav>;
116 -// Output (JS):
117 -var tree = Nav(null, React.DOM.span(null, null));
118 -```
119 -
120 -> Remember:
121 ->
122 -> JSX simply transforms elements into function calls and has no notion of the
123 -> DOM. The docblock parameter is only a convenience to resolve the most commonly
124 -> used elements. In general, JSX has no notion of the DOM.
125 -
126 -## JavaScript Expressions
127 -
128 -#### Attribute Expressions
129 -
130 -To use a JavaScript expression as an attribute value, wrap the expression in a
131 -pair of curly braces (`{}`) instead of quotes (`""`).
132 -
133 -```javascript
134 -// Input (JSX):
135 -var person = <Person name={window.isLoggedIn ? window.name : ''} />;
136 -// Output (JS):
137 -var person = Person({name: window.isLoggedIn ? window.name : ''});
138 -```
139 -
140 -#### Child Expressions
141 -
142 -Likewise, JavaScript expressions may be used to express children:
143 -
144 -```javascript
145 -// Input (JSX):
146 -var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;
147 -// Output (JS):
148 -var content = Container(null, window.isLoggedIn ? Nav(null, null) : Login(null, null));
149 -```
150 -
151 -## Tooling
152 -
153 -Beyond the compilation step, JSX does not require any special tools.
154 -
155 -- Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
156 -- Linting provides accurate line numbers after compiling without sourcemaps.
157 -- Elements use standard scoping so linters can find usage of out-of-scope
158 - components.
159 -
160 -## Prior Work
161 -
162 -JSX is similar to several other JavaScript embedded XML language
163 -proposals/projects. Some of the features of JSX that distinguish it from similar
164 -efforts include:
165 -
166 -- JSX is a simple syntactic transform.
167 -- JSX neither provides nor requires a runtime library.
168 -- JSX does not alter or add to the semantics of JavaScript.