@samitouri / QOS-React-2 / commits / 9694a0f7ea

Fork 0

The library for web and native user interfaces.

Fix title casing and heading levels

Paul O’Shannessy committed Jul 16, 2013 at 14:52 UTC 9694a0f7eaf7c105c44e2b3beb1578986f36a143

13 files changed +109 -109

docs/_includes/nav_docs.html

+7 -7

@@ -2,7 +2,7 @@

2 <div class="nav-docs-section">

3 <h3>Quick start</h3>

4 <ul>

5 - <li><a href="/react/docs/getting-started.html"{% if page.id == 'getting-started' %} class="active"{% endif %}>Getting started</a></li>

5 + <li><a href="/react/docs/getting-started.html"{% if page.id == 'getting-started' %} class="active"{% endif %}>Getting Started</a></li>

6 <li><a href="/react/docs/tutorial.html"{% if page.id == 'tutorial' %} class="active"{% endif %}>Tutorial</a></li>

7 </ul>

8 </div>

@@ -10,13 +10,13 @@

10 <h3>Guides</h3>

11 <ul>

12 <li><a href="/react/docs/01-why-react.html"{% if page.id == '01-why-react' %} class="active"{% endif %}>Why React?</a></li>

13 - <li><a href="/react/docs/02-displaying-data.html"{% if page.id == '02-displaying-data' %} class="active"{% endif %}>Displaying data</a></li>

14 - <li><a href="/react/docs/03-interactivity-and-dynamic-uis.html"{% if page.id == '03-interactivity-and-dynamic-uis' %} class="active"{% endif %}>Interactivity and dynamic UIs</a></li>

15 - <li><a href="/react/docs/04-multiple-components.html"{% if page.id == '04-multiple-components' %} class="active"{% endif %}>Multiple components</a></li>

16 - <li><a href="/react/docs/05-reusable-components.html"{% if page.id == '05-reusable-components' %} class="active"{% endif %}>Reusable components</a></li>

13 + <li><a href="/react/docs/02-displaying-data.html"{% if page.id == '02-displaying-data' %} class="active"{% endif %}>Displaying Data</a></li>

14 + <li><a href="/react/docs/03-interactivity-and-dynamic-uis.html"{% if page.id == '03-interactivity-and-dynamic-uis' %} class="active"{% endif %}>Interactivity and Dynamic UIs</a></li>

15 + <li><a href="/react/docs/04-multiple-components.html"{% if page.id == '04-multiple-components' %} class="active"{% endif %}>Multiple Components</a></li>

16 + <li><a href="/react/docs/05-reusable-components.html"{% if page.id == '05-reusable-components' %} class="active"{% endif %}>Reusable Components</a></li>

17 <li><a href="/react/docs/06-forms.html"{% if page.id == '06-forms' %} class="active"{% endif %}>Forms</a></li>

18 - <li><a href="/react/docs/07-working-with-the-browser.html"{% if page.id == '07-working-with-the-browser' %} class="active"{% endif %}>Working with the browser</a></li>

19 - <li><a href="/react/docs/08-tooling-integration.html"{% if page.id == '08-tooling-integration' %} class="active"{% endif %}>Tooling integration</a></li>

18 + <li><a href="/react/docs/07-working-with-the-browser.html"{% if page.id == '07-working-with-the-browser' %} class="active"{% endif %}>Working With the Browser</a></li>

19 + <li><a href="/react/docs/08-tooling-integration.html"{% if page.id == '08-tooling-integration' %} class="active"{% endif %}>Tooling Integration</a></li>

20 <li><a href="/react/docs/09-reference.html"{% if page.id == '09-reference' %} class="active"{% endif %}>Reference</a></li>

22 </ul>

docs/docs/01-why-react.md

+4 -4

@@ -8,20 +8,20 @@ React is a JavaScript library for creating user interfaces by Facebook and Insta

9 We built React to solve one problem: **building large applications with data that changes over time**. To do this, React has two main ideas.

11 -### Stay simple and declarative

11 +### Stay Simple and Declarative

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

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

17 -### Build composable components

17 +## Build Composable Components

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

21 -### Give it five minutes

21 +## Give it Five Minutes

23 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!

25 -### Learn more

25 +## Learn More

27 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).

docs/docs/02-displaying-data.md

+5 -5

@@ -1,13 +1,13 @@

1 ---

2 id: 02-displaying-data

3 -title: Displaying data

3 +title: Displaying Data

4 layout: docs

