Skip to content

Commit 2d0764f

Browse files
lukasbachlukasbach
committed
chore: extract data provider docs into two pages, finish new docs
1 parent c5a0af4 commit 2d0764f

File tree

4 files changed

+164
-151
lines changed

4 files changed

+164
-151
lines changed

‎README.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,9 @@ import { UncontrolledTreeEnvironment, Tree, StaticTreeDataProvider } from 'react
4141
</UncontrolledTreeEnvironment>;
4242
```
4343

44-
More details at [the Get-Started Guide](https://rct.lukasbach.com/docs/getstarted).
44+
More details at [the Get-Started Guide](https://rct.lukasbach.com/docs/getstarted). The [guide on how to integrate
45+
data with a static tree data provider](https://rct.lukasbach.com/docs/guides/static-data-provider) is also
46+
a good starting point to understand how to integrate data with React Complex Tree.
4547

4648
## Features
4749

‎packages/docs/docs/getstarted.mdx

+6-1
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ For the environment, there are three ways to implement your tree environment:
110110

111111
- Use an [UncontrolledTreeEnvironment](/docs/react/UncontrolledTreeEnvironment) and a
112112
[StaticTreeDataProvider](/docs/api/classes/StaticTreeDataProvider) that provides the items. This is the easiest
113-
approach and is described below.
113+
approach and is described below, and in the [static tree data provider guide](/docs/guides/static-data-provider).
114114
- Use an [UncontrolledTreeEnvironment](/docs/react/UncontrolledTreeEnvironment) and implement a custom
115115
[TreeDataProvider](/docs/api/interfaces/TreeDataProvider). This is similarly easy and provides the ability to
116116
directly react to change events and define a lazy item-loading strategy. This approach is most likely the best
@@ -122,6 +122,11 @@ For the environment, there are three ways to implement your tree environment:
122122

123123
## Providing the data for the tree
124124

125+
:::info
126+
There is another guide specifically for using static tree data providers [here](/docs/guides/static-data-provider),
127+
which goes a bit more into detail.
128+
:::
129+
125130
When integrating React Complex Tree with an uncontrolled environment and a static tree data provider, items
126131
must be provided as [explicit data source](/docs/api/interfaces/ExplicitDataSource). An example for such
127132
items looks like this:

‎packages/docs/docs/guides/custom-data-provider.mdx

+2-149
Original file line numberDiff line numberDiff line change
@@ -1,156 +1,9 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 2.5
33
---
44

5-
# Data Provider
5+
# Custom Tree Data Provider
66

7-
When using an uncontrolled environment, you need to provide your data by supplying a data provider. The
8-
easiest way to get started is using the [Static Tree Data Provider](/docs/api/classes/StaticTreeDataProvider).
9-
It allows you to provide your data as record which maps item ids to tree items, and gives you the possibility
10-
to react to changes in the tree structure, as well as inject your own changes through change events.
11-
12-
# Static Tree Data Provider
13-
14-
The following example gives a good example of what is possible with static tree data providers. We will look
15-
into the details of the data provider below.
16-
17-
```jsx live
18-
function App() {
19-
const items = useMemo(() => ({ ...shortTree.items }), []);
20-
const dataProvider = useMemo(
21-
() =>
22-
new StaticTreeDataProvider(items, (item, data) => ({
23-
...item,
24-
data,
25-
})),
26-
[items]
27-
);
28-
29-
const injectItem = () => {
30-
const rand = `${Math.random()}`;
31-
items[rand] = { data: 'New Item', index: rand };
32-
items.root.children.push(rand);
33-
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
34-
};
35-
36-
const removeItem = () => {
37-
if (items.root.children.length === 0) return;
38-
items.root.children.pop();
39-
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
40-
};
41-
42-
return (
43-
<UncontrolledTreeEnvironment
44-
canDragAndDrop
45-
canDropOnFolder
46-
canReorderItems
47-
dataProvider={dataProvider}
48-
getItemTitle={item => item.data}
49-
viewState={{
50-
'tree-1': {
51-
expandedItems: [],
52-
},
53-
}}
54-
>
55-
<button type="button" onClick={injectItem}>
56-
Inject item
57-
</button>
58-
<button type="button" onClick={removeItem}>
59-
Remove item
60-
</button>
61-
<Tree treeId="tree-1" rootItem="root" treeLabel="Tree Example" />
62-
</UncontrolledTreeEnvironment>
63-
);
64-
}
65-
```
66-
67-
## Creating the data provider with data
68-
69-
First, create the data provider. You want to make sure it isn't recreated on re-renders, so memoize
70-
it in the component in which it is defined.
71-
72-
```tsx
73-
const dataProvider = useMemo(
74-
() =>
75-
new StaticTreeDataProvider(items, (item, data) => ({
76-
...item,
77-
data,
78-
})),
79-
[items]
80-
);
81-
```
82-
83-
The items is a record mapping item ids to tree items, for example:
84-
85-
```typescript
86-
const items = [
87-
{
88-
index: "item-id",
89-
data: { arbitraryData: 123, name: "Hello" },
90-
children: ["item-id-1", "item-id-2"],
91-
isFolder: true
92-
}
93-
]
94-
```
95-
96-
Note that, whatever you provide to the `getItemTitle` prop is used to infer the item display name.
97-
98-
```ts jsx
99-
<UncontrolledTreeEnvironment
100-
getItemTitle={item => item.data.name}
101-
/>
102-
```
103-
104-
## Apply changes from outside
105-
106-
You can apply changes to the underlying data source. Just make sure to let RCT know about that by
107-
emitting a change event on the affected items. Note that, if you add or remove items, the affected item
108-
is the parent item, not the added or removed items.
109-
110-
```ts
111-
const injectItem = () => {
112-
const rand = `${Math.random()}`;
113-
items[rand] = { data: 'New Item', index: rand };
114-
items.root.children.push(rand);
115-
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
116-
};
117-
118-
const removeItem = () => {
119-
if (items.root.children.length === 0) return;
120-
items.root.children.pop();
121-
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
122-
};
123-
```
124-
125-
## Reacting to Drag Events
126-
127-
Drag changes are always immediately applied to the visualization, so make sure to implement the `canDropAt`
128-
prop to customize if that should not work in all cases. The static tree data emits tree change events similar
129-
to the ones you would emit when applying changes from outside, so you can react to them in the same way.
130-
131-
```typescript
132-
dataProvider.onDidChangeTreeData(changedItemIds => {
133-
console.log(changedItemIds);
134-
});
135-
```
136-
137-
## Reacting to Rename Events
138-
139-
The second (optional) parameter of the static tree data provider lets you react to rename events. Note that
140-
you can customize whether renaming is possible in the first place through the `canRename` prop.
141-
142-
```typescript
143-
const dataProvider = new StaticTreeDataProvider(items, (item, newName) => {
144-
// Return the patched item with new item name here
145-
return {
146-
...item,
147-
data: { ...item.data, name: newName },
148-
};
149-
});
150-
`
151-
```
152-
153-
## Custom Data Provider
1547

