From 79b09d95977eb08ca0e48e100caefb3fc55e5769 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Paul=20O=E2=80=99Shannessy?= <paul@oshannessy.com>
Date: Thu, 14 Nov 2013 14:59:41 -0800
Subject: [PATCH] Merge pull request #362 from
 mcsheffrey/feat-documentation-cookbook

React Tips documentation
---
 docs/README.md                                |  1 +
 docs/_config.yml                              | 29 +++++++++
 docs/_includes/nav_docs.html                  | 15 +++++
 docs/_layouts/default.html                    |  1 +
 docs/_layouts/tips.html                       | 25 ++++++++
 docs/tips/01-introduction.md                  | 13 ++++
 docs/tips/02-inline-styles.md                 | 24 +++++++
 docs/tips/03-if-else-in-JSX.md                | 42 +++++++++++++
 docs/tips/04-self-closing-tag.md              | 14 +++++
 .../05-maximum-number-of-jsx-root-nodes.md    | 12 ++++
 docs/tips/06-style-props-value-px.md          | 29 +++++++++
 docs/tips/07-children-props-type.md           | 49 +++++++++++++++
 docs/tips/08-controlled-input-null-value.md   | 24 +++++++
 ...ceiveProps-not-triggered-after-mounting.md | 12 ++++
 ...rops-in-getInitialState-as-anti-pattern.md | 62 +++++++++++++++++++
 docs/tips/11-dom-event-listeners.md           | 44 +++++++++++++
 docs/tips/12-initial-ajax.md                  | 47 ++++++++++++++
 docs/tips/13-false-in-jsx.md                  | 32 ++++++++++
 18 files changed, 475 insertions(+)
 create mode 100644 docs/_layouts/tips.html
 create mode 100644 docs/tips/01-introduction.md
 create mode 100644 docs/tips/02-inline-styles.md
 create mode 100644 docs/tips/03-if-else-in-JSX.md
 create mode 100644 docs/tips/04-self-closing-tag.md
 create mode 100644 docs/tips/05-maximum-number-of-jsx-root-nodes.md
 create mode 100644 docs/tips/06-style-props-value-px.md
 create mode 100644 docs/tips/07-children-props-type.md
 create mode 100644 docs/tips/08-controlled-input-null-value.md
 create mode 100644 docs/tips/09-componentWillReceiveProps-not-triggered-after-mounting.md
 create mode 100644 docs/tips/10-props-in-getInitialState-as-anti-pattern.md
 create mode 100644 docs/tips/11-dom-event-listeners.md
 create mode 100644 docs/tips/12-initial-ajax.md
 create mode 100644 docs/tips/13-false-in-jsx.md

diff --git a/docs/README.md b/docs/README.md
index 4db50f03e119e..3d14a9bfd8419 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,6 +21,7 @@ Once you have RubyGems and installed Bundler (via `gem install bundler`), use it
 ```sh
 $ cd react/docs
 $ bundle install # Might need sudo.
+$ npm install # Might need sudo.
 ```
 
 ### Instructions
diff --git a/docs/_config.yml b/docs/_config.yml
index e99f4538a4fc0..35d586129fd72 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -69,3 +69,32 @@ nav_docs_sections:
     title: Event System
   - id: dom-differences
     title: DOM Differences