5 prev: 01-why-react.html

6 next: 02.1-jsx-in-depth.html

7 ---

8 The most basic thing you can do with a UI is display some data. React makes it easy to display data, and automatically keeps it up-to-date when the data changes.

10 -### Getting started

10 +## Getting Started

12 Let's look at a really simple example. Create a `hello-react.html` file with the following code:

@@ -54,7 +54,7 @@ setInterval(function() {

54 }, 500);

55 ```

57 -### Reactive updates

57 +## Reactive Updates

59 View the finished code in a web browser and type your name into the text field. Notice that React is only changing the time string in the UI -- any input you put in the text field remains, even though you haven't written any code to manage this behavior. React figures it out for you and does the right thing.

@@ -62,13 +62,13 @@ The way it is able to figure this out is that React does not directly manipulate

63 The inputs to this component are called `props` -- short for "properties". They're passed as attributes in JSX syntax. You should think of these as immutable within the component, that is, **never write to this.props**.

65 -### Components are just like functions

65 +## Components are Just Like Functions

67 React components are very simple. You can think of them as simple function that take in `props` and `state` (discussed later) and render HTML. Because they're so simple, it makes them very easy to reason about.

69 **One limitation**: React components can only render a single root node. If you want to return multiple nodes they *must* be wrapped in a single root. This is a limitation we can fix, but we have not identified a pressing reason to do so yet; reach out to our [Google Group](http://groups.google.com/group/reactjs) if you have a compelling case for it.

71 -### JSX syntax

71 +## JSX Syntax

73 We strongly believe that components are the right way to separate concerns rather than "templates" and "display logic." We think that markup and the code that generates it are intimately tied together. Additionally, display logic is often very complex and using template languages to express it becomes cumbersome.

docs/docs/02.1-jsx-in-depth.md

+11 -11

@@ -8,7 +8,7 @@ next: 02.2-jsx-gotchas.html

8 JSX is a JavaScript XML syntax transform recommended (but not required) for use

9 with React.

11 -### Why JSX?

11 +## Why JSX?

13 First of all, **don't use JSX if you don't like it!**

@@ -25,7 +25,7 @@ We recommend using JSX for many reasons:

25 - Designers are more comfortable making changes.

26 - It's familiar for those who have used MXML or XAML.

28 -### The Transform

28 +## The Transform

30 JSX transforms XML-like syntax into native JavaScript. It turns XML elements and

31 attributes into function calls and objects, respectively.

@@ -61,7 +61,7 @@ how to setup compilation.

61 > Details about the code transform are given here to increase understanding, but

62 > your code should not rely on these implementation details.

64 -### React and JSX

64 +## React and JSX

66 React and JSX are independent technologies, but JSX was primarily built with

67 React in mind. The two valid uses of JSX are:

@@ -97,7 +97,7 @@ See [Component Basics](component-basics.html) to learn more about components.

97 > as XML attribute names. Instead, React DOM components expect attributes like

98 > `className` and `htmlFor`, respectively.

100 -### DOM Convenience

100 +## DOM Convenience

101

102 Having to define variables for every type of DOM element can get tedious

103 (e.g. `var div, span, h1, h2, ...`). JSX provides a convenience to address this

@@ -121,9 +121,9 @@ var tree = Nav(null, React.DOM.span(null, null));

121 > DOM. The docblock parameter is only a convenience to resolve the most commonly

122 > used elements. In general, JSX has no notion of the DOM.

123

124 -### JavaScript Expressions

124 +## JavaScript Expressions

125

126 -##### Attribute Expressions

126 +### Attribute Expressions

127

128 To use a JavaScript expression as an attribute value, wrap the expression in a

129 pair of curly braces (`{}`) instead of quotes (`""`).

@@ -135,7 +135,7 @@ var person = <Person name={window.isLoggedIn ? window.name : ''} />;

135 var person = Person({name: window.isLoggedIn ? window.name : ''});

136 ```

137

138 -##### Child Expressions

138 +### Child Expressions

139

140 Likewise, JavaScript expressions may be used to express children:

141

@@ -146,14 +146,14 @@ var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;

146 var content = Container(null, window.isLoggedIn ? Nav(null, null) : Login(null, null));

147 ```

148

149 -##### Comments

149 +### Comments

150

151 It's easy to add comments within your JSX; they're just JS expressions:

152 ```javascript

153 var content = <Container>{/* this is a comment */}<Nav /></Container>;

