further improvements

petehunt committed Jul 10, 2013 at 17:18 UTC faa84b5b852e73f446b95ed0c5b9f0a8d5a410d0

3 files changed +11

docs/docs/refactor/00-table-of-contents.md

@@ -3,6 +3,7 @@

3 - High information density -- assume the reader is adept at JS

4 - Talk about best practices

5 - JSFiddles for all code samples

6 +- Provide background for some of the design decisions

8 # Outline

@@ -14,12 +15,14 @@ Motivation / Why React?

15 Displaying data

16 - Hello world example

17 - Reactive updates

18 +- Components are just functions

19 - JSX syntax (link to separate doc?)

21 Handling user input

22 - Click handler example

23 - Event handlers / synthetic events (link to w3c docs)

24 - Under the hood: autoBind and event delegation (IE8 notes)

25 +- React is a state machine

26 - How state works

27 - What should go in state?

28 - What components should have state?

docs/docs/refactor/02-displaying-data.md

@@ -55,6 +55,10 @@ View the finished code in a web browser and type your name into the text field.

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

58 +## Components are just like functions

59 +

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

61 +

62 ## JSX syntax

64 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/refactor/03-handling-user-input.md

@@ -42,6 +42,10 @@ Under the hood React does a few things to keep your code performant and easy to

43 **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).

45 +## Components are just state machines

46 +

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

48 +

49 ## How state works

51 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 state tends to be so minimal.