+nav_tips:
+- title: Tips
+  items:
+  - id: introduction
+    title: Introduction
+  - id: inline-styles
+    title: Inline Styles
+  - id: if-else-in-JSX
+    title: If-Else in JSX
+  - id: self-closing-tag
+    title: Self-Closing Tag
+  - id: maximum-number-of-jsx-root-nodes
+    title: Maximum Number of JSX Root Nodes
+  - id: style-props-value-px
+    title: Shorthand for Specifying Pixel Values in style props
+  - id: children-props-type
+    title: Type of the Children props
+  - id: controlled-input-null-value
+    title: Value of null for Controlled Input
+  - id: componentWillReceiveProps-not-triggered-after-mounting
+    title: componentWillReceiveProps Not Triggered After Mounting
+  - id: props-in-getInitialState-as-anti-pattern
+    title: Props in getInitialState Is an Anti-Pattern
+  - id: dom-event-listeners
+    title: DOM Event Listeners in a Component
+  - id: initial-ajax
+    title: Load Initial Data via AJAX
+  - id: false-in-jsx
+    title: False in JSX
diff --git a/docs/_includes/nav_docs.html b/docs/_includes/nav_docs.html
index e71ece3cb223e..98e1a15197e21 100644
--- a/docs/_includes/nav_docs.html
+++ b/docs/_includes/nav_docs.html
@@ -1,4 +1,5 @@
 <div class="nav-docs">
+  <!-- Docs Nav -->
   {% for section in site.nav_docs_sections %}
     <div class="nav-docs-section">
       <h3>{{ section.title }}</h3>
@@ -24,4 +25,18 @@ <h3>{{ section.title }}</h3>
       </ul>
     </div>
   {% endfor %}
+
+  <!-- Tips Nav -->
+  {% for section in site.nav_tips %}
+    <div class="nav-docs-section">
+      <h3>{{ section.title }}</h3>
+      <ul>
+        {% for item in section.items %}
+          <li>
+            <a href="/react/tips/{{ item.id }}.html"{% if page.id == item.id %} class="active"{% endif %}>{{ item.title }}</a>
+          </li>
+        {% endfor %}
+      </ul>
+    </div>
+  {% endfor %}
 </div>
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 61b06b8adb1e0..f013a7286c2d8 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -74,6 +74,7 @@
     </footer>
   </div>
   <div id="fb-root"></div>
