{"commit":{"subject":"Merge pull request #5693 from gaearon\/elements-post","authorName":"Paul O’Shannessy","authoredAt":"2015-12-18T12:42:33-08:00","authorEmail":"paul@oshannessy.com","shortRevision":"bdca170d2a","revision":"bdca170d2a3e8d088a61cbbb8bb291fbff1f23c5"},"files":[{"path":"docs\/_data\/authors.yml","status":"M"},{"path":"docs\/_posts\/2015-12-18-react-components-elements-and-instances.md","status":"A"}],"patch":"diff --git a\/docs\/_data\/authors.yml b\/docs\/_data\/authors.yml\nindex 2b1277a735..5be3ee5b3d 100644\n--- a\/docs\/_data\/authors.yml\n+++ b\/docs\/_data\/authors.yml\n@@ -13,6 +13,9 @@ Daniel15:\n fisherwebdev:\n name: Bill Fisher\n url: https:\/\/twitter.com\/fisherwebdev\n+gaearon:\n+ name: Dan Abramov\n+ url: https:\/\/twitter.com\/dan_abramov\n jaredly:\n name: Jared Forsyth\n url: https:\/\/twitter.com\/jaredforsyth\ndiff --git a\/docs\/_posts\/2015-12-18-react-components-elements-and-instances.md b\/docs\/_posts\/2015-12-18-react-components-elements-and-instances.md\nnew file mode 100644\nindex 0000000000..a69abdaae4\n--- \/dev\/null\n+++ b\/docs\/_posts\/2015-12-18-react-components-elements-and-instances.md\n@@ -0,0 +1,379 @@\n+---\n+title: \"React Components, Elements, and Instances\"\n+author: gaearon\n+---\n+\n+The difference between **components, their instances, and elements** confuses many React beginners. Why are there three different terms to refer to something that is painted on screen?\n+\n+## Managing the Instances\n+\n+If you’re new to React, you probably only worked with component classes and instances before. For example, you may declare a `Button` *component* by creating a class. When the app is running, you may have several *instances* of this component on screen, each with its own properties and local state. This is the traditional object-oriented UI programming. Why introduce *elements*?\n+\n+In this traditional UI model, it is up to you take care of creating and destroying child component instances. If a `Form` component wants to render a `Button` component, it needs to create its instance, and manually keep it up to date with any new information.\n+\n+```js\n+class Form extends TraditionalObjectOrientedView {\n+ render() {\n+ \/\/ Read some data passed to the view\n+ const { isSubmitted, buttonText } = this.attrs;\n+\n+ if (!isSubmitted && !this.button) {\n+ \/\/ Form is not yet submitted. Create the button!\n+ this.button = new Button({\n+ children: buttonText,\n+ color: 'blue'\n+ });\n+ this.el.appendChild(this.button.el);\n+ }\n+\n+ if (this.button) {\n+ \/\/ The button is visible. Update its text!\n+ this.button.attrs.children = buttonText;\n+ this.button.render();\n+ }\n+\n+ if (isSubmitted && this.button) {\n+ \/\/ Form was submitted. Destroy the button!\n+ this.el.removeChild(this.button.el);\n+ this.button.destroy();\n+ }\n+\n+ if (isSubmitted && !this.message) {\n+ \/\/ Form was submitted. Show the success message!\n+ this.message = new Message({ text: 'Success!' });\n+ this.el.appendChild(this.message.el);\n+ }\n+ }\n+}\n+```\n+\n+This is pseudocode, but it is more or less what you end up with when you write composite UI code that behaves consistently in an object-oriented way using a library like Backbone.\n+\n+Each component instance has to keep references to its DOM node and to the instances of the children components, and create, update, and destroy them when the time is right. The lines of code grow as the square of the number of possible states of the component, and the parents have direct access to their children component instances, making it hard to decouple them in the future.\n+\n+So how is React different?\n+\n+## Elements Describe the Tree\n+\n+In React, this is where the *elements* come to rescue. **An element is a plain object *describing* a component instance or DOM node and its desired properties.** It contains only information about the component type (for example, a `Button`), its properties (for example, its `color`), and any child elements inside it.\n+\n+An element is not an actual instance. Rather, it is a way to tell React what you *want* to see on the screen. You can’t call any methods on the element. It’s just an immutable description object with two fields: `type: (string | ReactClass)` and `props: Object`[^1].\n+\n+### DOM Elements\n+\n+When an element’s `type` is a string, it represents a DOM node with that tag name, and `props` correspond to its attributes. This is what React will render. For example:\n+\n+```js\n+{\n+ type: 'button',\n+ props: {\n+ className: 'button button-blue',\n+ children: {\n+ type: 'b',\n+ children: 'OK!'\n+ }\n+ }\n+}\n+```\n+\n+This element is just a way to represent the following HTML as a plain object:\n+\n+```html\n+

dillon1000/react

Files changed