154 ```

155

156 -### Tooling

156 +## Tooling

157

158 Beyond the compilation step, JSX does not require any special tools.

159

@@ -162,7 +162,7 @@ Beyond the compilation step, JSX does not require any special tools.

162 - Elements use standard scoping so linters can find usage of out-of-scope

163 components.

164

165 -### Prior Work

165 +## Prior Work

166

167 JSX is similar to several other JavaScript embedded XML language

168 proposals/projects. Some of the features of JSX that distinguish it from similar

@@ -172,4 +172,4 @@ efforts include:

172 - JSX neither provides nor requires a runtime library.

173 - JSX does not alter or add to the semantics of JavaScript.

174

175 -JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./02.2-jsx-gotchas.html) for some key differences.

\ No newline at end of file

175 +JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./02.2-jsx-gotchas.html) for some key differences.

docs/docs/02.2-jsx-gotchas.md

+4 -4

@@ -7,7 +7,7 @@ next: 03-interactivity-and-dynamic-uis.html

7 ---

8 JSX looks like HTML but there are some important differences you may run into.

10 -### Whitespace removal

10 +## Whitespace removal

12 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 `{' '}`.

@@ -17,7 +17,7 @@ JSX doesn't follow the same whitespace elimination rules as HTML. JSX removes al

18 Follow [Issue #65](https://github.com/facebook/react/issues/65) for discussion on this behavior.

20 -### HTML Entities

20 +## HTML Entities

22 You can insert HTML entities within literal text in JSX:

@@ -57,7 +57,7 @@ As a last resort, you always have the ability to insert raw HTML.

57 <div dangerouslySetInnerHTML={{'{{'}}__html: 'First · Second'}} />

58 ```

60 -### Custom HTML Attributes

60 +## Custom HTML Attributes

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

@@ -69,4 +69,4 @@ If you pass properties to native HTML elements that do not exist in the HTML spe

70 ```javascript

71 <div aria-hidden={true} />

72 -```

\ No newline at end of file

72 +```

docs/docs/03-interactivity-and-dynamic-uis.md

+9 -9

@@ -7,7 +7,7 @@ next: 04-multiple-components.html

7 ---

8 You've already [learned how to display data](./02-displaying-data.html) with React. Now let's look at how to make our UIs interactive.

10 -### A simple example

10 +## A Simple Example

12 ```javascript

13 /** @jsx React.DOM */

@@ -35,13 +35,13 @@ React.renderComponent(

35 );

