You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds support for Preact (including "native" Preact - i.e. without
preact-compat)
Adds support for React's "Portals" feature.
Breaking Change: componentWillMount now gets executed before the
visitor. This should allow for better intialized instances
being passed into the visitor. Hopefully this doesn't affect you,
but it is good to be made aware of this change.
Fixes the manner in which context is passed down the tree.
@@ -9,92 +9,208 @@ Walk a React element tree, executing a provided visitor function against each el
9
9
10
10
## TOCs
11
11
12
-
-[Introduction](#introduction)
13
-
-[Example](#example)
14
-
-[FAQs](#faqs)
12
+
*[Introduction](#introduction)
13
+
*[Illustrative Example](#illustrative-example)
14
+
*[Order of Execution](#order-of-execution)
15
+
*[API](#api)
15
16
16
17
## Introduction
17
18
18
-
Originally inspired/lifted from the awesome [`react-apollo`](https://github.com/apollostack/react-apollo) project.
19
+
Inspired/lifted from the awesome [`react-apollo`](https://github.com/apollostack/react-apollo) project. 😗
19
20
20
-
This modified version expands upon the design, making it `Promise` based, allowing the visitor to return a `Promise`, which would subsequently delay the tree walking until the `Promise` is resolved. The tree is still walked in a depth-first fashion.
21
+
This modified version expands upon the design, making it `Promise` based, allowing the visitor to return a `Promise`, which would subsequently delay the tree walking until the `Promise` is resolved. The tree is still walked in a depth-first fashion.
21
22
22
-
With this you could, for example, perform pre-rendering parses on your React element tree to do things like data prefetching. 🤛
23
+
With this you could, for example, perform pre-rendering parses on your React element tree to do things like data prefetching. Which can be especially helpful when dealing with declarative APIs such as the one provided by React Router 4.
23
24
24
-
# Example
25
+
# Illustrative Example
25
26
26
-
In the below example we walk the tree and execute the `getValue` function on every element instance that has the function available. We then push the value into a values array.
27
+
In the below example we will create a visitor that will walk a React application, looking for any "class" component that has a `getData` method on it. We will then execute the `getData` function, storing the results into an array.
27
28
28
29
```jsx
29
-
importreactTreeWalkerfrom'react-tree-walker';
30
+
importreactTreeWalkerfrom'react-tree-walker'
30
31
31
-
classFooextendsReact.Component {
32
+
classDataFetcherextendsReact.Component {
32
33
constructor(props) {
33
-
super(props);
34
-
this.getData=this.getData.bind(this);
34
+
super(props)
35
+
this.getData=this.getData.bind(this)
35
36
}
36
37
37
38
getData() {
38
-
// Return a promise or a sync value
39
-
returnPromise.resolve(this.props.value);
39
+
// Supports promises! You could call an API for example to fetch some
40
+
// data, or do whatever "bootstrapping" you desire.
41
+
returnPromise.resove(this.props.id)
40
42
}
41
43
42
44
render() {
43
-
return<div>{this.props.children}</div>;
45
+
return<div>{this.props.children}</div>
44
46
}
45
47
}
46
48
47
49
constapp= (
48
50
<div>
49
51
<h1>Hello World!</h1>
50
-
<Foo value={1} />
51
-
<Foo value={2}>
52
-
<Foo value={4}>
53
-
<Foo value={5} />
54
-
</Foo>
55
-
</Foo>
56
-
<Foo value={3} />
52
+
<DataFetcher id={1} />
53
+
<DataFetcher id={2}>
54
+
<DataFetcher id={3}>
55
+
<DataFetcher id={4} />
56
+
</DataFetcher>
57
+
</DataFetcher>
58
+
<DataFetcher id={5} />
57
59
</div>
58
-
);
59
-
60
-
constvalues= [];
61
-
62
-
/**
63
-
* Visitor to be executed on each element being walked.
64
-
*
65
-
* @paramelement - The current element being walked.
66
-
* @paraminstance - If the current element is a Component or PureComponent
67
-
* then this will hold the reference to the created
68
-
* instance. For any other element type this will be null.
69
-
* @paramcontext - The current "React Context". Any provided childContextTypes
70
-
* will be passed down the tree.
71
-
*
72
-
* @return Anything other than `false` to continue walking down the current branch
73
-
* OR
74
-
* `false` if you wish to stop the traversal down the current branch,
75
-
* OR
76
-
* `Promise<true|false>` a promise that resolves to either true/false
77
-
*/
78
-
functionvisitor(element, instance, context) {
60
+
)
61
+
62
+
constvalues= []
63
+
64
+
// You provide this! See the API docs below for full details.
65
+
functionvisitor(element, instance) {
79
66
if (instance &&typeofinstance.getData) {
80
-
returninstance.getData()
81
-
.then((value)=> {
82
-
values.push(value);
83
-
//Return "false" to indicate that we do not want to traverse "4"'s children
84
-
return value !==4
85
-
})
67
+
returninstance.getData().then(value=> {
68
+
values.push(value)
69
+
// Return "false" to indicate that we do not want to visit "3"'s children,
70
+
//therefore we do not expect "4" to make it into our values array.
71
+
return value !==3
72
+
})
86
73
}
87
74
}
88
75
89
76
reactTreeWalker(app, visitor)
90
77
.then(() => {
91
-
console.log(values); // [1, 2, 4, 3];
78
+
console.log(values) // [1, 2, 3, 5];
79
+
// Now is a good time to call React's renderToString whilst exposing
80
+
// whatever values you built up to your app.
92
81
})
93
82
// since v3.0.0 you need to do your own error handling!
94
-
.catch(err=>console.error(err));
83
+
.catch(err=>console.error(err))
84
+
```
85
+
86
+
Not a particularly useful piece of code, but hopefully it is illustrative enough as to indicate the posibilities. One could use this to warm a cache or a `redux` state, subsequently performing a `renderToString` execution with all the required data in place.
95
87
88
+
## Order of Execution
89
+
90
+
`react-tree-walker` walks your React application in a depth-first fashion, i.e. from the top down, visiting each child until their are no more children available before moving on to the next element. We can illustrate this behaviour using the below example:
91
+
92
+
```jsx
93
+
<div>
94
+
<h1>Foo</h1>
95
+
<section>
96
+
<p>One</p>
97
+
<p>Two</p>
98
+
</section>
99
+
<Footer />
100
+
</div>
96
101
```
97
102
98
-
## FAQs
103
+
In this example the order of elements being visited would be:
104
+
105
+
div -> h1 -> "Foo" -> section -> p -> "One" -> p -> "Two" -> Footer
106
+
107
+
Whilst your application is being walked its behaviour will be much the same as if it were being rendered on the server - i.e. the `componentWillMount` lifecycle will be executed for any "class" components, and context provided by any components will be passed down and become available to child components.
108
+
109
+
Despite emulating a server side render, the tree walking process is far cheaper as it doesn't actually perform any rendering of the element tree to a string. It simply interogates your app building up an object/element tree. The really expensive cycles will likely be the API calls that you make. 😀
110
+
111
+
That being said you do have a bail-out ability allowing you to suspend the traversal down a branch of the tree. To do so you simply need to return `false` from your visitor function, or if returning a `Promise` ensure that the `Promise` resolves a `false` for the same behaviour.
112
+
113
+
## API
114
+
115
+
The API is very simple at the moment, only exposing a single function, which you can import as follows
The function you wish to execute against _each_ element that is walked on the `tree`.
140
+
141
+
See its [API docs](#visitor) below.
142
+
143
+
***context** (`Object`, _optional_)
144
+
145
+
Any root context you wish to provide to your application.
146
+
147
+
e.g. `{ myContextItem: 'foo' }`
99
148
100
-
> Let me know if you have any...
149
+
***options** (`Object`, _optional_)
150
+
151
+
Additional options/configuration. It currently supports the following values:
152
+
153
+
*_componentWillUnmount_: Enable this to have the `componentWillUnmount` lifecycle event be executed whilst walking your tree. Defaults to `false`. This was added as an experimental additional flag to help with applications where they have critical disposal logic being executed within the `componentWillUnmount` lifecycle event.
154
+
155
+
**Returns**
156
+
157
+
A `Promise` that resolves when the tree walking is completed.
158
+
159
+
### `visitor`
160
+
161
+
Encapsulates the logic you wish to execute against each element. You create and provide this function to the `reactTreeWalker`.
162
+
163
+
**Parameters**
164
+
165
+
***element** (React/Preact element, _required_)
166
+
167
+
The current element being walked.
168
+
169
+
***instance** (Component Instance, _optional_)
170
+
171
+
If the current element being walked is a "class" Component then this will contain the instance of the Component - allowing you to interface with its methods etc.
172
+
173
+
***context** (`Object`, _required_)
174
+
175
+
The React context that is available to the current element. `react-tree-walker` emulates React in exposing context down the tree.
176
+
177
+
***childContext** (`Object`, _optional_)
178
+
179
+
If the current element being walked is a "class" Component and it exposes additional "child" context (via the `getChildContext` method) then this will contain the context that is being provided by the component instance.
180
+
181
+
**Returns**
182
+
183
+
If you return `false` then the children of the current element will not be visited.
184
+
185
+
e.g.
186
+
187
+
```javascript
188
+
functionvisitor(element) {
189
+
if (element.type==='menu') {
190
+
// We will not traverse the children for any <menu /> nodes
191
+
return'false'
192
+
}
193
+
}
194
+
```
195
+
196
+
You can also return a `Promise` which will cause the tree walking to wait for the `Promise` to be resolved before attempting to visit the children for the current element.
197
+
198
+
```javascript
199
+
functionvisitor(element, instance) {
200
+
// This will make every visit take 1 second to execution.
0 commit comments