{"body":"","commit":{"authoredAt":"2016-10-27T02:02:14+01:00","revision":"cc3dc21be01bd8f1e4d74d16a0cd795357c0be89","subject":"Tweak Forms","authorName":"Dan Abramov","shortRevision":"cc3dc21be0","authorEmail":"dan.abramov@gmail.com"},"parents":["552033e33b6a3f6eddc4873fa2140b8ad2e090ea"],"files":[{"path":"docs\/docs\/forms.md","status":"M"},{"path":"docs\/docs\/reference-events.md","status":"M"}],"patch":"diff --git a\/docs\/docs\/forms.md b\/docs\/docs\/forms.md\nindex a8c105191f..b9d8c0c658 100644\n--- a\/docs\/docs\/forms.md\n+++ b\/docs\/docs\/forms.md\n@@ -9,7 +9,7 @@ redirect_from: \"tips\/controlled-input-null-value.html\"\n \n Form components such as ``, `

`, 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.\n \n-Two types of form components:\n+There are two types of form components:\n \n * Controlled Components\n * Uncontrolled Components\n@@ -20,15 +20,19 @@ You can jump directly to <a href=\"\/react\/docs\/forms.html#examples\">examples<\/a>.\n \n A **controlled** form component provides a `value` prop. A **controlled** component does not maintain its own internal state; the component renders purely based on props.\n \n-```javascript\n+```javascript{5}\n render() {\n-  return <input type=\"text\" value=\"Hello!\" \/>;\n+  return (\n+    <input\n+      type=\"text\"\n+      value=\"Hello!\" \/>\n+  );\n }\n ```\n \n-User input has no effect on the rendered element because React has declared the value to be \"Hello!\".\n+If you try to run this example, you will notice that the input doesn't change as you type. This is because the component has declared the input's `value` to always be `\"Hello!\"`.\n \n-To update the value in response to user input, you would use the `onChange` event to save the new value, then pass that to the `value` prop of the form:\n+To update the value in response to user input, you would use the `onChange` event to save the new value, then pass that to the `value` prop of the input:\n \n ```javascript{10,22,23}\n class Form extends React.Component {\n@@ -54,34 +58,53 @@ class Form extends React.Component {\n           placeholder=\"Hello!\"\n           value={this.state.value}\n           onChange={this.handleChange} \/>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n \n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n \n-[Try it on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/QKkJva?editors=0010)\n+[Try it on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/NRmBmq?editors=0010)\n \n In this example, we are accepting the value provided by the user and updating the `value` prop of the `<input>` component. This pattern makes it easy to implement interfaces that respond to or validate user interactions. For example:\n \n-```javascript\n+```javascript{3}\n   handleChange(event) {\n-    this.setState({value: event.target.value.substr(0, 140)});\n+    this.setState({\n+      value: event.target.value.substr(0, 140)\n+    });\n   }\n ```\n \n This would accept user input and truncate the value to the first 140 characters.\n \n+Controlled components also let us reset inputs to arbitrary values by setting the state:\n+\n+```javascript{3}\n+  handleClearClick() {\n+    this.setState({\n+      value: ''\n+    });\n+  }\n+```\n+\n ### Potential Issues With Checkboxes and Radio Buttons\n \n-Be aware that, in an attempt to normalize change handling for checkbox and radio inputs, React uses a `click` event in place of a `change` event. For the most part this behaves as expected, except when calling `preventDefault` in a `change` handler. `preventDefault` stops the browser from visually updating the input, even if `checked` gets toggled. This can be worked around either by removing the call to `preventDefault`, or putting the toggle of `checked` in a `setTimeout`.\n+Be aware that, in an attempt to normalize change handling for checkbox and radio inputs, React listens to a `click` browser event to implement the `onChange` event.\n+\n+For the most part this behaves as expected, except when calling `preventDefault` in a `change` handler. `preventDefault` stops the browser from visually updating the input, even if `checked` gets toggled. This can be worked around either by removing the call to `preventDefault`, or putting the toggle of `checked` in a `setTimeout`.\n \n ## Uncontrolled Components\n \n-Form components that do not provide a `value` prop are *uncontrolled*.\n+Form components that do not provide a `value` prop are **uncontrolled**.\n \n The example below renders an `<input>` control with an empty value. Any user input will be immediately reflected by the rendered element.\n \n@@ -95,7 +118,7 @@ An **uncontrolled** component manages its own state.\n \n If you wanted to listen to updates to the value, you could use the `onChange` event just like you can with controlled components. However, you would _not_ pass the value you saved to the component.\n \n-```javascript{10,22}\n+```javascript{25}\n class Form extends React.Component {\n   constructor(props) {\n     super(props);\n@@ -105,6 +128,8 @@ class Form extends React.Component {\n   }\n \n   handleChange(event) {\n+    \/\/ Note: with uncontrolled inputs, you don't\n+    \/\/ have to put the value in the state.\n     this.setState({value: event.target.value});\n   }\n \n@@ -115,21 +140,29 @@ class Form extends React.Component {\n   render() {\n     return (\n       <div>\n-        <input type=\"text\"\n+        <input\n+          type=\"text\"\n           placeholder=\"Hello!\"\n           onChange={this.handleChange} \/>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n \n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n \n-[Try it on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/XjxyoL?editors=0010)\n+[Try it on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/pEBOJR?editors=0010)\n+\n+While this example puts value in the state so we can later read it in `handleSubmit()`, uncontrolled form components don't require this. You may completely omit an `onChange` handler and instead read the input value using [DOM references](\/react\/docs\/refs-and-the-dom.html), an advanced feature discussed later.\n \n-###Default Values\n+### Default Values\n \n To initialize an uncontrolled component with a non-empty value, you can supply a `defaultValue` prop.\n \n@@ -190,7 +223,7 @@ Since this method describes the view at any point in time, the value of the text\n In HTML, the value of `<textarea>` is usually set using its children:\n \n ```html\n-  \n+  \n   <textarea name=\"description\">This is the description.<\/textarea>\n ```\n \n@@ -220,16 +253,16 @@ To make an uncontrolled component, `defaultValue` is used instead.\n >\n > You can pass an array into the `value` attribute, allowing you to select multiple options in a `select` tag: `<select multiple={true} value={['B', 'C']}>`.\n \n-### Imperative operations\n+### Imperative Operations\n \n If you need to imperatively perform an operation, you have to obtain a [reference to the DOM node](\/react\/docs\/more-about-refs.html#the-ref-callback-attribute).\n For instance, if you want to imperatively submit a form, one approach would be to attach a `ref` to the `form` element and manually call `form.submit()`.\n \n ## Examples\n \n-### Basic Controlled Input\n+### Controlled Input\n \n-```javascript\n+```javascript{10,23,24}\n class Form extends React.Component {\n   constructor(props) {\n     super(props);\n@@ -237,6 +270,7 @@ class Form extends React.Component {\n     this.handleChange = this.handleChange.bind(this);\n     this.handleSubmit = this.handleSubmit.bind(this);\n   }\n+\n   handleChange(event) {\n     this.setState({value: event.target.value});\n   }\n@@ -254,21 +288,25 @@ class Form extends React.Component {\n           value={this.state.value}\n           onChange={this.handleChange}\n         \/>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n \n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n \n-[Try this on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/JRmZjz?editors=0010)\n-\n+[Try it out on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/JRVaYB?editors=0010)\n \n-### Basic Controlled Textarea\n+### Controlled Textarea\n \n-```javascript\n+```javascript{10,22,23}\n class Form extends React.Component {\n   constructor(props) {\n     super(props);\n@@ -293,20 +331,26 @@ class Form extends React.Component {\n           value={this.state.value}\n           onChange={this.handleChange}\n         \/>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <br \/>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n \n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n \n-[Try this on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/kkAQPp?editors=0010)\n+[Try it out on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/NRmLxN?editors=0010)\n \n-### Basic Uncontrolled Select\n+### Controlled Select\n \n-```javascript\n+```javascript{10,20}\n class Form extends React.Component {\n   constructor(props) {\n     super(props);\n@@ -331,20 +375,25 @@ class Form extends React.Component {\n           <option value=\"B\">Banana<\/option>\n           <option value=\"C\">Cranberry<\/option>\n         <\/select>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n \n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n \n-[Try this on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/pExQbL?editors=0010)\n+[Try it out on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/qawrbr?editors=0010)\n \n-### Basic Radio Button\n+### Uncontrolled Radio Button\n \n-```javascript\n+```javascript{25,34,35,44}\n class Form extends React.Component {\n   constructor(props) {\n     super(props);\n@@ -365,38 +414,53 @@ class Form extends React.Component {\n     return (\n       <div>\n         <label>\n-          <input type=\"radio\" value=\"A\" id=\"choice-a\"\n+          <input\n+            type=\"radio\"\n+            name=\"choice\"\n+            value=\"A\"\n             onChange={this.handleChange} \/>\n           Option A\n         <\/label>\n         <br \/>\n         <label>\n-          <input type=\"radio\" value=\"B\" id=\"choice-b\"\n-            onChange={this.handleChange} defaultChecked={true} \/>\n+          <input\n+            type=\"radio\"\n+            name=\"choice\"\n+            value=\"B\"\n+            onChange={this.handleChange}\n+            defaultChecked={true} \/>\n           Option B\n         <\/label>\n         <br \/>\n         <label>\n-          <input type=\"radio\" value=\"C\" id=\"choice-c\"\n-          onChange={this.handleChange} \/> \n+          <input\n+            type=\"radio\"\n+            name=\"choice\"\n+            value=\"C\"\n+            onChange={this.handleChange} \/> \n           Option C\n         <\/label>\n-        <br \/><br \/>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <br \/>\n+        <br \/>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n \n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n \n-[Try this on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/WGaYVg?editors=0010)\n+[Try it out on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/ozOPLJ?editors=0010)\n \n+### Uncontrolled Checkbox\n \n-### Basic Uncontrolled Checkbox\n-\n-```javascript\n+```javascript{37,45,46,54}\n class Form extends React.Component {\n   constructor(props) {\n     super(props);\n@@ -406,10 +470,16 @@ class Form extends React.Component {\n   }\n \n   handleChange(event) {\n-    let value = event.target.value;\n-    let checked = this.state.checked; \/\/ copy \n-    if (!checked[value]) { checked[value] = true; } else { checked[value] = false; }\n-    this.setState({checked: checked})\n+    const value = event.target.value;\n+    \/\/ Copy the object so we don't mutate the old state.\n+    \/\/ (This requires an Object.assign polyfill):\n+    const checked = Object.assign({}, this.state.checked)\n+    if (!checked[value]) {\n+      checked[value] = true;\n+    } else {\n+      checked[value] = false;\n+    };\n+    this.setState({checked});\n   }\n \n   handleSubmit(event) {\n@@ -424,36 +494,43 @@ class Form extends React.Component {\n     return (\n       <div>\n         <label>\n-          <input type=\"checkbox\" value=\"A\"\n+          <input\n+            type=\"checkbox\"\n+            value=\"A\"\n             onChange={this.handleChange} \/> \n           Option A\n         <\/label>\n         <br \/>\n         <label>\n-          <input type=\"checkbox\" value=\"B\"\n-          onChange={this.handleChange} defaultChecked={true} \/> \n+          <input\n+            type=\"checkbox\"\n+            value=\"B\"\n+            onChange={this.handleChange}\n+            defaultChecked={true} \/> \n           Option B\n         <\/label>\n         <br \/>\n-        <label><input type=\"checkbox\" value=\"C\"\n+        <label>\n+        <input\n+          type=\"checkbox\"\n+          value=\"C\"\n           onChange={this.handleChange} \/> \n           Option C\n         <\/label>\n-        <br \/><br \/>\n-        <button onClick={this.handleSubmit}>Submit<\/button>\n+        <br \/>\n+        <br \/>\n+        <button onClick={this.handleSubmit}>\n+          Submit\n+        <\/button>\n       <\/div>\n     );\n   }\n }\n-ReactDOM.render(<Form \/>, document.getElementById('root'));\n-```\n-\n-[Try it on CodePen.](https:\/\/codepen.io\/ericnakagawa\/pen\/kkAzPO?editors=0010)\n-\n-### Form Events\n-\n-Event names:\n \n+ReactDOM.render(\n+  <Form \/>,\n+  document.getElementById('root')\n+);\n ```\n-onChange onInput onSubmit\n-```\n+\n+[Try it on CodePen.](https:\/\/codepen.io\/gaearon\/pen\/rrbkWz?editors=0010)\ndiff --git a\/docs\/docs\/reference-events.md b\/docs\/docs\/reference-events.md\nindex b68e65c84b..6e275db9b5 100644\n--- a\/docs\/docs\/reference-events.md\n+++ b\/docs\/docs\/reference-events.md\n@@ -35,7 +35,7 @@ string type\n >\n > As of v0.14, returning `false` from an event handler will no longer stop event propagation. Instead, `e.stopPropagation()` or `e.preventDefault()` should be triggered manually, as appropriate.\n \n-### Event pooling\n+### Event Pooling\n \n The `SyntheticEvent` is pooled. This means that the `SyntheticEvent` object will be reused and all properties will be nullified after the event callback has been invoked.\n This is for performance reasons.\n"}</article></body></html>

dillon1000/react

Files changed