36 ```

38 -### Event handling and synthetic events

38 +## Event Handling and Synthetic Events

40 With React you simply pass your event handler as a camelCased prop similar to how you'd do it in normal HTML. React ensures that all events behave identically in IE8 and above by implementing a synthetic event system. That is, React knows how to bubble and capture events according to the spec, and the events passed to your event handler are guaranteed to be consistent with [the W3C spec](http://www.w3.org/TR/DOM-Level-3-Events/), regardless of which browser you're using.

42 **If you'd like to use React on a touch device** (i.e. a phone or tablet), simply call `React.initializeTouchEvents(true);` to turn them on.

44 -### Under the hood: autoBind and event delegation

44 +## Under the Hood: autoBind and Event Delegation

46 Under the hood React does a few things to keep your code performant and easy to understand.

@@ -49,17 +49,17 @@ Under the hood React does a few things to keep your code performant and easy to

50 **Event delegation.** React doesn't actually attach event handlers to the nodes themselves. When React starts up, it starts listening for all events at the top level using a single event listener. When a component is mounted or unmounted, the event handlers are simply added or removed from a fast internal event mapping. When the event occurs, React knows how to dispatch it using this mapping. When there are no event handlers left in the mapping, React's event handlers are simple no-ops. To learn more about why this is fast, see [David Walsh's excellent blog post](http://davidwalsh.name/event-delegate).

52 -### Components are just state machines

52 +## Components are Just State Machines

54 React thinks of UIs as simple state machines. By thinking of a UI as being in various states and rendering those states, it's easy to keep your UI consistent.

56 In React, you simply update a component's state, and then render a new UI based on this new state. React takes care of updating the DOM for you in the most efficient way.

58 -### How state works

58 +## How State Works

60 A common way to inform React of a data change is by calling `setState(data, callback)`. This method merges `data` into `this.state` and re-renders the component. When the component finishes re-rendering, the optional `callback` is called. Most of the time you'll never need to provide a `callback` since React will take care of keeping your UI up-to-date for you.

62 -### What components should have state?

62 +## What Components Should Have State?

64 Most of your components should simply take some data from `props` and render it. However, sometimes you need to respond to user input, a server request or the passage of time. For this you use state.

@@ -67,14 +67,14 @@ Most of your components should simply take some data from `props` and render it.

68 A common pattern is to create several stateless components that just render data, and have a stateful component above them in the hierarchy that passes its state to its children via `props`. The stateful component encapsulates all of the interaction logic, while the stateless components take care of rendering data in a declarative way.

70 -### What should go in state?

70 +## What Should Go in State?

72 **State should contain data that the component's event handlers may change to trigger a UI update.** In real apps this data tends to be very small and JSON-serializable. When building a stateful component, think about the minimal possible representation of its state, and only store those properties in `this.state`. Inside of `render()` simply compute any other information you need based on this state. You'll find that thinking about and writing applications in this way tends to lead to the most correct application, since adding redundant or computed values to state means that you need to explicitly keep them in sync rather than rely on React computing them for you.

74 -### What *shouldn't* go in state?

74 +## What *Shouldn't* Go in State?

76 `this.state` should only contain the minimal amount of data needed to represent your UI's state. As such, it should not contain:

78 * **Computed data.** Don't worry about precomputing values based on state -- it's easier to ensure that your UI is consistent if you do all computation within `render()`. For example, if you have an array of list items in state and you want to render the count as a string, simply render `this.state.listItems.length + ' list items'` in your `render()` method rather than storing it on state.

79 * **React components.** Build them in `render()` based on underlying props and state.

80 -* **Duplicated data from props.** Try to use props as the source of truth where possible. Because props can change over time, it's appropriate to store props in state to be able to know its previous values.

\ No newline at end of file

80 +* **Duplicated data from props.** Try to use props as the source of truth where possible. Because props can change over time, it's appropriate to store props in state to be able to know its previous values.

docs/docs/04-multiple-components.md

+11 -11

@@ -1,17 +1,17 @@

1 ---

2 id: 04-multiple-components

3 -title: Multiple components

3 +title: Multiple Components

4 layout: docs

5 prev: 03-interactivity-and-dynamic-uis.html

6 next: 05-reusable-components.html

7 ---

8 So far, we've looked at how to write a single component to display data and handle user input. Next let's examine one of React's finest features: composability.

10 -### Motivation: separation of concerns

10 +## Motivation: Separation of Concerns

12 By building modular components that reuse other components with well-defined interfaces, you get much of the same benefits that you get by using functions or classes. Specifically you can *separate the different concerns* of your app however you please simply by building new components. By building a custom component library for your application, you are expressing your UI in a way that best fits your domain.

14 -### Composition example

14 +## Composition Example

16 Let's create a simple Avatar component which shows a profile picture and username using the Facebook Graph API.

@@ -53,13 +53,13 @@ React.renderComponent(

53 );

54 ```

56 -### Ownership

56 +## Ownership

58 In the above example, instances of `Avatar` *own* instances of `ProfilePic` and `ProfileLink`. In React, **an owner is the component that sets the `props` of other components**. More formally, if a component `X` is created in component `Y`'s `render()` method, it is said that `X` is *owned by* `Y`. As discussed earlier, a component cannot mutate its `props` -- they are always consistent with what its owner sets them to. This key property leads to UIs that are guaranteed to be consistent.

60 It's important to draw a distinciton between the owner-ownee relationship and the parent-child relationship. The owner-ownee relationship is specific to React, while the parent-child relationship is simply the one you know and love from the DOM. In the example above, `Avatar` owns the `div`, `ProfilePic` and `ProfileLink` instances, and `div` is the **parent** (but not owner) of the `ProfilePic` and `ProfileLink` instances.

62 -### Children

62 +## Children

64 When you create a React component instance, you can include additional React components or JavaScript expressions between the opening and closing tags like this:

@@ -69,7 +69,7 @@ When you create a React component instance, you can include additional React com

70 `Parent` can read its children by accessing the special `this.props.children` prop.

72 -#### Child Reconciliation

72 +### Child Reconciliation

74 > Reconciliation is the process by which React updates the DOM with each new render pass.

@@ -84,7 +84,7 @@ In general, children are reconciled according to the order in which they are ren

85 Intuitively, `<p>Paragraph 1</p>` was removed. Instead, React will reconcile the DOM by changing the text content of the first child and destroying the last child. React reconciles according to the *order* of the children.

87 -#### Stateful Children

