maxjhandsome
/
react
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cleanup some files, move tutorial

This commit is contained in:
petehunt 2013-07-14 18:35:59 -07:00
parent b20c2641d4
commit 6009934176
8 changed files with 123 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/docs/01-motivation.md
View File

@ -1,27 +0,0 @@
---
id: 01-motivation
title: Motivation / Why React?
layout: docs
next: 02-displaying-data.html
---
React is a JavaScript library for creating user interfaces by Facebook and Instagram. Many people choose to think of React as the **V** in **[MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)**.
We built React to solve one problem: **building large applications with data that changes over time**. To do this, React has two main ideas.
### Stay simple and declarative
React apps are easy to write. Simply express how the UI should look at any given point in time, and React will manage all UI updates for you when your underlying data changes.
It's just like writing a server-rendered web app: when the data changes, React conceptually hits the refresh button, except React is very fast and maintains the state of your UI. Because of this, React's API is very small and easy to understand.
### Build composable components
React is all about building reusable components. In fact, with React the *only* thing you do is build components. Since they're so encapsulated, components make code reuse, testing, and separation of concerns easy.
### Give it five minutes
React challenges a lot of conventional wisdom, and at first glance some of the ideas may seem crazy. We ask that you [give it five minutes](http://37signals.com/svn/posts/3124-give-it-five-minutes) while reading about React; engineers and designers have built thousands of components both inside and outside of Facebook and Instagram, and we hope you'll find it useful!
### Learn more
You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).

2
docs/docs/01-why-react.md
View File

@ -24,4 +24,4 @@ React challenges a lot of conventional wisdom, and at first glance some of the i
### Learn more
You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).
You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).

90
docs/docs/05-building-effective-reusable-components.md
View File

@ -1,90 +0,0 @@
---
id: 05-building-effective-reusable-components
title: Build reusable component libraries!
layout: docs
prev: 04-scaling-up.html
next: 06-forms.html
---
When designing interfaces, break down the common design elements (buttons, form fields, layout components, etc) into reusable components with well-defined interfaces. That way, the next time you need to build some UI you can write much less code, which means faster development time, less bugs, and less bytes down the wire.
### Prop validation
As your app grows it's helpful to ensure that your components are used correctly. We do this using `propTypes`.
** TODO zpao **
### Transferring props: a shortcut
A common type of React component is one that extends a basic HTML in a simple way. Often you'll want to copy any HTML attributes passed to your component to the underlying HTML element to save typing. React provides `transferPropsTo()` to do just this.
```javascript
/** @jsx React.DOM */
var CheckLink = React.createClass({
render: function() {
// transferPropsTo() will take any props pased to CheckLink
// and copy them to <a>
return this.transferPropsTo(<a>{'√ '}{this.props.children}</a>);
}
});
React.renderComponent(
<CheckLink href="javascript:alert('Hello, world!');">
Click here!
</CheckLink>,
document.getElementById('example')
);
```
### Mixins
Components are the best way to reuse code in React, but sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](http://en.wikipedia.org/wiki/Cross-cutting_concern). React provides `mixins` to solve this problem.
One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](./06-working-with-the-browser.html) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed.
```javascript
/** @jsx React.DOM */
var SetIntervalMixin = {
componentWillMount: function() {
this.intervals = [];
},
setInterval: function() {
this.intervals.push(setInterval.apply(null, arguments));
},
componentWillUnmount: function() {
this.intervals.map(clearInterval);
}
};
var TickTock = React.createClass({
mixins: [SetIntervalMixin], // Use the mixin
getInitialState: function() {
return {seconds: 0};
},
componentDidMount: function() {
this.setInterval(this.tick, 1000); // Call a method on the mixin
},
tick: function() {
this.setState({seconds: this.state.seconds + 1});
},
render: function() {
return (
<p>
React has been running for {this.state.seconds} seconds.
</p>
);
}
});
React.renderComponent(
<TickTock />,
document.getElementById('example')
);
```
A nice feature of mixins is that if a component is using multiple mixins and several mixins define the same lifecycle method (i.e. several mixins want to do some cleanup when the component is destroyed), all of the lifecycle methods are guaranteed to be called.
### Testing
**TODO: benjamn**

90
docs/docs/05-building-reusable-components.md
View File

