{"files":[{"path":"docs\/_data\/nav_docs.yml","status":"M"},{"path":"docs\/docs\/ref-08-reconciliation.md","status":"M"},{"path":"docs\/docs\/ref-09-glossary.md","status":"A"}],"commit":{"shortRevision":"d36d26a574","authorEmail":"paul@oshannessy.com","authoredAt":"2014-10-23T20:50:27-07:00","authorName":"Paul O’Shannessy","revision":"d36d26a57454366132e8cd23adddefe3595535da","subject":"[docs] Glossary"},"parents":["4e5f5df4f6895ce4753d47b84c5e4ab9288c87ff"],"body":"Pulled in https:\/\/gist.github.com\/sebmarkbage\/fcb1b6ab493b0c77d589\nmostly verbatim","patch":"diff --git a\/docs\/_data\/nav_docs.yml b\/docs\/_data\/nav_docs.yml\nindex e7c71b68d5..4764540e7e 100644\n--- a\/docs\/_data\/nav_docs.yml\n+++ b\/docs\/_data\/nav_docs.yml\n@@ -77,6 +77,8 @@\n title: Special Non-DOM Attributes\n - id: reconciliation\n title: Reconciliation\n+ - id: glossary\n+ title: React (Virtual) DOM Terminology\n - title: Flux\n items:\n - id: flux-overview\ndiff --git a\/docs\/docs\/ref-08-reconciliation.md b\/docs\/docs\/ref-08-reconciliation.md\nindex 60f669caea..0c525eb233 100644\n--- a\/docs\/docs\/ref-08-reconciliation.md\n+++ b\/docs\/docs\/ref-08-reconciliation.md\n@@ -3,6 +3,7 @@ id: reconciliation\n title: Reconciliation\n permalink: reconciliation.html\n prev: special-non-dom-attributes.html\n+next: glossary.html\n ---\n \n React's key design decision is to make the API seem like it re-renders the whole app on every update. This makes writing applications a lot easier but is also an incredible challenge to make it tractable. This article explains how with powerful heuristics we managed to turn a O(n^{3<\/sup>) problem into a O(n) one.\ndiff --git a\/docs\/docs\/ref-09-glossary.md b\/docs\/docs\/ref-09-glossary.md\nnew file mode 100644\nindex 0000000000..3d8f200b2a\n--- \/dev\/null\n+++ b\/docs\/docs\/ref-09-glossary.md\n@@ -0,0 +1,192 @@\n+---\n+id: glossary\n+title: React (Virtual) DOM Terminology\n+permalink: glossary.html\n+prev: reconciliation.html\n+---\n+\n+In React's terminology, there are five core types that are important to distinguish:\n+\n+- [ReactElement \/ ReactElement Factory](#react-elements)\n+- [ReactNode](#react-nodes)\n+- [ReactComponent \/ ReactComponent Class](#react-components)\n+\n+## React Elements\n+\n+The primary type in React is the `ReactElement`. It has four properties: `type`, `props`, `key` and `ref`. It has no methods and nothing on the prototype.\n+\n+You can create one of these object through `React.createElement`.\n+\n+```javascript\n+var root = React.createElement('div');\n+```\n+\n+To render a new tree into the DOM, you create `ReactElement`s and pass them to `React.render` a long with a regular DOM `Element` (`HTMLElement` or `SVGElement`). `ReactElement`s are not to be confused with DOM `Element`s. A `ReactElement` is a light, stateless, immutable, virtual representation of a DOM `Element`. It is a virtual DOM.\n+\n+```javascript\n+React.render(root, document.body);\n+```\n+\n+To add properties to a DOM element, pass a properties object as the second argument and children to the third argument.\n+\n+```javascript\n+var child = React.createElement('li', null, 'Text Content');\n+var root = React.createElement('ul', { className: 'my-list' }, child);\n+React.render(root, document.body);\n+```\n+\n+If you use React JSX, then these `ReactElement`s are created for you. So this is equivalent:\n+\n+```javascript\n+var root = \n+ Text Content<\/li>\n+ <\/ul>;\n+React.render(root, document.body);\n+```\n+\n+__Factories__\n+\n+A `ReactElement`-factory is simply a function that generates a `ReactElement` with a particular `type` property. React has a built-in helper for you to create factories. It's effectively just:\n+\n+```javascript\n+function createFactory(type){\n+ return React.createElement.bind(null, type);\n+}\n+```\n+\n+It allows you to create a convenient short-hand instead of typing out `React.createElement('div')` all the time.\n+\n+```javascript\n+var div = React.createFactory('div');\n+var root = div({ className: 'my-div' });\n+React.render(root, document.body);\n+```\n+\n+React already have built-in factories for common HTML tags:\n+\n+```javascript\n+var root = React.DOM.ul({ className: 'my-list' },\n+ React.DOM.li(null, 'Text Content')\n+ );\n+```\n+\n+If you are using JSX you have no need for factories. JSX already provides a convenient short-hand for creating `ReactElement`s.\n+\n+\n+## React Nodes\n+\n+A `ReactNode` can be either:\n+- `ReactElement`\n+- `string` (aka `ReactText`)\n+- `number` (aka `ReactText`)\n+- Array of `ReactNode`s (aka `ReactFragment`)\n+\n+These are used as properties of other `ReactElement`s to represent children. Effectively they create a tree of `ReactElement`s.\n+\n+\n+## React Components\n+\n+You can use React using only `ReactElement`s but to really take advantage of React, you'll want to use `ReactComponent`s to create encapsulations with embedded state.\n+\n+A `ReactComponent` Class is simply just a JavaScript class (or \"constructor function\").\n+\n+```javascript\n+var MyComponent = React.createClass({\n+ render: function() {\n+ ...\n+ }\n+});\n+```\n+\n+When this constructor is invoked it is expected to return an object with at least a `render` method on it. This object is referred to as a `ReactComponent`.\n+\n+```javascript\n+var component = new MyComponent(props); \/\/ never do this\n+```\n+\n+Other than for testing, you would normally __never__ call this constructor yourself. React calls it for you.\n+\n+Instead, you pass the `ReactComponent` Class to `createElement` you get a `ReactElement`.\n+\n+```javascript\n+var element = React.createElement(MyComponent);\n+```\n+\n+OR using JSX:\n+\n+```javascript\n+var element = ;\n+```\n+\n+When this is passed to `React.render`, React will call the constructor for you and create a `ReactComponent`, which returned.\n+\n+```javascript\n+var component = React.render(element, document.body);\n+```\n+\n+If you keep calling `React.render` with the same type of `ReactElement` and the same container DOM `Element` it always returns the same instance. This instance is stateful.\n+\n+```javascript\n+var componentA = React.render(, document.body);\n+var componentB = React.render(, document.body);\n+componentA === componentB; \/\/ true\n+```\n+\n+This is why you shouldn't construct your own instance. Instead, `ReactElement` is a virtual `ReactComponent` before it gets constructed. An old and new `ReactElement` can be compared to see if a new `ReactComponent` instance is created or if the existing one is reused.\n+\n+The `render` method of a `ReactComponent` is expected to return another `ReactElement`. This allows these components to be composed. Ultimately the render resolves into `ReactElement` with a `string` tag which instantiates a DOM `Element` instance and inserts it into the document.\n+\n+\n+## Formal Type Definitions\n+\n+__Entry Point__\n+\n+```\n+React.render = (ReactElement, HTMLElement | SVGElement) => ReactComponent;\n+```\n+\n+__Nodes and Elements__\n+\n+```\n+type ReactNode = ReactElement | ReactFragment | ReactText;\n+\n+type ReactElement = ReactComponentElement | ReactDOMElement;\n+\n+type ReactDOMElement = {\n+ type : string,\n+ props : {\n+ children : ReactNodeList,\n+ className : string,\n+ etc.\n+ },\n+ key : string | boolean | number | null,\n+ ref : string | null\n+};\n+\n+type ReactComponentElement = {\n+ type : ReactClass,\n+ props : TProps,\n+ key : string | boolean | number | null,\n+ ref : string | null\n+};\n+\n+type ReactFragment = Array;\n+\n+type ReactNodeList = ReactNode | ReactEmpty;\n+\n+type ReactText = string | number;\n+\n+type ReactEmpty = null | undefined | boolean;\n+```\n+\n+__Classes and Components__\n+\n+```\n+type ReactClass = (TProps) => ReactComponent;\n+\n+type ReactComponent = {\n+ props : TProps,\n+ render : () => ReactElement\n+};\n+```\n+\n"}}

dillon1000/react

Files changed