87 +### Stateful Children

89 For most components, this is not a big deal. However, for stateful components that maintain data in `this.state` across render passes, this can be very problematic.

@@ -97,7 +97,7 @@ In most cases, this can be sidestepped by hiding elements instead of destroying

97 <Card><p style={{display: 'none'}}>Paragraph 1</p><p>Paragraph 2</p></Card>

98 ```

100 -#### Dynamic Children

100 +### Dynamic Children

101

102 The situation gets more complicated when the children are shuffled around (as in search results) or if new components are added onto the front of the list (as in streams). In these cases where the identity and state of each child must be maintained across render passes, you can uniquely identify each child by assigning it a `key`:

103

@@ -116,14 +116,14 @@ The situation gets more complicated when the children are shuffled around (as in

116

117 When React reconciles the keyed children, it will ensure that any child with `key` will be reordered (instead of clobbered) or destroyed (instead of reused).

118

119 -### Data flow

119 +## Data flow

120

121 In React, data flows from owner to owned component through `props` as discussed above. This is effectively one-way data binding: owners bind their owned component's props to some value the owner has computed based on its `props` or `state`. Since this process happens recursively, data changes are automatically reflected everywhere they are used.

122

123 -### A note on performance

123 +## A Note on Performance

124

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

126

127 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 API docs](./api.html) for more information.

128

129 -**Note:** if `shouldComponentUpdate()` returns false when data has actually changed, React can't keep your UI in sync. Be sure you know what you're doing while using it, and only use this function when you have a noticeable performance problem. Don't underestimate how fast JavaScript is relative to the DOM.

\ No newline at end of file

129 +**Note:** if `shouldComponentUpdate()` returns false when data has actually changed, React can't keep your UI in sync. Be sure you know what you're doing while using it, and only use this function when you have a noticeable performance problem. Don't underestimate how fast JavaScript is relative to the DOM.

docs/docs/05-reusable-components.md

+6 -6

@@ -1,19 +1,19 @@

1 ---

2 id: 05-reusable-components

3 -title: Reusable components

3 +title: Reusable Components

4 layout: docs

5 prev: 04-multiple-components.html

6 next: 06-forms.html

7 ---

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

10 -### Prop validation

10 +## Prop Validation

12 As your app grows it's helpful to ensure that your components are used correctly. We do this using `propTypes`.

14 ** TODO zpao **

16 -### Transferring props: a shortcut

16 +## Transferring Props: A Shortcut

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

@@ -36,7 +36,7 @@ React.renderComponent(

36 );

37 ```

39 -### Mixins

39 +## Mixins

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

