Skip to content

Commit 99d4152

Browse files
LukasBollLukasBoll
committed
add dynamic enum Tutorial
Co-authored-by: Stefan Dirix <[email protected]> closes eclipsesource#270
1 parent 9edb883 commit 99d4152

File tree

11 files changed

+576
-1
lines changed

11 files changed

+576
-1
lines changed

‎content/docs/tutorial/dynamic-enum.mdx

+259
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
---
2+
id: dynamic-enum
3+
title: Dynamic Renderers
4+
description: This tutorial describes how to create a dynamic enum
5+
---
6+
7+
import { WithRegionRenderer } from '../../../src/components/docs/tutorials/dynamic-enum';
8+
9+
10+
In this tutorial, you will learn how to handle dynamic data in React using [custom renderers](./custom-renderers), React Context, and the `useJsonForms` hook.
11+
This approach allows you to build flexible and interactive forms that adapt to user selections and API responses.
12+
13+
### Scenario
14+
15+
Imagine a form where users need to provide their location by selecting a country, a region and a city.
16+
The options for countries and regions are fetched from an API.
17+
The available regions depend on the selected country.
18+
To address those requirements, we'll create custom renderers for country and region.
19+
20+
<WithRegionRenderer />
21+
22+
23+
#### Schema
24+
25+
To begin, let's introduce the corresponding JSON schema.
26+
We have created an object with properties for country, region, and city.
27+
In our example, the schema also includes a property `x-url`, which specifies the entry point of the corresponding API.
28+
Both `country` and `region` have a property `x-endpoint`, indicating the endpoint from which the data should be fetched.
29+
Additionally, they have a field specifying which fields depend on the input.
30+
In the case of the `country` field, the `region` and `city` fields depend on it and will get reset, if the value of the `country` changes.
31+
The `city` field, in turn, is dependent on the `region` field.
32+
33+
```js
34+
{
35+
"type": "object",
36+
"x-url": "www.api.com",
37+
"properties": {
38+
"country": {
39+
"type": "string",
40+
"x-endpoint": "countries",
41+
"dependencies": ["region", "city"]
42+
},
43+
"region": {
44+
"type": "string",
45+
"x-endpoint": "regions",
46+
"dependencies": ["city"]
47+
},
48+
"city": {
49+
"type": "string"
50+
}
51+
}
52+
}
53+
```
54+
55+
56+
### Accessing Schema Data and Initialising the React Context
57+
58+
In this step we will access the data from the schema and initialize the react context.
59+
60+
#### Accessing the API URL from Schema
61+
62+
To access the URL defined from the schema we can simply access the `x-url` attribute.
63+
64+
```js
65+
const url = schema['x-url'];
66+
```
67+
68+
#### Initializing the React Context
69+
70+
Now that we have access to the API URL, we can use React Context to make this data available across our renderers.
71+
React Context allows you to share data globally within your application, enabling components deep in the component tree to access data without needing to pass properties through all parent elements.
72+
To set up the React Context for your API service, create it in your application as follows:
73+
74+
```js
75+
export const APIContext = React.createContext(new API(url));
76+
77+
const App = () =>{
78+
79+
...
80+
<JsonForms/>
81+
}
82+
```
83+
84+
#### Accessing the API context
85+
86+
87+
Access the API service using the context:
88+
89+
```js
90+
const api = React.useContext(APIContext);
91+
```
92+
93+
Changing the context's value will trigger a re-render of components that use it, making it a powerful tool for managing dynamic data.
94+
95+
96+
### The Country Renderer
97+
98+
The core of the country renderer is a dropdown, therefore we can reuse the MaterialEnumControl from the React Material renderer set.
99+
To reuse material renderers, the Unwrapped renderers must be used. (more information regarding reusing renderers can be seen [here](./custom-renderers#reusing-existing-controls))
100+
101+
```js
102+
import { Unwrapped, WithOptionLabel } from '@jsonforms/material-renderers';
103+
104+
const { MaterialEnumControl } = Unwrapped;
105+
106+
...
107+
108+
<MaterialEnumControl
109+
{...props}
110+
options = {options}
111+
handleChange = {handleChange}
112+
/>
113+
...
114+
```
115+
116+
With the `MaterialEnumControl`in place the main question remains how to set the `options` and the `handleChange` attribute.
117+
To determine the available options, we need to access the API.
118+
And to implement the `handleChange` function, we need access to the `dependent` field in the schema.
119+
120+
#### Accessing Schema Data
121+
122+
The `endpoint` and `dependent` fields can be obtained from the schema object provided to the custom renderer via JSON Forms.
123+
Since these fields are not part of the standard JSON schema type in JSON Forms, we must add them to the schema's interface and access them as follows:
124+
125+
```js
126+
type JsonSchemaWithDependenciesAndEndpoint = JsonSchema & {
127+
dependent: string[];
128+
endpoint: string;
129+
};
130+
export const Country = (
131+
props: ControlProps & OwnPropsOfEnum & WithOptionLabel & TranslateProps
132+
) => {
133+
...
134+
135+
const schema = props.schema as JsonSchemaWithDependenciesAndEndpoint;
136+
const endpoint = schema.endpoint;
137+
const dependent = schema.dependent
138+
...
139+
}
140+
```
141+
142+
#### Country Renderer Implementation
143+
144+
The country renderer uses the `APIContext` to query the API and fetch the available options.
145+
We utilize the `useEffect` hook to initialize the options.
146+
While waiting for the API response, we set the available options to empty and display a loading spinner.
147+
In the `handleChange` function, we set the new selected value and reset all dependent fields;
148+
When changing the country, both the region and city will be reset to `undefined`.
149+
150+
```js
151+
import { Unwrapped, WithOptionLabel } from '@jsonforms/material-renderers';
152+
153+
const { MaterialEnumControl } = Unwrapped;
154+
155+
type JsonSchemaWithDependenciesAndEndpoint = JsonSchema & {
156+
dependent: string[];
157+
endpoint: string;
158+
};
159+
160+
export const Country = (
161+
props: ControlProps & OwnPropsOfEnum & WithOptionLabel & TranslateProps
162+
) => {
163+
const { handleChange } = props;
164+
const [options, setOptions] = useState<string[]>([]);
165+
const api = React.useContext(APIContext);
166+
const schema = props.schema as JsonSchemaWithDependenciesAndEndpoint;
167+
168+
const endpoint = schema.endpoint;
169+
const dependent: string[] = schema.dependent ? schema.dependent : [];
170+
171+
useEffect(() => {
172+
api.get(endpoint).then((result) => {
173+
setOptions(result);
174+
});
175+
}, []);
176+
177+
if (options.length === 0) {
178+
return <CircularProgress />;
179+
}
180+
181+
return (
182+
<MaterialEnumControl
183+
{...props}
184+
handleChange={(path: string, value: any) => {
185+
handleChange(path, value);
186+
dependent.forEach((path) => {
187+
handleChange(path, undefined);
188+
});
189+
}}
190+
options={options.map((option) => {
191+
return { label: option, value: option };
192+
})}
193+
/>
194+
);
195+
};
196+
```
197+
198+
Now all that´s left to do is to [create a tester](./custom-renderers#2-create-a-tester) and [register](./custom-renderers#3-register-the-renderer) the new custom renderer in our application.
199+
200+
### The Region Renderer
201+
202+
The region renderer can be implemented similarly to the country renderer.
203+
It also accesses the API via the context and includes `endpoint` and `dependent` fields defined in its schema.
204+
However, the options, on the other hand, are also dependent on the selected country.
205+
JSON Forms provides the `useJsonForms` hook, allowing you to access form data and trigger component rerenders when the data changes.
206+
Let's use this hook in our region renderer to access the selected country:
207+
208+
```js
209+
import { Unwrapped, WithOptionLabel } from '@jsonforms/material-renderers';
210+
const { MaterialEnumControl } = Unwrapped;
211+
212+
type JsonSchemaWithDependenciesAndEndpont = JsonSchema & {
213+
dependent: string[];
214+
endpoint: string;
215+
};
216+
217+
export const Region = (
218+
props: ControlProps & OwnPropsOfEnum & WithOptionLabel & TranslateProps
219+
) => {
220+
const schema = props.schema as JsonSchemaWithDependenciesAndEndpont;
221+
const { handleChange } = props;
222+
const [options, setOptions] = useState<string[]>([]);
223+
const api = React.useContext(APIContext);
224+
const country = useJsonForms().core?.data.country;
225+
const [previousCountry, setPreviousCountry] = useState<String>();
226+
227+
const endpoint = schema.endpoint;
228+
const dependent: string[] = schema.dependent ? schema.dependent : [];
229+
230+
if (previousCountry !== country) {
231+
setOptions([]);
232+
setPreviousCountry(country);
233+
api.get(endpoint + '/' + country).then((result) => {
234+
setOptions(result);
235+
});
236+
}
237+
238+
if (options.length === 0 && country !== undefined) {
239+
return <CircularProgress />;
240+
}
241+
242+
return (
243+
<MaterialEnumControl
244+
{...props}
245+
handleChange={(path: string, value: any) => {
246+
handleChange(path, value);
247+
dependent.forEach((path) => {
248+
handleChange(path, undefined);
249+
});
250+
}}
251+
options={options.map((option) => {
252+
return { label: option, value: option };
253+
})}
254+
/>
255+
);
256+
};
257+
```
258+
Again we need to create a [create a tester](./custom-renderers#2-create-a-tester) and [register](./custom-renderers#3-register-the-renderer) the new custom renderer.
259+
A running example of the scenario can also be seen at the [react-seed](https://github.com/eclipsesource/jsonforms-react-seed) app.

‎docusaurus.config.js

+4
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,10 @@ module.exports = {
227227
to: '/docs/tutorial/custom-renderers',
228228
from: '/docs/custom-renderers',
229229
},
230+
{
231+
to: '/docs/tutorial/dynamic-enum',
232+
from: '/docs/dynamic-enum',
233+
},
230234
{
231235
to: '/docs/tutorial/multiple-forms',
232236
from: '/docs/multiple-forms',

‎src/components/common/api.ts

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
export class API {
2+
private url: string;
3+
4+
constructor(url: string) {
5+
this.url = url;
6+
}
7+
8+
async get(endpoint: string): Promise<string[]> {
9+
switch (this.url + '/' + endpoint) {
10+
case 'www.api.com/regions/Germany':
11+
return germanStates;
12+
case 'www.api.com/regions/US':
13+
return usStates;
14+
case 'www.api.com/countries':
15+
return ['Germany', 'US'];
16+
default:
17+
return [];
18+
}
19+
}
20+
}
21+
22+
const germanStates = [
23+
'Berlin',
24+
'Bayern',
25+
'Niedersachsen',
26+
'Baden-Württemberg',
27+
'Rheinland-Pfalz',
28+
'Sachsen',
29+
'Thüringen',
30+
'Hessen',
31+
'Nordrhein-Westfalen',
32+
'Sachsen-Anhalt',
33+
'Brandenburg',
34+
'Mecklenburg-Vorpommern',
35+
'Hamburg',
36+
'Schleswig-Holstein',
37+
'Saarland',
38+
'Bremen',
39+
];
40+
41+
const usStates = [
42+
'Alabama',
43+
'Alaska',
44+
'Arizona',
45+
'Arkansas',
46+
'California',
47+
'Colorado',
48+
'Connecticut',
49+
'Delaware',
50+
'Florida',
51+
'Georgia',
52+
'Hawaii',
53+
'Idaho',
54+
'Illinois',
55+
'Indiana',
56+
'Iowa',
57+
'Kansas',
58+
'Kentucky',
59+
'Louisiana',
60+
'Maine',
61+
'Maryland',
62+
'Massachusetts',
63+
'Michigan',
64+
'Minnesota',
65+
'Mississippi',
66+
'Missouri',
67+
'Montana',
68+
'Nebraska',
69+
'Nevada',
70+
'New Hampshire',
71+
'New Jersey',
72+
'New Mexico',
73+
'New York',
74+
'North Carolina',
75+
'North Dakota',
76+
'Ohio',
77+
'Oklahoma',
78+
'Oregon',
79+
'Pennsylvania',
80+
'Rhode Island',
81+
'South Carolina',
82+
'South Dakota',
83+
'Tennessee',
84+
'Texas',
85+
'Utah',
86+
'Vermont',
87+
'Virginia',
88+
'Washington',
89+
'West Virginia',
90+
'Wisconsin',
91+
'Wyoming',
92+
];

0 commit comments

Comments
 (0)