[docs] Glossary
Pulled in https://gist.github.com/sebmarkbage/fcb1b6ab493b0c77d589 mostly verbatim
Paul O’Shannessy committed
Oct 23, 2014 at 20:50 UTC
d36d26a57454366132e8cd23adddefe3595535da
3 files changed
+195
docs/_data/nav_docs.yml
+2
@@ -77,6 +77,8 @@
77
title: Special Non-DOM Attributes
78
- id: reconciliation
79
title: Reconciliation
80
+ - id: glossary
81
+ title: React (Virtual) DOM Terminology
82
- title: Flux
83
items:
84
- id: flux-overview
docs/docs/ref-08-reconciliation.md
+1
@@ -3,6 +3,7 @@ id: reconciliation
3
title: Reconciliation
4
permalink: reconciliation.html
5
prev: special-non-dom-attributes.html
6
+next: glossary.html
7
---
8
9
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<sup>3</sup>) problem into a O(n) one.
docs/docs/ref-09-glossary.md
new
+192
@@ -0,0 +1,192 @@
1
+---
2
+id: glossary
3
+title: React (Virtual) DOM Terminology
4
+permalink: glossary.html
5
+prev: reconciliation.html
6
+---
7
+
8
+In React's terminology, there are five core types that are important to distinguish:
9
+
10
+- [ReactElement / ReactElement Factory](#react-elements)
11
+- [ReactNode](#react-nodes)
12
+- [ReactComponent / ReactComponent Class](#react-components)
13
+
14
+## React Elements
15
+
16
+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.
17
+
18
+You can create one of these object through `React.createElement`.
19
+
20
+```javascript
21
+var root = React.createElement('div');
22
+```
23
+
24
+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.
25
+
26
+```javascript
27
+React.render(root, document.body);
28
+```
29
+
30
+To add properties to a DOM element, pass a properties object as the second argument and children to the third argument.
31
+
32
+```javascript
33
+var child = React.createElement('li', null, 'Text Content');
34
+var root = React.createElement('ul', { className: 'my-list' }, child);
35
+React.render(root, document.body);
36
+```
37
+
38
+If you use React JSX, then these `ReactElement`s are created for you. So this is equivalent:
39
+
40
+```javascript
41
+var root = <ul className="my-list">
42
+ <li>Text Content</li>
43
+ </ul>;
44
+React.render(root, document.body);
45
+```
46
+
47
+__Factories__
48
+
49
+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:
50
+
51
+```javascript
52
+function createFactory(type){
53
+ return React.createElement.bind(null, type);
54
+}
55
+```
56
+
57
+It allows you to create a convenient short-hand instead of typing out `React.createElement('div')` all the time.
58
+
59
+```javascript
60
+var div = React.createFactory('div');
61
+var root = div({ className: 'my-div' });
62
+React.render(root, document.body);
63
+```
64
+
65
+React already have built-in factories for common HTML tags:
66
+
67
+```javascript
68
+var root = React.DOM.ul({ className: 'my-list' },
69
+ React.DOM.li(null, 'Text Content')
70
+ );
71
+```
72
+
73
+If you are using JSX you have no need for factories. JSX already provides a convenient short-hand for creating `ReactElement`s.
74
+
75
+
76
+## React Nodes
77
+
78
+A `ReactNode` can be either:
79
+- `ReactElement`
80
+- `string` (aka `ReactText`)
81
+- `number` (aka `ReactText`)
82
+- Array of `ReactNode`s (aka `ReactFragment`)
83
+
84
+These are used as properties of other `ReactElement`s to represent children. Effectively they create a tree of `ReactElement`s.
85
+
86
+
87
+## React Components
88
+
89
+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.
90
+
91
+A `ReactComponent` Class is simply just a JavaScript class (or "constructor function").
92
+
93
+```javascript
94
+var MyComponent = React.createClass({
95
+ render: function() {
96
+ ...
97
+ }
98
+});
99
+```
100
+
101
+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`.
102
+
103
+```javascript
104
+var component = new MyComponent(props); // never do this
105
+```
106
+
107
+Other than for testing, you would normally __never__ call this constructor yourself. React calls it for you.
108
+
109
+Instead, you pass the `ReactComponent` Class to `createElement` you get a `ReactElement`.
110
+
111
+```javascript
112
+var element = React.createElement(MyComponent);
113
+```
114
+
115
+OR using JSX:
116
+
117
+```javascript
118
+var element = <MyComponent />;
119
+```
120
+
121
+When this is passed to `React.render`, React will call the constructor for you and create a `ReactComponent`, which returned.
122
+
123
+```javascript
124
+var component = React.render(element, document.body);
125
+```
126
+
127
+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.
128
+
129
+```javascript
130
+var componentA = React.render(<MyComponent />, document.body);
131
+var componentB = React.render(<MyComponent />, document.body);
132
+componentA === componentB; // true
133
+```
134
+
135
+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.
136
+
137
+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.
138
+
139
+
140
+## Formal Type Definitions
141
+
142
+__Entry Point__
143
+
144
+```
145
+React.render = (ReactElement, HTMLElement | SVGElement) => ReactComponent;
146
+```
147
+
148
+__Nodes and Elements__
149
+
150
+```
151
+type ReactNode = ReactElement | ReactFragment | ReactText;
152
+
153
+type ReactElement = ReactComponentElement | ReactDOMElement;
154
+
155
+type ReactDOMElement = {
156
+ type : string,
157
+ props : {
158
+ children : ReactNodeList,
159
+ className : string,
160
+ etc.
161
+ },
162
+ key : string | boolean | number | null,
163
+ ref : string | null
164
+};
165
+
166
+type ReactComponentElement<TProps> = {
167
+ type : ReactClass<TProps>,
168
+ props : TProps,
169
+ key : string | boolean | number | null,
170
+ ref : string | null
171
+};
172
+
173
+type ReactFragment = Array<ReactNode | ReactEmpty>;
174
+
175
+type ReactNodeList = ReactNode | ReactEmpty;
176
+
177
+type ReactText = string | number;
178
+
179
+type ReactEmpty = null | undefined | boolean;
180
+```
181
+
182
+__Classes and Components__
183
+
184
+```
185
+type ReactClass<TProps> = (TProps) => ReactComponent<TProps>;
186
+
187
+type ReactComponent<TProps> = {
188
+ props : TProps,
189
+ render : () => ReactElement
190
+};
191
+```
192
+