@@ -85,6 +85,6 @@ React.renderComponent(

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

88 -### Testing

88 +## Testing

90 -**TODO: benjamn**

\ No newline at end of file

90 +**TODO: benjamn**

docs/docs/06-forms.md

+7 -7

@@ -7,7 +7,7 @@ next: 07-working-with-the-browser.html

7 ---

8 Form components such as `<input>`, `<textarea>`, and `<option>` differ from other native components because they can be mutated via user interactions. These components provide interfaces that make it easier to manage forms in response to user interactions.

10 -### Interactive Props

10 +## Interactive Props

12 Form components support a few props that are affected via user interactions:

@@ -25,7 +25,7 @@ Form components allow listening for changes by setting a callback to the `onChan

26 Like all DOM events, the `onChange` prop is supported on all native components and can be used to listen to bubbled change events.

28 -### Controlled Components

28 +## Controlled Components

30 An `<input>` with `value` set is a *controlled* component. In a controlled `<input>`, the value of the rendered element will always reflect the `value` prop. For example:

@@ -60,7 +60,7 @@ In this example, we are simply accepting the newest value provided by the user a

61 This would accept user input but truncate the value to the first 140 characters.

63 -### Uncontrolled Components

63 +## Uncontrolled Components

65 An `<input>` that does not supply a `value` (or sets it to `null`) is an *uncontrolled* component. In an uncontrolled `<input>`, the value of the rendered element will reflect the user's input. For example:

@@ -84,9 +84,9 @@ This example will function much like the **Controlled Components** example above

85 Likewise, `<input>` supports `defaultChecked` and `<option>` supports `defaultSelected`.

87 -### Advanced Topics

87 +## Advanced Topics

89 -#### Why controlled components?

89 +### Why Controlled Components?

91 Using form components such as `<input>` in React presents a challenge that is absent when writing traditional form HTML. For example, in HTML:

@@ -106,7 +106,7 @@ Unlike HTML, React components must represent the state of the view at any point

106

107 Since this method describes the view at any point in time, the value of the text input should *always* be `Untitled`.

108

109 -#### Why textarea value?

109 +### Why Textarea Value?

110

111 In HTML, the value of `<textarea>` is usually set using its children:

112

@@ -121,4 +121,4 @@ For HTML, this easily allows developers to supply multiline values. However, sin

121 <textarea name="description" value="This is a description." />

122 ```

123

124 -If you *do* decide to use children, they will behave like `defaultValue`.

\ No newline at end of file

124 +If you *do* decide to use children, they will behave like `defaultValue`.

docs/docs/07-working-with-the-browser.md

+12 -12

@@ -1,13 +1,13 @@

1 ---

2 id: 07-working-with-the-browser

3 -title: Working with the browser

3 +title: Working With the Browser

4 layout: docs

5 prev: 06-forms.html

6 next: 07.1-more-about-refs.html

7 ---

8 React provides powerful abstractions that free you from touching the DOM directly in most cases, but sometimes you simply need to access the underlying API, perhaps to work with a third-party library or existing code.

10 -### The mock DOM

10 +## The Mock DOM

12 React is so fast because it never talks to the DOM directly. React maintains a fast in-memory representation of the DOM. `render()` methods return a *description* of the DOM, and React can diff this description with the in-memory representation to compute the fastest way to update the browser.

@@ -15,7 +15,7 @@ Additionally, React implements a full synthetic event system such that all event

16 Most of the time you should stay within React's "faked browser" world since it's more performant and easier to reason about. However, sometimes you simply need to access the underlying API, perhaps to work with a third-party library like a jQuery plugin. React provides escape hatches for you to use the underlying DOM API directly.

18 -### Refs and getDOMNode()

18 +## Refs and getDOMNode()

20 To interact with the browser, you'll need a reference to a DOM node. Every mounted React component has a `getDOMNode()` function which you can call to get a reference to it.

@@ -53,11 +53,11 @@ React.renderComponent(

53 );

54 ```

56 -### More about refs

56 +## More About Refs

58 To learn more about refs, including ways to use them effectively, see our [more about refs](./07.1-more-about-refs.html) documentation.

60 -### Component lifecycle

60 +## Component Lifecycle

62 Components have three main parts of their lifecycle:

63 - **Mounting:** A component is being inserted into the DOM.

@@ -66,24 +66,24 @@ Components have three main parts of their lifecycle:

67 React provides lifecycle methods that you can override to hook into this process. We provide **will** methods, which are called right before something happens, and **did** methods which are called right after something happens.

69 -#### Mounting

69 +### Mounting

71 - `getInitialState(): object` is invoked before a component is mounted. Stateful components should implement this and return the initial state data.

72 - `componentWillMount()` is invoked immediately before mounting occurs.

73 - `componentDidMount(DOMElement rootNode)` is invoked immediately after mounting occurs. Initialization that requires DOM nodes should go here.

75 -#### Updating

75 +### Updating

77 - `componentWillReceiveProps(object nextProps)` is invoked when a mounted component receives new props. This method should be used to compare `this.props` and `nextProps` to perform state transitions using `this.setState()`.

78 - `shouldComponentUpdate(object nextProps, object nextState): boolean` is invoked when a component decides whether any changes warrant an update to the DOM. Implement this as an optimization to compare `this.props` with `nextProps` and `this.state` with `nextState` and return false if React should skip updating.

79 - `componentWillUpdate(object nextProps, object nextState)` is invoked immediately before updating occurs. You cannot call `this.setState()` here.

80 - `componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)` is invoked immediately after updating occurs.

82 -#### Unmounting

82 +### Unmounting

84 - `componentWillUnmount()` is invoked immediately before a component is unmounted and destroyed. Cleanup should go here.

86 -#### Mounted Methods

86 +### Mounted Methods

88 _Mounted_ composite components also support the following methods:

@@ -96,14 +96,14 @@ _Mounted_ composite components also support the following methods:

96 > `componentDidUpdate()` is a convenience. The same node can be obtained by

97 > calling `this.getDOMNode()`.

99 -### Browser suppport and polyfills

99 +## Browser Suppport and Polyfills

100

101 At Facebook, we support older browsers, including IE8. We've had polyfills in place for a long time to allow us to write forward-thinking JS. This means we don't have a bunch of hacks scattered throughout our codebase and we can still expect our code to "just work". For example, instead of seeing `+new Date()`, we can just write `Date.now()`. Since the open source React is the same as what we use internally, we've carried over this philosophy of using forward thinking JS.

102

103 In addition to that philosphy, we've also taken the stance that we, as authors of a JS library, should not be shipping polyfills as a part of our library. If every library did this, there's a good chance you'd be sending down the same polyfill multiple times, which could be a sizable chunk of dead code. If your product needs to support older browsers, chances are you're already using something like [es5-shim](https://github.com/kriskowal/es5-shim).

104

105

106 -#### Polyfills needed to support older browsers

106 +### Polyfills Needed to Support Older Browsers

107

108 * `Array.isArray`

109 * `Array.prototype.forEach`

@@ -115,4 +115,4 @@ In addition to that philosphy, we've also taken the stance that we, as authors o

115 All of these can be polyfilled using `es5-shim.js` from [https://github.com/kriskowal/es5-shim](https://github.com/kriskowal/es5-shim).

116

117 * `console.*` - [https://github.com/paulmillr/console-polyfill](https://github.com/paulmillr/console-polyfill)

118 -* `Object.create` - Provided in `es5-sham.js` @ [https://github.com/kriskowal/es5-shim](https://github.com/kriskowal/es5-shim)

\ No newline at end of file

118 +* `Object.create` - Provided in `es5-sham.js` @ [https://github.com/kriskowal/es5-shim](https://github.com/kriskowal/es5-shim)

docs/docs/07.1-more-about-refs.md

+5 -5

@@ -1,6 +1,6 @@

1 ---

2 id: 07.1-more-about-refs

3 -title: More about refs

3 +title: More About Refs

4 layout: docs

5 prev: 07-working-with-the-browser.html

6 next: 08-tooling-integration.html

@@ -63,7 +63,7 @@ In this counterexample, the `<input />` is merely a *description* of an `<input

