diff --git a/docs/docs/01-motivation.md b/docs/docs/01-motivation.md deleted file mode 100644 index 0ec81f5a04..0000000000 --- a/docs/docs/01-motivation.md +++ /dev/null @@ -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). \ No newline at end of file diff --git a/docs/docs/01-why-react.md b/docs/docs/01-why-react.md index b7c463dace..52fca18831 100644 --- a/docs/docs/01-why-react.md +++ b/docs/docs/01-why-react.md @@ -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). \ No newline at end of file +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). diff --git a/docs/docs/05-building-effective-reusable-components.md b/docs/docs/05-building-effective-reusable-components.md deleted file mode 100644 index 073eb782d7..0000000000 --- a/docs/docs/05-building-effective-reusable-components.md +++ /dev/null @@ -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 - return this.transferPropsTo({'√ '}{this.props.children}); - } -}); - -React.renderComponent( - - Click here! - , - 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 ( -

- React has been running for {this.state.seconds} seconds. -

- ); - } -}); - -React.renderComponent( - , - 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** \ No newline at end of file diff --git a/docs/docs/05-building-reusable-components.md b/docs/docs/05-building-reusable-components.md deleted file mode 100644 index 24e79cc2ad..0000000000 --- a/docs/docs/05-building-reusable-components.md +++ /dev/null @@ -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 - return this.transferPropsTo({'√ '}{this.props.children}); - } -}); - -React.renderComponent( - - Click here! - , - 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 ( -

- React has been running for {this.state.seconds} seconds. -

- ); - } -}); - -React.renderComponent( - , - 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** \ No newline at end of file diff --git a/docs/docs/08-working-with-your-environment.md b/docs/docs/08-working-with-your-environment.md deleted file mode 100644 index a28e0a9008..0000000000 --- a/docs/docs/08-working-with-your-environment.md +++ /dev/null @@ -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 ` + + + +
+ + + +``` + +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 ` +``` + +### 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} + + + + Hello React! + + + + +
+ + + +``` + +## 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! diff --git a/docs/docs/09.1-tutorial.md b/docs/docs/tutorial.md similarity index 99% rename from docs/docs/09.1-tutorial.md rename to docs/docs/tutorial.md index 3d74934129..04b313ecf4 100644 --- a/docs/docs/09.1-tutorial.md +++ b/docs/docs/tutorial.md @@ -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! \ No newline at end of file +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!