1558
In more complex scenarios, it's probably easiest to implement your own data provider.
1569
This provider must implement the [TreeDataProvider interface](/docs/api/interfaces/TreeDataProvider), i.e.

‎packages/docs/docs/guides/static-data-provider.mdx

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Static Tree Data Provider
6+
7+
When using an uncontrolled environment, you need to provide your data by supplying a data provider. The
8+
easiest way to get started is using the [Static Tree Data Provider](/docs/api/classes/StaticTreeDataProvider).
9+
It allows you to provide your data as record which maps item ids to tree items, and gives you the possibility
10+
to react to changes in the tree structure, as well as inject your own changes through change events.
11+
12+
:::info
13+
If you want to implement a custom data provider your own, you can find a comprehensive guide [here](/docs/guides/custom-data-provider).
14+
:::
15+
16+
The following example gives a good example of what is possible with static tree data providers. We will look
17+
into the details of the data provider below.
18+
19+
```jsx live
20+
function App() {
21+
const items = useMemo(() => ({ ...shortTree.items }), []);
22+
const dataProvider = useMemo(
23+
() =>
24+
new StaticTreeDataProvider(items, (item, data) => ({
25+
...item,
26+
data,
27+
})),
28+
[items]
29+
);
30+
31+
const injectItem = () => {
32+
const rand = `${Math.random()}`;
33+
items[rand] = { data: 'New Item', index: rand };
34+
items.root.children.push(rand);
35+
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
36+
};
37+
38+
const removeItem = () => {
39+
if (items.root.children.length === 0) return;
40+
items.root.children.pop();
41+
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
42+
};
43+
44+
return (
45+
<UncontrolledTreeEnvironment
46+
canDragAndDrop
47+
canDropOnFolder
48+
canReorderItems
49+
dataProvider={dataProvider}
50+
getItemTitle={item => item.data}
51+
viewState={{
52+
'tree-1': {
53+
expandedItems: [],
54+
},
55+
}}
56+
>
57+
<button type="button" onClick={injectItem}>
58+
Inject item
59+
</button>
60+
<button type="button" onClick={removeItem}>
61+
Remove item
62+
</button>
63+
<Tree treeId="tree-1" rootItem="root" treeLabel="Tree Example" />
64+
</UncontrolledTreeEnvironment>
65+
);
66+
}
67+
```
68+
69+
## Creating the data provider with data
70+
71+
First, create the data provider. You want to make sure it isn't recreated on re-renders, so memoize
72+
it in the component in which it is defined.
73+
74+
```tsx
75+
const dataProvider = useMemo(
76+
() =>
77+
new StaticTreeDataProvider(items, (item, data) => ({
78+
...item,
79+
data,
80+
})),
81+
[items]
82+
);
83+
```
84+
85+
The items is a record mapping item ids to tree items, for example:
86+
87+
```typescript
88+
const items = [
89+
{
90+
index: "item-id",
91+
data: { arbitraryData: 123, name: "Hello" },
92+
children: ["item-id-1", "item-id-2"],
93+
isFolder: true
94+
}
95+
]
96+
```
97+
98+
Note that, whatever you provide to the `getItemTitle` prop is used to infer the item display name.
99+
100+
```ts jsx
101+
<UncontrolledTreeEnvironment
102+
getItemTitle={item => item.data.name}
103+
/>
104+
```
105+
106+
## Apply changes from outside
107+
108+
You can apply changes to the underlying data source. Just make sure to let RCT know about that by
109+
emitting a change event on the affected items. Note that, if you add or remove items, the affected item
110+
is the parent item, not the added or removed items.
111+
112+
```ts
113+
const injectItem = () => {
114+
const rand = `${Math.random()}`;
115+
items[rand] = { data: 'New Item', index: rand };
116+
items.root.children.push(rand);
117+
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
118+
};
119+
120+
const removeItem = () => {
121+
if (items.root.children.length === 0) return;
122+
items.root.children.pop();
123+
dataProvider.onDidChangeTreeDataEmitter.emit(['root']);
124+
};
125+
```
126+
127+
## Reacting to Drag Events
128+
129+
Drag changes are always immediately applied to the visualization, so make sure to implement the `canDropAt`
130+
prop to customize if that should not work in all cases. The static tree data emits tree change events similar
131+
to the ones you would emit when applying changes from outside, so you can react to them in the same way.
132+
133+
```typescript
134+
dataProvider.onDidChangeTreeData(changedItemIds => {
135+
console.log(changedItemIds);
136+
});
137+
```
138+
139+
## Reacting to Rename Events
140+
141+
The second (optional) parameter of the static tree data provider lets you react to rename events. Note that
142+
you can customize whether renaming is possible in the first place through the `canRename` prop.
143+
144+
```typescript
145+
const dataProvider = new StaticTreeDataProvider(items, (item, newName) => {
146+
// Return the patched item with new item name here
147+
return {
148+
...item,
149+
data: { ...item.data, name: newName },
150+
};
151+
});
152+
`
153+
```

0 commit comments

Comments
 (0)