+
   <script>
     (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
     (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
diff --git a/docs/_layouts/tips.html b/docs/_layouts/tips.html
new file mode 100644
index 0000000000000..74cf0be25abd1
--- /dev/null
+++ b/docs/_layouts/tips.html
@@ -0,0 +1,25 @@
+---
+layout: default
+sectionid: tips
+---
+
+<section class="content wrap documentationContent">
+  {% include nav_docs.html %}
+
+  <div class="inner-content">
+    <h1>{{ page.title }}</h1>
+    <div class="subHeader">{{ page.description }}</div>
+    {{ content }}
+
+    <div class="docs-prevnext">
+      {% if page.prev %}
+        <a class="docs-prev" href="/react/tips/{{ page.prev }}">&larr; Prev</a>
+      {% endif %}
+      {% if page.next %}
+        <a class="docs-next" href="/react/tips/{{ page.next }}">Next &rarr;</a>
+      {% endif %}
+    </div>
+
+    <div class="fb-comments" data-width="650" data-num-posts="10" data-href="{{ site.url }}{{ site.baseurl }}{{ page.url }}"></div>
+  </div>
+</section>
diff --git a/docs/tips/01-introduction.md b/docs/tips/01-introduction.md
new file mode 100644
index 0000000000000..c2e86c6eae3d2
--- /dev/null
+++ b/docs/tips/01-introduction.md
@@ -0,0 +1,13 @@
+---
+id: introduction
+title: Introduction
+layout: tips
+permalink: introduction.html
+next: inline-styles.html
+---
+
+The React tips section provides bite-sized information that can answer lots of questions you might have and warn you against common pitfalls.
+
+## Contributing
+
+Submit a pull request to the [React repository](https://github.com/facebook/react) following the [current tips](https://github.com/facebook/react/tree/master/docs) entries' style. If you have a recipe that needs review prior to submitting a PR you can find help in the [#reactjs channel on freenode](irc://chat.freenode.net/reactjs) or the [reactjs Google group](http://groups.google.com/group/reactjs). Also, check the [Tips Wiki](https://github.com/facebook/react/wiki/Tips-(Previously-Cookbook)) for entries in-progress and general guidelines on writing React tips.
diff --git a/docs/tips/02-inline-styles.md b/docs/tips/02-inline-styles.md
new file mode 100644
index 0000000000000..1f61596a54186
--- /dev/null
+++ b/docs/tips/02-inline-styles.md
@@ -0,0 +1,24 @@
+---
+id: inline-styles
+title: Inline Styles
+layout: tips
+permalink: inline-styles.html
+next: if-else-in-JSX.html
+prev: introduction.html
+---
+
+In React, inline styles are not specified as a string. Instead they are specified with an object whose key is the camelCased version of the style name, and whose value is the style's value, usually a string ([more on that later](/react/tips/style-props-value-px.html)):
+
+```js
+/** @jsx React.DOM */
+
+var divStyle = {
+  color: 'white',
+  backgroundImage: 'url(' + imgUrl + ')',
+  WebkitTransition: 'all' // note the capital 'W' here
+};
+
+React.renderComponent(<div style={divStyle}>Hello World!</div>, mountNode);
+```
+
+Style keys are camelCased in order to be consistent with accessing the properties on DOM nodes from JS (e.g. `node.style.backgroundImage`). Vendor prefixes should begin with a capital letter. This is why `WebkitTransition` has an uppercase "W".
diff --git a/docs/tips/03-if-else-in-JSX.md b/docs/tips/03-if-else-in-JSX.md
new file mode 100644
index 0000000000000..5a04c9f60e311
--- /dev/null
+++ b/docs/tips/03-if-else-in-JSX.md
@@ -0,0 +1,42 @@
+---
+id: if-else-in-JSX
+title: If-Else in JSX
+layout: tips
+permalink: if-else-in-JSX.html
+prev: inline-styles.html
+next: self-closing-tag.html
+---
+
+`if-else` statements don't work inside JSX. This is because JSX is just syntactic sugar for function calls and object construction. Take this basic example:
+
+```js
+/** @jsx React.DOM */
+
+// This JSX:
+React.renderComponent(<div id="msg">Hello World!</div>, mountNode);
+
+// Is transformed to this JS:
+React.renderComponent(React.DOM.div({id:"msg"}, "Hello World!"), mountNode);
+```
+
+This means that `if` statements don't fit in. Take this example:
+
+```js
+/** @jsx React.DOM */
+
+// This JSX:
+<div id={if (condition) { 'msg' }}>Hello World!</div>
+
+// Is transformed to this JS:
+React.DOM.div({id: if (condition) { 'msg' }}, "Hello World!");
+```
+
+That's not valid JS. You probably want to make use of a ternary expression:
+
+```js
+/** @jsx React.DOM */
+
+React.renderComponent(<div id={condition ? 'msg' : ''}>Hello World!</div>, mountNode);
+```
+
+Try using it today with the [JSX compiler](/react/jsx-compiler.html).
diff --git a/docs/tips/04-self-closing-tag.md b/docs/tips/04-self-closing-tag.md
new file mode 100644
index 0000000000000..7c0a72fa8e9d8
--- /dev/null
+++ b/docs/tips/04-self-closing-tag.md
@@ -0,0 +1,14 @@
+---
+id: self-closing-tag
+title: Self-Closing Tag
+layout: tips
+permalink: self-closing-tag.html
+prev: if-else-in-JSX.html
+next: maximum-number-of-jsx-root-nodes.html
+---
+
+In JSX, `<MyComponent />` alone is valid while `<MyComponent>` isn't. All tags must be closed, either with the self-closing format or with a corresponding closing tag (`</MyComponent>`).
+
+> Note:
+>
+> Every React component can be self-closing: `<div />`. `<div></div>` is also an equivalent.
diff --git a/docs/tips/05-maximum-number-of-jsx-root-nodes.md b/docs/tips/05-maximum-number-of-jsx-root-nodes.md
new file mode 100644
index 0000000000000..0ce319e6330be
--- /dev/null
+++ b/docs/tips/05-maximum-number-of-jsx-root-nodes.md
@@ -0,0 +1,12 @@
+---
+id: maximum-number-of-jsx-root-nodes
+title: Maximum Number of JSX Root Nodes
+layout: tips
+permalink: maximum-number-of-jsx-root-nodes.html
+prev: self-closing-tag.html
+next: style-props-value-px.html
+---
+
+Currently, in a component's `render`, you can only return one node; if you have, say, a list of `div`s to return, you must wrap your components within a `div`, `span` or any other component.
+
+Don't forget that JSX compiles into regular js; returning two functions doesn't really make syntactic sense. Likewise, don't put more than one child in a ternary.
diff --git a/docs/tips/06-style-props-value-px.md b/docs/tips/06-style-props-value-px.md
new file mode 100644
index 0000000000000..233e29ff37d2b
--- /dev/null
+++ b/docs/tips/06-style-props-value-px.md
@@ -0,0 +1,29 @@
+---
+id: style-props-value-px
+title: Shorthand for Specifying Pixel Values in style props
+layout: tips
+permalink: style-props-value-px.html
+prev: maximum-number-of-jsx-root-nodes.html
+next: children-props-type.html
+---
+
+When specifying a pixel value for your inline `style` prop, React automatically appends the string "px" for you after your number value, so this works:
+
+```js
+/** @jsx React.DOM */
+
+var divStyle = {height: 10}; // rendered as "height:10px"
+React.renderComponent(<div style={divStyle}>Hello World!</div>, mountNode);
+```
+
+See [Inline Styles](/react/tips/inline-styles.html) for more info.
+
+Sometimes you _do_ want to keep the CSS properties unitless. Here's a list of properties that won't get the automatic "px" suffix:
+
+- `fillOpacity`
+- `fontWeight`
+- `lineHeight`
+- `opacity`
+- `orphans`
+- `zIndex`
+- `zoom`
diff --git a/docs/tips/07-children-props-type.md b/docs/tips/07-children-props-type.md
new file mode 100644
index 0000000000000..8c4549acd7184
--- /dev/null
+++ b/docs/tips/07-children-props-type.md
@@ -0,0 +1,49 @@
+---
+id: children-props-type
+title: Type of the Children props
+layout: tips
+permalink: children-props-type.html
+prev: style-props-value-px.html
+next: controlled-input-null-value.html
+---
+
+Usually, a component's children (`this.props.children`) is an array of components:
+
+```js
+/** @jsx React.DOM */
+
+var GenericWrapper = React.createClass({
+  componentDidMount: function() {
+    console.log(Array.isArray(this.props.children)); // => true
+  },
+  render: function() {
+    return <div />;
+  }
+});
+
+React.renderComponent(
+  <GenericWrapper><span/><span/><span/></GenericWrapper>,
+  mountNode
+);
+```
+
+However, when there is only a single child, `this.props.children` will be the single child component itself _without the array wrapper_. This saves an array allocation.
+
+```js
+/** @jsx React.DOM */
+
+var GenericWrapper = React.createClass({
+  componentDidMount: function() {
+    console.log(Array.isArray(this.props.children)); // => false
+
+    // warning: yields 5 for length of the string 'hello', not 1 for the
+    // length of the non-existant array wrapper!
+    console.log(this.props.children.length);
+  },
+  render: function() {
+    return <div />;
+  }
+});
+
+React.renderComponent(<GenericWrapper>hello</GenericWrapper>, mountNode);
+```
diff --git a/docs/tips/08-controlled-input-null-value.md b/docs/tips/08-controlled-input-null-value.md
new file mode 100644
index 0000000000000..37c8efb34ca5b
--- /dev/null
+++ b/docs/tips/08-controlled-input-null-value.md
@@ -0,0 +1,24 @@
+---
+id: controlled-input-null-value
+title: Value of null for Controlled Input
+layout: tips
+permalink: controlled-input-null-value.html
+prev: children-props-type.html
+next: componentWillReceiveProps-not-triggered-after-mounting.html
+---
+
+Specifying the `value` prop on a [controlled component](/react/docs/forms.html) prevents the user from changing the input unless you desire so.
+
+You might have run into a problem where `value` is specified, but the input can still be changed without consent. In this case, you might have accidentally set `value` to `undefined` or `null`.
+
+The snippet below shows this phenomenon; after a second, the text becomes editable.
+
+```js
+/** @jsx React.DOM */
+
+React.renderComponent(<input value="hi" />, mountNode);
+
+setTimeout(function() {
+  React.renderComponent(<input value={null} />, mountNode);
+}, 2000);
+```
diff --git a/docs/tips/09-componentWillReceiveProps-not-triggered-after-mounting.md b/docs/tips/09-componentWillReceiveProps-not-triggered-after-mounting.md
new file mode 100644
index 0000000000000..b4b1cd5c1a648
--- /dev/null
+++ b/docs/tips/09-componentWillReceiveProps-not-triggered-after-mounting.md
@@ -0,0 +1,12 @@
+---
+id: componentWillReceiveProps-not-triggered-after-mounting
+title: componentWillReceiveProps Not Triggered After Mounting
+layout: tips
+permalink: componentWillReceiveProps-not-triggered-after-mounting.html
+prev: controlled-input-null-value.html
+next: props-in-getInitialState-as-anti-pattern.html
+---
+
+`componentWillReceiveProps` isn't triggered after the node is put on scene. This is by design. Check out [other lifecycle methods](/react/docs/component-specs.html) for the one that suits your needs.
+
+The reason for that is because `componentWillReceiveProps` often handles the logic of comparing with the old props and acting upon changes; not triggering it at mounting (where there are no old props) helps in defining what the method does.
diff --git a/docs/tips/10-props-in-getInitialState-as-anti-pattern.md b/docs/tips/10-props-in-getInitialState-as-anti-pattern.md
new file mode 100644
index 0000000000000..097fbc718f2c3
--- /dev/null
+++ b/docs/tips/10-props-in-getInitialState-as-anti-pattern.md
@@ -0,0 +1,62 @@
+---
+id: props-in-getInitialState-as-anti-pattern
+title: Props in getInitialState Is an Anti-Pattern
+layout: tips
+permalink: props-in-getInitialState-as-anti-pattern.html
+prev: componentWillReceiveProps-not-triggered-after-mounting.html
+next: dom-event-listeners.html
+---
+
+> Note:
+>
+> This isn't really a React-specific tip, as such anti-patterns often occur in code in general; in this case, React simply points them out more clearly.
+
+Using props, passed down from parent, to generate state in `getInitialState` often leads to duplication of "source of truth", i.e. where the real data is. Whenever possible, compute values on-the-fly to ensure that they don't get out of sync later on and cause maintenance trouble.
+
+Bad example:
+
+```js
+/** @jsx React.DOM */
+
+var MessageBox = React.createClass({
+  getInitialState: function() {
+    return {nameWithQualifier: "Mr. " + this.props.name};
+  },
+  render: function() {
+    return <div>{this.state.nameWithQualifier}</div>;
+  }
+});
+
+React.renderComponent(<MessageBox name="Rogers"/>, mountNode);
+```
+
+Better:
+
+```js
+/** @jsx React.DOM */
+
+var MessageBox = React.createClass({
+  render: function() {
+    return <div>{"Mr. " + this.props.name}</div>;
+  }
+});
+
+React.renderComponent(<MessageBox name="Rogers"/>, mountNode);
+```
+
+For more complex logic:
+
+```js
+/** @jsx React.DOM */
+
+var MessageBox = React.createClass({
+  render: function() {
+    return <div>{this.getNameWithQualifier(this.props.name)}</div>;
+  },
+  getNameWithQualifier: function(name) {
+    return 'Mr. ' + name;
+  }
+});
+
+React.renderComponent(<MessageBox name="Rogers"/>, mountNode);
+```
diff --git a/docs/tips/11-dom-event-listeners.md b/docs/tips/11-dom-event-listeners.md
new file mode 100644
index 0000000000000..46e577fff5e01
--- /dev/null
+++ b/docs/tips/11-dom-event-listeners.md
@@ -0,0 +1,44 @@
+---
+id: dom-event-listeners
+title: DOM Event Listeners in a Component
+layout: tips
+permalink: dom-event-listeners.html
+prev: props-in-getInitialState-as-anti-pattern.html
+next: initial-ajax.html
+---
+
+> Note:
+>
+> This entry shows how to attach DOM events not provided by React ([check here for more info](/react/docs/events.html)). This is good for integrations with other libraries such as jQuery.
+
+Try to resize the window:
+
+```js
+/** @jsx React.DOM */
+
+var Box = React.createClass({
+  getInitialState: function() {
+    return {windowWidth: window.innerWidth};
+  },
+
+  handleResize: function(e) {
+    this.setState({windowWidth: window.innerWidth});
+  },
+
+  componentDidMount: function() {
+    window.addEventListener('resize', this.handleResize);
+  },
+
+  componentWillUnmount: function() {
+    window.removeEventListener('resize', this.handleResize);
+  },
+
+  render: function() {
+    return <div>Current window width: {this.state.windowWidth}</div>;
+  }
+});
+
+React.renderComponent(<Box />, mountNode);
+```
+
+`componentDidMount` is called after the component is mounted and has a DOM representation. This is often a place where you would attach generic DOM events.
diff --git a/docs/tips/12-initial-ajax.md b/docs/tips/12-initial-ajax.md
new file mode 100644
index 0000000000000..c608dc6accbf2
--- /dev/null
+++ b/docs/tips/12-initial-ajax.md
@@ -0,0 +1,47 @@
+---
+id: initial-ajax
+title: Load Initial Data via AJAX
+layout: tips
+permalink: initial-ajax.html
+prev: dom-event-listeners.html
+next: false-in-jsx.html
+---
+
+Fetch data in `componentDidMount`. When the response arrives, store the data in state, triggering a render to update your UI.
+
+This example fetches the desired Github user's lastest gist:
+
+```js
+/** @jsx React.DOM */
+
+var UserGist = React.createClass({
+  getInitialState: function() {
+    return {
+      username: '',
+      lastGistUrl: ''
+    };
+  },
+  componentDidMount: function() {
+    $.get(this.props.source, function(result) {
+      var lastGist = result[0];
+      this.setState({
+        username: lastGist.user.login,
+        lastGistUrl: lastGist.html_url
+      });
+    }.bind(this));
+  },
+  render: function() {
+    return (
+      <div>
+        {this.state.username}'s last gist is
+        <a href={this.state.lastGistUrl}>here</a>.
+      </div>
+    );
+  }
+});
+
+React.renderComponent(
+  <UserGist source="https://api.github.com/users/octocat/gists" />,
+  mountNode
+);
+```
diff --git a/docs/tips/13-false-in-jsx.md b/docs/tips/13-false-in-jsx.md
new file mode 100644
index 0000000000000..0c86bddf55770
--- /dev/null
+++ b/docs/tips/13-false-in-jsx.md
@@ -0,0 +1,32 @@
+---
+id: false-in-jsx
+title: False in JSX
+layout: tips
+permalink: false-in-jsx.html
+prev: initial-ajax.html
+---
+
+Here's how `false` renders in different contexts:
+
+Renders as `id="false"`:
+
+```js
+/** @jsx React.DOM */
+React.renderComponent(<div id={false} />, mountNode);
+```
+
+String "false" as input value:
+
+```js
+/** @jsx React.DOM */
+React.renderComponent(<input value={false} />, mountNode);
+```
+
+No child:
+
+```js
+/** @jsx React.DOM */
+React.renderComponent(<div>{false}</div>, mountNode);
+```
+
+The reason why this one doesn't render as the string `"false"` as a `div` child is to allow the more common use-case: `<div>{x > 1 && 'You have more than one item'}</div>`.