{"body":"Use controlled components in tutorial","files":[{"path":"docs\/docs\/tutorial.md","status":"M"}],"parents":["60cba8fcf74d10107ff8978b225a9b06865bba17","3812b95450fac28fb7c17d9cc57ba2edf9170aac"],"patch":"diff --git a\/docs\/docs\/tutorial.md b\/docs\/docs\/tutorial.md\nindex 55b6e0b86f..2c8c121b54 100644\n--- a\/docs\/docs\/tutorial.md\n+++ b\/docs\/docs\/tutorial.md\n@@ -492,28 +492,91 @@ var CommentForm = React.createClass({\n });\n ```\n \n-Let's make the form interactive. When the user submits the form, we should clear it, submit a request to the server, and refresh the list of comments. To start, let's listen for the form's submit event and clear it.\n+#### Controlled components\n+\n+With the traditional DOM, `input` elements are rendered and the browser manages the state (its rendered value). As a result, the state of the actual DOM will differ from that of the component. This is not ideal as the state of the view will differ from that of the component. In React, components should always represent the state of the view and not only at the point of initialization.\n+\n+Hence, we will be using `this.state` to save the user's input as it is entered. We define an initial `state` with two properties `author` and `text` and set them to be empty strings. In our `` elements, we set the `value` prop to reflect the `state` of the component and attach `onChange` handlers to them. These `` elements with a `value` set are called controlled components. Read more about controlled components on the [Forms article](\/react\/docs\/forms.html#controlled-components).\n \n-```javascript{3-14,16-19}\n+```javascript{3-11,15-26}\n \/\/ tutorial16.js\n var CommentForm = React.createClass({\n+ getInitialState: function() {\n+ return {author: '', text: ''};\n+ },\n+ handleAuthorChange: function(e) {\n+ this.setState({author: e.target.value});\n+ },\n+ handleTextChange: function(e) {\n+ this.setState({text: e.target.value});\n+ },\n+ render: function() {\n+ return (\n+

\n+ \n+ \n+ \n+ <\/form>\n+ );\n+ }\n+});\n+```\n+\n+#### Events\n+\n+React attaches event handlers to components using a camelCase naming convention. We attach `onChange` handlers to the two `` elements. Now, as the user enters text into the `` fields, the attached `onChange` callbacks are fired and the `state` of the component is modified. Subsequently, the rendered value of the `input` element will be updated to reflect the current component `state`.\n+\n+#### Submitting the form\n+\n+Let's make the form interactive. When the user submits the form, we should clear it, submit a request to the server, and refresh the list of comments. To start, let's listen for the form's submit event and clear it.\n+\n+```javascript{12-21,24}\n+\/\/ tutorial17.js\n+var CommentForm = React.createClass({\n+ getInitialState: function() {\n+ return {author: '', text: ''};\n+ },\n+ handleAuthorChange: function(e) {\n+ this.setState({author: e.target.value});\n+ },\n+ handleTextChange: function(e) {\n+ this.setState({text: e.target.value});\n+ },\n handleSubmit: function(e) {\n e.preventDefault();\n- var author = this.refs.author.value.trim();\n- var text = this.refs.text.value.trim();\n+ var author = this.state.author.trim();\n+ var text = this.state.text.trim();\n if (!text || !author) {\n return;\n }\n \/\/ TODO: send request to the server\n- this.refs.author.value = '';\n- this.refs.text.value = '';\n- return;\n+ this.setState({author: '', text: ''});\n },\n render: function() {\n return (\n \n- \n- \n+ \n+ \n \n <\/form>\n );\n@@ -521,24 +584,18 @@ var CommentForm = React.createClass({\n });\n ```\n \n-##### Events\n-\n-React attaches event handlers to components using a camelCase naming convention. We attach an `onSubmit` handler to the form that clears the form fields when the form is submitted with valid input.\n+We attach an `onSubmit` handler to the form that clears the form fields when the form is submitted with valid input.\n \n Call `preventDefault()` on the event to prevent the browser's default action of submitting the form.\n \n-##### Refs\n-\n-We use the `ref` attribute to assign a name to a child component and `this.refs` to reference the DOM node.\n-\n-##### Callbacks as props\n+#### Callbacks as props\n \n When a user submits a comment, we will need to refresh the list of comments to include the new one. It makes sense to do all of this logic in `CommentBox` since `CommentBox` owns the state that represents the list of comments.\n \n We need to pass data from the child component back up to its parent. We do this in our parent's `render` method by passing a new callback (`handleCommentSubmit`) into the child, binding it to the child's `onCommentSubmit` event. Whenever the event is triggered, the callback will be invoked:\n \n ```javascript{16-18,31}\n-\/\/ tutorial17.js\n+\/\/ tutorial18.js\n var CommentBox = React.createClass({\n loadCommentsFromServer: function() {\n $.ajax({\n@@ -577,26 +634,43 @@ var CommentBox = React.createClass({\n \n Let's call the callback from the `CommentForm` when the user submits the form:\n \n-```javascript{10}\n-\/\/ tutorial18.js\n+```javascript{19}\n+\/\/ tutorial19.js\n var CommentForm = React.createClass({\n+ getInitialState: function() {\n+ return {author: '', text: ''};\n+ },\n+ handleAuthorChange: function(e) {\n+ this.setState({author: e.target.value});\n+ },\n+ handleTextChange: function(e) {\n+ this.setState({text: e.target.value});\n+ },\n handleSubmit: function(e) {\n e.preventDefault();\n- var author = this.refs.author.value.trim();\n- var text = this.refs.text.value.trim();\n+ var author = this.state.author.trim();\n+ var text = this.state.text.trim();\n if (!text || !author) {\n return;\n }\n this.props.onCommentSubmit({author: author, text: text});\n- this.refs.author.value = '';\n- this.refs.text.value = '';\n- return;\n+ this.setState({author: '', text: ''});\n },\n render: function() {\n return (\n \n- \n- \n+ \n+ \n \n <\/form>\n );\n@@ -607,7 +681,7 @@ var CommentForm = React.createClass({\n Now that the callbacks are in place, all we have to do is submit to the server and refresh the list:\n \n ```javascript{17-28}\n-\/\/ tutorial19.js\n+\/\/ tutorial20.js\n var CommentBox = React.createClass({\n loadCommentsFromServer: function() {\n $.ajax({\n@@ -660,7 +734,7 @@ var CommentBox = React.createClass({\n Our application is now feature complete but it feels slow to have to wait for the request to complete before your comment appears in the list. We can optimistically add this comment to the list to make the app feel faster.\n \n ```javascript{17-23}\n-\/\/ tutorial20.js\n+\/\/ tutorial21.js\n var CommentBox = React.createClass({\n loadCommentsFromServer: function() {\n $.ajax({\n","commit":{"shortRevision":"904e9e3ea6","revision":"904e9e3ea654a811b1d455eed58a3364337c487b","authorName":"Paul O’Shannessy","authorEmail":"paul@oshannessy.com","subject":"Merge pull request #5445 from yangshun\/controlled-components-in-tutorial","authoredAt":"2015-11-17T22:59:40-08:00"}}

dillon1000/react

Files changed