@ -1,90 +0,0 @@
---
id: 05-building-reusable-components
title: Building reusable components
layout: docs
prev: 04-scaling-up.html
next: 06-forms.html
---
When designing interfaces, break down the common design elements (buttons, form fields, layout components, etc) into reusable components with well-defined interfaces. That way, the next time you need to build some UI you can write much less code, which means faster development time, less bugs, and less bytes down the wire.
### Prop validation
As your app grows it's helpful to ensure that your components are used correctly. We do this using `propTypes`.
** TODO zpao **
### Transferring props: a shortcut
A common type of React component is one that extends a basic HTML in a simple way. Often you'll want to copy any HTML attributes passed to your component to the underlying HTML element to save typing. React provides `transferPropsTo()` to do just this.
```javascript
/** @jsx React.DOM */
var CheckLink = React.createClass({
render: function() {
// transferPropsTo() will take any props pased to CheckLink
// and copy them to <a>
return this.transferPropsTo(<a>{'√ '}{this.props.children}</a>);
}
});
React.renderComponent(
<CheckLink href="javascript:alert('Hello, world!');">
Click here!
</CheckLink>,
document.getElementById('example')
);
```
### Mixins
Components are the best way to reuse code in React, but sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](http://en.wikipedia.org/wiki/Cross-cutting_concern). React provides `mixins` to solve this problem.
One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](./06-working-with-the-browser.html) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed.
```javascript
/** @jsx React.DOM */
var SetIntervalMixin = {
componentWillMount: function() {
this.intervals = [];
},
setInterval: function() {
this.intervals.push(setInterval.apply(null, arguments));
},
componentWillUnmount: function() {
this.intervals.map(clearInterval);
}
};
var TickTock = React.createClass({
mixins: [SetIntervalMixin], // Use the mixin
getInitialState: function() {
return {seconds: 0};
},
componentDidMount: function() {
this.setInterval(this.tick, 1000); // Call a method on the mixin
},
tick: function() {
this.setState({seconds: this.state.seconds + 1});
},
render: function() {
return (
<p>
React has been running for {this.state.seconds} seconds.
</p>
);
}
});
React.renderComponent(
<TickTock />,
document.getElementById('example')
);
```
A nice feature of mixins is that if a component is using multiple mixins and several mixins define the same lifecycle method (i.e. several mixins want to do some cleanup when the component is destroyed), all of the lifecycle methods are guaranteed to be called.
### Testing
**TODO: benjamn**

35
docs/docs/08-working-with-your-environment.md
View File