64 So how do we talk to the *real* backing instance of the input?

66 -### The `ref` attribute

66 +## The `ref` Attribute

68 React supports a very special property that you can attach to any component that is output from `render()`. This special property allows you to refer to the corresponding **backing instance** of anything returned from `render()`. It is always guaranteed to be the proper instance, at any point in time.

@@ -81,7 +81,7 @@ It's as simple as:

81 this.refs.myInput

82 ```

84 -### Completing the Example

84 +## Completing the Example

86 ```javascript

87 var App = React.createClass({

@@ -115,7 +115,7 @@ It's as simple as:

115 In this example, our render function returns a description of an <input /> instance. But the true instance is accessed via `this.refs.theInput`. As long as a child component with `ref="theInput"` is returned from render, `this.refs.theInput` will access the the proper instance. This even works on higher level (non-DOM) components such as <Typeahead ref="myTypeahead" />.

116

117

118 -### Summary

118 +## Summary

119

120 Refs are a great way to send a message to a particular child instance in a way that would be inconvenient to do via streaming Reactive `props` and `state`. They should, however, not be your go-to abstraction for flowing data through your application. By default, use the Reactive data flow and save `ref`s for use cases that are inherently non-reactive.

121

@@ -132,4 +132,4 @@ Refs are automatically book-kept for you! If that child is destroyed, its ref is

132

133 - If you want to preserve Google Closure Compiler Crushing resilience, make sure to never access as a property what was specified as a string. This means you must access using `this.refs['myRefString']` if your ref was defined as `ref="myRefString"`.

134

135 -- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" - instead, the data flow will usually accomplish your goal.

\ No newline at end of file

135 +- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" - instead, the data flow will usually accomplish your goal.

docs/docs/08-tooling-integration.md

+6 -6

@@ -7,29 +7,29 @@ next: 09-reference.html

7 ---

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

10 -### CDN-hosted React

10 +## CDN-hosted React

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

14 -### Using master

14 +## Using Master

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

18 -### In-browser JSX transform

18 +## In-browser JSX Transform

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

22 **Warning:** the in-browser JSX transformer is fairly large and is extra computation. Do not use it in production -- see the next section.

24 -### Productionizing: precompiled JSX

24 +## Productionizing: Precompiled JSX

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

28 -### Helpful open-source projects

28 +## Helpful Open-Source Projects

30 The open-source community has built tools that integrate JSX with several build systems.

32 * [reactify](https://github.com/andreypopp/reactify) - use JSX with [browserify](http://browserify.org/).

33 * [grunt-react](https://github.com/ericclemmons/grunt-react) - [grunt](http://gruntjs.com/) task for JSX

34 * [require-jsx](https://github.com/seiffert/require-jsx) - use JSX with [require.js](http://requirejs.org/)

35 -* [reactapp](https://github.com/jordwalke/reactapp) - a sample project to get up-and-running with React quickly

\ No newline at end of file

35 +* [reactapp](https://github.com/jordwalke/reactapp) - a sample project to get up-and-running with React quickly

docs/docs/09-reference.md

+22 -22

@@ -4,15 +4,15 @@ title: Reference

4 layout: docs

5 prev: 08-tooling-integration.html

6 ---

7 -### Examples

7 +## Examples

9 -#### Production apps

9 +### Production Apps

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.

15 -#### Sample code

15 +### Sample Code

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

18 * There is also [a simple LikeButton tutorial](./likebutton/)

@@ -21,17 +21,17 @@ prev: 08-tooling-integration.html

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.

24 -### API

24 +## API

26 -#### React

26 +### React

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

30 -##### React.DOM

30 +#### React.DOM

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

34 -##### React.initializeTouchEvents

34 +#### React.initializeTouchEvents

36 ```javascript

37 initializeTouchEvents(boolean shouldUseTouch)

@@ -39,7 +39,7 @@ initializeTouchEvents(boolean shouldUseTouch)

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

42 -##### React.createClass

42 +#### React.createClass

44 ```javascript

45 function createClass(object specification)

@@ -47,7 +47,7 @@ function createClass(object specification)

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

50 -##### React.renderComponent

50 +#### React.renderComponent

52 ```javascript

53 ReactComponent renderComponent(ReactComponent container, DOMElement container)

@@ -57,7 +57,7 @@ Renders a React component into the DOM in the supplied `container`.

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

60 -##### React.unmountAndReleaseReactRootNode

60 +#### React.unmountAndReleaseReactRootNode

62 ```javascript

63 unmountAndReleaseReactRootNode(DOMElement container)

@@ -65,7 +65,7 @@ unmountAndReleaseReactRootNode(DOMElement container)

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

68 -##### React.renderComponentToString

68 +#### React.renderComponentToString

70 ```javascript

71 renderComponentToString(ReactComponent component, function callback)

@@ -73,17 +73,17 @@ renderComponentToString(ReactComponent component, function callback)

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

76 -#### AbstractEvent

76 +### AbstractEvent

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

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

82 -#### ReactComponent

82 +### ReactComponent

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

86 -##### getDOMNode

86 +#### getDOMNode

88 ```javascript

89 DOMElement getDOMNode()

@@ -91,7 +91,7 @@ DOMElement getDOMNode()

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

94 -##### setProps

94 +#### setProps

96 ```javascript

97 setProps(object nextProps)

@@ -101,7 +101,7 @@ When you're integrating with an external JavaScript application you may want to

101

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

103

104 -##### replaceProps

104 +#### replaceProps

105

106 ```javascript

107 replaceProps(object nextProps)

@@ -109,7 +109,7 @@ replaceProps(object nextProps)

109

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

111

112 -##### transferPropsTo

112 +#### transferPropsTo

113

114 ```javascript

115 ReactComponent transferPropsTo(ReactComponent targetComponent)

@@ -117,7 +117,7 @@ ReactComponent transferPropsTo(ReactComponent targetComponent)

117

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

119

120 -##### setState

120 +#### setState

121

122 ```javascript

123 setState(object nextState[, function callback])

@@ -131,7 +131,7 @@ Merges nextState with the current state. This is the primary method you use to t

131

132 **Note**: There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.

133

134 -##### replaceState

134 +#### replaceState

135

136 ```javascript

137 replaceState(object nextState[, function callback])

@@ -139,7 +139,7 @@ replaceState(object nextState[, function callback])

139

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

141

142 -##### forceUpdate()

142 +#### forceUpdate()

143

144 ```javascript

145 forceUpdate([function callback])

@@ -151,7 +151,7 @@ Normally you should try to avoid all uses of `forceUpdate()` and only read from

151

152 **Note**: There is no guarantee of synchronous operation of calls to `forceUpdate` and calls may be batched for performance gains.

153

154 -##### Lifecycle methods

154 +#### Lifecycle methods

155

156 ```javascript

157 object getInitialState()

@@ -167,7 +167,7 @@ componentWillUnmount()

167

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

169

170 -### DOM differences

170 +## DOM Differences

171

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

173