@ -1,35 +0,0 @@
---
id: 08-working-with-your-environment
title: Working with your environment
layout: docs
prev: 07.1-more-about-refs.html
next: 09-reference.html
---
Every project uses a different system for building and deploying JavaScript. We've tried to make React as environment-agnostic as possible.
### CDN-hosted React
We provide CDN-hosted versions of React [on our download page](/react/downloads.html). These prebuilt files use the UMD module format. Dropping them in with a simple `<script>` tag will inject a `React` global into your environment. It also works out-of-the-box in CommonJS and AMD environments.
### Using master
We have instructions for building from master [in our GitHub repository](https://github.com/facebook/react). We build a tree of CommonJS modules under `build/modules` which you can drop into any environment or packaging tool that supports CommonJS.
### In-browser JSX transform
If you like using JSX, we provide an in-browser JSX transformer for development [on our download page](/react/downloads.html). Simply include a `<script type="text/jsx">` tag to engage the JSX transformer. Be sure to include the `/** @jsx React.DOM */` comment as well, otherwise the transformer will not run the transforms.
**Warning:** the in-browser JSX transformer is fairly large and is extra computation. Do not use it in production -- see the next section.
### Productionizing: precompiled JSX
If you have [npm](http://npmjs.org/), you can simply run `npm install -g react-tools` to install our command-line `jsx` tool. This tool will translate files that use JSX syntax to plain JavaScript files that can run directly in the browser. It will also watch directories for you and automatically transform files when they are changed; for example: `jsx --watch src/ build/`. Run `jsx --help` for more information on how to use this tool.
### Helpful open-source projects
The open-source community has built tools that integrate JSX with several build systems.
* [reactify](https://github.com/andreypopp/reactify) - use JSX with [browserify](http://browserify.org/).
* [grunt-react](https://github.com/ericclemmons/grunt-react) - [grunt](http://gruntjs.com/) task for JSX
* [require-jsx](https://github.com/seiffert/require-jsx) - use JSX with [require.js](http://requirejs.org/)
* [reactapp](https://github.com/jordwalke/reactapp) - a sample project to get up-and-running with React quickly

5
docs/docs/09-reference.md
View File

@ -3,7 +3,6 @@ id: 09-reference
title: Reference
layout: docs
prev: 08-tooling-integration.html
next: 09.1-tutorial.html
---
### Examples
@ -15,7 +14,7 @@ next: 09.1-tutorial.html
#### Sample code
* We've included **[a step-by-step comment box tutorial](./09.1-tutorial.md)**
* We've included **[a step-by-step comment box tutorial](./tutorial.md)**
* There is also [a simple LikeButton tutorial](./likebutton/)
* [The React starter kit](/react/downloads.md) includes several examples which you can [view online in our GitHub repo](https://github.com/facebook/react/tree/master/examples/)
* [reactapp](https://github.com/jordwalke/reactapp) is a simple app template to get you up-and-running quickly with React.
@ -175,4 +174,4 @@ React has implemented a browser-independent events and DOM system for performanc
* All events (including submit) bubble correctly per the W3C spec
* All event objects conform to the W3C spec
* 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.
* `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.
* `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.

118
docs/docs/getting-started.md Normal file
View File

@ -0,0 +1,118 @@
---
id: docs-getting-started
title: Getting Started
layout: docs
next: tutorial.html
---
## JSFiddle
The easiest way to start hacking on React is using the following JSFiddle Hello Worlds
* **[React JSFiddle](http://jsfiddle.net/vjeux/kb3gN/)**
* [React JSFiddle without JSX](http://jsfiddle.net/vjeux/VkebS/)
## Starter Kit
Download the starter kit to get started.
<div class="buttons-unit downloads">
<a href="/react/downloads/react-{{site.react_version}}.zip" class="button">
Download Starter Kit {{site.react_version}}
</a>
</div>
In the root directory of the starter kit, create a `helloworld.html` with the following contents.
```html
<!DOCTYPE html>
<html>
<head>
<script src="build/react.min.js"></script>
<script src="build/JSXTransformer.js"></script>
</head>
<body>
<div id="example"></div>
<script type="text/jsx">
/** @jsx React.DOM */
React.renderComponent(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
</script>
</body>
</html>
```
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.
### Separate File
Your React JSX file can live in a separate file. Create the following `src/helloworld.js`.
```javascript
/** @jsx React.DOM */
React.renderComponent(
<h1>Hello, world!</h1>,
document.getElementById('example')
);
```
Then reference it from `helloworld.html`:
```html{10}
<script type="text/jsx" src="src/helloworld.js"></script>
```
### Offline Transform
First install the command-line tools (requires [npm](http://npmjs.org/)):
```
npm install -g react-tools
```
Then, translate your `src/helloworld.js` file to plain JavaScript:
```
jsx --watch src/ build/
```
The file `build/helloworld.js` is autogenerated whenever you make a change.
```javascript{3}
/** @jsx React.DOM */
React.renderComponent(
React.DOM.h1(null, 'Hello, world!'),
document.getElementyById('example')
);
```
> Note:
>
> 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.
Update your HTML file as below:
```html{6,10}
<!DOCTYPE html>
<html>
<head>
<title>Hello React!</title>
<script src="build/react.min.js"></script>
<!-- No need for JSXTransformer! -->
</head>
<body>
<div id="example"></div>
<script src="build/helloworld.js"></script>
</body>
</html>
```
## Want CommonJS?
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.
## Next Steps
Check out [the tutorial](tutorial.html) and the other examples in the `/examples` directory to learn more. Good luck, and welcome!

5
docs/docs/09.1-tutorial.md → docs/docs/tutorial.md
View File

@ -1,8 +1,7 @@
---
id: 09.1-tutorial
id: tutorial
title: Tutorial
layout: docs
prev: 09-reference.html
---
We'll be building a simple, but realistic comments box that you can drop into a blog, similar to Disqus, LiveFyre or Facebook comments.
@ -678,4 +677,4 @@ var CommentBox = React.createClass({
### Congrats!
You have just built a comment box in a few simple steps. Learn more about React in the [reference](syntax.html) or start hacking! Good luck!
You have just built a comment box in a few simple steps. Learn more about React in the [reference](syntax.html) or start hacking! Good luck!