@ea-lab/reactive-json-docs 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/public/rjbuild/docs/core/reaction/fetchData.md +136 -10
- package/public/rjbuild/docs/core/reaction/fetchData.yaml +222 -9
- package/public/rjbuild/docs/core/reaction/submitData.md +139 -4
- package/public/rjbuild/docs/core/reaction/submitData.yaml +50 -2
- package/public/rjbuild/docs/install.yaml +0 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ea-lab/reactive-json-docs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
|
|
5
5
|
"main": "public/rjbuild/docs/index.yaml",
|
|
6
6
|
"files": [
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"private": false,
|
|
27
27
|
"devDependencies": {
|
|
28
28
|
"@craco/craco": "^7.1.0",
|
|
29
|
-
"@ea-lab/reactive-json": "^0.
|
|
29
|
+
"@ea-lab/reactive-json": "^0.2.2",
|
|
30
30
|
"@ea-lab/reactive-json-chartjs": "^0.0.23",
|
|
31
31
|
"@npmcli/fs": "^4.0.0",
|
|
32
32
|
"@reduxjs/toolkit": "^2.6.1",
|
|
@@ -1,24 +1,38 @@
|
|
|
1
1
|
# Reactive-JSON fetchData Documentation
|
|
2
2
|
|
|
3
3
|
## Introduction
|
|
4
|
-
`fetchData` is a reaction that allows making HTTP
|
|
4
|
+
`fetchData` is a reaction that allows making HTTP requests to a server. It operates in multiple modes, depending on configuration values.
|
|
5
|
+
|
|
6
|
+
- Supports configurable HTTP methods (GET by default for backward compatibility)
|
|
7
|
+
- Only one request can be active at a time
|
|
8
|
+
- The URL is evaluated via the template system before sending, but must resolve to a static string
|
|
9
|
+
- The response can refresh the app (default) or be ignored
|
|
5
10
|
|
|
6
11
|
## Properties
|
|
7
12
|
- `url` (string, required): The URL to call (must be a static string, dynamic URLs are not supported)
|
|
8
|
-
- `
|
|
13
|
+
- `httpMethod` (string, optional): The HTTP method to use (default: "get"). Supports: get, post, put, patch, delete, etc.
|
|
14
|
+
- `refreshAppOnResponse` (boolean, optional): If true (default), the response will update the application. If false, the response is ignored (webhook mode).
|
|
15
|
+
- `updateOnlyData` (boolean, optional): When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false.
|
|
16
|
+
- `updateDataAtLocation` (string, optional): When `updateOnlyData` is true, specifies where to place the response data using template path syntax (e.g., "~~.userProfile", "~.config.settings"). If not specified, replaces the entire data object.
|
|
9
17
|
|
|
10
18
|
## Behavior
|
|
11
|
-
-
|
|
19
|
+
- Supports configurable HTTP methods (GET by default for backward compatibility)
|
|
12
20
|
- Only one request can be active at a time
|
|
13
21
|
- The URL is evaluated via the template system before sending, but must resolve to a static string
|
|
14
|
-
- If `refreshAppOnResponse` is true, the response must be a valid rjbuild and will replace the application state
|
|
15
|
-
- If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
|
|
16
22
|
- Errors are only logged to the console
|
|
17
23
|
- The triggering element is visually disabled during the request
|
|
24
|
+
- When `refreshAppOnResponse` is false, the response is ignored (webhook mode)
|
|
25
|
+
- When `refreshAppOnResponse` is true and `updateOnlyData` is false, the server response must be a valid rjbuild and will replace the entire application state
|
|
26
|
+
- When `refreshAppOnResponse` is true and `updateOnlyData` is true:
|
|
27
|
+
- Only the data section is updated, preserving templates and renderView
|
|
28
|
+
- Without `updateDataAtLocation`: **completely replaces** the entire data object
|
|
29
|
+
- With `updateDataAtLocation`: updates only the specified path in the data
|
|
30
|
+
|
|
31
|
+
> **⚠️ Important:** When using `updateOnlyData: true`, the server response must contain **data only**, not a complete RjBuild structure. The response should be the raw data object, not wrapped in `{data: {...}, renderView: [...], templates: {...}}`.
|
|
18
32
|
|
|
19
33
|
## Examples
|
|
20
34
|
|
|
21
|
-
### Data Loading
|
|
35
|
+
### Data Loading with GET (Default)
|
|
22
36
|
```yaml
|
|
23
37
|
renderView:
|
|
24
38
|
- type: button
|
|
@@ -30,7 +44,7 @@ renderView:
|
|
|
30
44
|
refreshAppOnResponse: true # Response will replace the application state
|
|
31
45
|
```
|
|
32
46
|
|
|
33
|
-
### Simple
|
|
47
|
+
### Simple Webhook Call
|
|
34
48
|
```yaml
|
|
35
49
|
renderView:
|
|
36
50
|
- type: button
|
|
@@ -42,19 +56,131 @@ renderView:
|
|
|
42
56
|
refreshAppOnResponse: false # Response is ignored, like a webhook
|
|
43
57
|
```
|
|
44
58
|
|
|
59
|
+
## Data Update Behavior
|
|
60
|
+
When using `updateOnlyData: true`:
|
|
61
|
+
|
|
62
|
+
### Without updateDataAtLocation (Complete Data Replacement)
|
|
63
|
+
```yaml
|
|
64
|
+
# Before request - original data:
|
|
65
|
+
data:
|
|
66
|
+
userProfile: { name: "John", email: "john@example.com" }
|
|
67
|
+
settings: { theme: "dark" }
|
|
68
|
+
notifications: { count: 5 }
|
|
69
|
+
|
|
70
|
+
# Response from server:
|
|
71
|
+
{
|
|
72
|
+
newUserData: { name: "Jane", email: "jane@example.com" }
|
|
73
|
+
systemStatus: "active"
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
# After request - data is COMPLETELY REPLACED:
|
|
77
|
+
data:
|
|
78
|
+
newUserData: { name: "Jane", email: "jane@example.com" }
|
|
79
|
+
systemStatus: "active"
|
|
80
|
+
# ❌ userProfile, settings, notifications are LOST
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### With updateDataAtLocation (Targeted Update)
|
|
84
|
+
```yaml
|
|
85
|
+
# Before request - original data:
|
|
86
|
+
data:
|
|
87
|
+
userProfile: { name: "John", email: "john@example.com" }
|
|
88
|
+
settings: { theme: "dark" }
|
|
89
|
+
notifications: { count: 5 }
|
|
90
|
+
|
|
91
|
+
# Request with updateDataAtLocation: "~~.userProfile"
|
|
92
|
+
# Response from server:
|
|
93
|
+
{
|
|
94
|
+
name: "Jane",
|
|
95
|
+
email: "jane@example.com",
|
|
96
|
+
avatar: "new-avatar.jpg"
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
# After request - only userProfile is updated:
|
|
100
|
+
data:
|
|
101
|
+
userProfile: { name: "Jane", email: "jane@example.com", avatar: "new-avatar.jpg" }
|
|
102
|
+
settings: { theme: "dark" } # ✅ Preserved
|
|
103
|
+
notifications: { count: 5 } # ✅ Preserved
|
|
104
|
+
```
|
|
105
|
+
|
|
45
106
|
## Use Cases with refreshAppOnResponse: false
|
|
46
107
|
1. Server notifications
|
|
47
108
|
2. Webhooks
|
|
48
109
|
3. API pinging
|
|
49
110
|
4. Triggering server-side actions without waiting for response
|
|
111
|
+
5. Cache invalidation
|
|
112
|
+
6. Remote resource cleanup
|
|
113
|
+
|
|
114
|
+
## Use Cases with updateOnlyData: true
|
|
115
|
+
1. **Refreshing user profile data** without losing application state
|
|
116
|
+
2. **Updating configuration settings** while preserving the UI structure
|
|
117
|
+
3. **Loading additional data** into specific sections
|
|
118
|
+
4. **Partial data synchronization** with the server
|
|
119
|
+
5. **Real-time data updates** for dashboards or live displays
|
|
120
|
+
|
|
121
|
+
## Example use cases
|
|
122
|
+
|
|
123
|
+
### Data-Only Update (Complete Replacement)
|
|
124
|
+
```yaml
|
|
125
|
+
actions:
|
|
126
|
+
- what: fetchData
|
|
127
|
+
on: click
|
|
128
|
+
url: "/api/user/data"
|
|
129
|
+
refreshAppOnResponse: true
|
|
130
|
+
updateOnlyData: true # Only updates data, preserves templates/renderView
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Targeted Data Update
|
|
134
|
+
```yaml
|
|
135
|
+
actions:
|
|
136
|
+
- what: fetchData
|
|
137
|
+
on: click
|
|
138
|
+
url: "/api/user/profile"
|
|
139
|
+
refreshAppOnResponse: true
|
|
140
|
+
updateOnlyData: true
|
|
141
|
+
updateDataAtLocation: "~~.userProfile" # Updates only userProfile section
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Nested Data Update
|
|
145
|
+
```yaml
|
|
146
|
+
actions:
|
|
147
|
+
- what: fetchData
|
|
148
|
+
on: click
|
|
149
|
+
url: "/api/user/settings"
|
|
150
|
+
refreshAppOnResponse: true
|
|
151
|
+
updateOnlyData: true
|
|
152
|
+
updateDataAtLocation: "~~.config.userSettings" # Deep update
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### API Call with Custom Method
|
|
156
|
+
```yaml
|
|
157
|
+
actions:
|
|
158
|
+
- what: fetchData
|
|
159
|
+
on: click
|
|
160
|
+
url: "/api/status"
|
|
161
|
+
httpMethod: "patch"
|
|
162
|
+
refreshAppOnResponse: false # Response is ignored, like a webhook
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### DELETE Request
|
|
166
|
+
```yaml
|
|
167
|
+
actions:
|
|
168
|
+
- what: fetchData
|
|
169
|
+
on: click
|
|
170
|
+
url: "/api/cache"
|
|
171
|
+
httpMethod: "delete"
|
|
172
|
+
refreshAppOnResponse: false
|
|
173
|
+
```
|
|
50
174
|
|
|
51
175
|
## Limitations
|
|
52
176
|
- Only one request can be active at a time
|
|
53
|
-
-
|
|
54
|
-
-
|
|
177
|
+
- Response must be a valid rjbuild **only** if refreshAppOnResponse is true and updateOnlyData is false
|
|
178
|
+
- When `updateOnlyData` is true, the response must contain **data only** (not a complete RjBuild structure)
|
|
55
179
|
- No built-in error handling beyond console logging
|
|
56
180
|
- No support for request cancellation
|
|
57
181
|
- No support for timeouts
|
|
58
182
|
- **No support for dynamic URLs** - URLs must be static strings
|
|
59
183
|
- No support for query parameters in URL templates
|
|
60
|
-
- No support for complex URL routing or path generation
|
|
184
|
+
- No support for complex URL routing or path generation
|
|
185
|
+
- **No request body support** - Use `submitData` if you need to send data in the request body
|
|
186
|
+
- `updateDataAtLocation` paths must be valid template paths that resolve to data locations
|
|
@@ -3,7 +3,7 @@ renderView:
|
|
|
3
3
|
content: |
|
|
4
4
|
# fetchData
|
|
5
5
|
|
|
6
|
-
fetchData is a reaction that allows making HTTP
|
|
6
|
+
fetchData is a reaction that allows making HTTP requests to a server. It operates in two distinct modes:
|
|
7
7
|
|
|
8
8
|
The behavior depends on `refreshAppOnResponse`:
|
|
9
9
|
- If `true` (default): Response must be a valid rjbuild (with renderView/templates/data) as it will be used to re-render the application
|
|
@@ -13,10 +13,13 @@ renderView:
|
|
|
13
13
|
|
|
14
14
|
## Properties
|
|
15
15
|
- `url` (string, required): The URL to call (must be a static string, dynamic URLs are not supported)
|
|
16
|
-
- `
|
|
16
|
+
- `httpMethod` (string, optional): The HTTP method to use (default: "get"). Supports: get, post, put, patch, delete, etc.
|
|
17
|
+
- `refreshAppOnResponse` (boolean, optional): If true (default), the response will update the application. If false, the response is ignored (webhook mode).
|
|
18
|
+
- `updateOnlyData` (boolean, optional): When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false.
|
|
19
|
+
- `updateDataAtLocation` (string, optional): When `updateOnlyData` is true, specifies where to place the response data using template path syntax (e.g., "~~.userProfile", "~.config.settings"). If not specified, replaces the entire data object.
|
|
17
20
|
|
|
18
21
|
## Behavior
|
|
19
|
-
-
|
|
22
|
+
- Supports configurable HTTP methods (GET by default for backward compatibility)
|
|
20
23
|
- Only one request can be active at a time
|
|
21
24
|
- The URL is evaluated via the template system before sending, but must resolve to a static string
|
|
22
25
|
- If `refreshAppOnResponse` is true, the response must be a valid rjbuild and will replace the application state
|
|
@@ -25,17 +28,17 @@ renderView:
|
|
|
25
28
|
- The triggering element is visually disabled during the request
|
|
26
29
|
|
|
27
30
|
- type: RjBuildDescriber
|
|
28
|
-
title: Basic Structure
|
|
31
|
+
title: Basic Structure (GET - Default)
|
|
29
32
|
description:
|
|
30
33
|
- type: Markdown
|
|
31
34
|
content: |
|
|
32
35
|
The basic structure of a fetchData reaction requires a URL and can include the refreshAppOnResponse option.
|
|
33
36
|
|
|
34
|
-
The URL can be a template value that resolves to a static string.
|
|
37
|
+
The URL can be a template value that resolves to a static string. By default, fetchData uses GET method.
|
|
35
38
|
toDescribe:
|
|
36
39
|
renderView:
|
|
37
40
|
- type: button
|
|
38
|
-
content: Basic Example
|
|
41
|
+
content: Basic GET Example
|
|
39
42
|
actions:
|
|
40
43
|
- what: fetchData
|
|
41
44
|
on: click
|
|
@@ -45,6 +48,9 @@ renderView:
|
|
|
45
48
|
content:
|
|
46
49
|
- "URL: "
|
|
47
50
|
- "/mockup-api/fetchData/example.json"
|
|
51
|
+
- type: div
|
|
52
|
+
content:
|
|
53
|
+
- "Method: GET (default)"
|
|
48
54
|
- type: div
|
|
49
55
|
content:
|
|
50
56
|
- "Fetch status: "
|
|
@@ -52,6 +58,41 @@ renderView:
|
|
|
52
58
|
data:
|
|
53
59
|
fetch_status: "Waiting for click"
|
|
54
60
|
|
|
61
|
+
- type: RjBuildDescriber
|
|
62
|
+
title: Custom HTTP Methods
|
|
63
|
+
description:
|
|
64
|
+
- type: Markdown
|
|
65
|
+
content: |
|
|
66
|
+
You can specify different HTTP methods using the `httpMethod` property:
|
|
67
|
+
- GET (default)
|
|
68
|
+
- POST, PUT, PATCH, DELETE
|
|
69
|
+
- Any valid HTTP method
|
|
70
|
+
|
|
71
|
+
> Open the console to see the request details.
|
|
72
|
+
toDescribe:
|
|
73
|
+
renderView:
|
|
74
|
+
- type: button
|
|
75
|
+
content: PATCH Request
|
|
76
|
+
actions:
|
|
77
|
+
- what: fetchData
|
|
78
|
+
on: click
|
|
79
|
+
url: "/mockup-api/fetchData/status.json"
|
|
80
|
+
httpMethod: "patch"
|
|
81
|
+
refreshAppOnResponse: false
|
|
82
|
+
- type: button
|
|
83
|
+
content: DELETE Request
|
|
84
|
+
actions:
|
|
85
|
+
- what: fetchData
|
|
86
|
+
on: click
|
|
87
|
+
url: "/mockup-api/fetchData/status.json"
|
|
88
|
+
httpMethod: "delete"
|
|
89
|
+
refreshAppOnResponse: false
|
|
90
|
+
- type: div
|
|
91
|
+
content:
|
|
92
|
+
- "Custom methods: PATCH, DELETE, etc."
|
|
93
|
+
data:
|
|
94
|
+
method_status: "Ready to test"
|
|
95
|
+
|
|
55
96
|
- type: RjBuildDescriber
|
|
56
97
|
title: Webhook Mode
|
|
57
98
|
description:
|
|
@@ -60,19 +101,23 @@ renderView:
|
|
|
60
101
|
With `refreshAppOnResponse: false`, fetchData behaves like a webhook:
|
|
61
102
|
- Response is completely ignored
|
|
62
103
|
- Only the HTTP call is made
|
|
104
|
+
- Works with any HTTP method
|
|
63
105
|
- Useful for:
|
|
64
106
|
* Server notifications
|
|
65
107
|
* Triggering server-side actions
|
|
66
108
|
* API pinging
|
|
67
109
|
* Sending webhooks
|
|
110
|
+
* Cache invalidation
|
|
111
|
+
* Remote resource cleanup
|
|
68
112
|
toDescribe:
|
|
69
113
|
renderView:
|
|
70
114
|
- type: button
|
|
71
|
-
content: Notify Server
|
|
115
|
+
content: Notify Server (POST)
|
|
72
116
|
actions:
|
|
73
117
|
- what: fetchData
|
|
74
118
|
on: click
|
|
75
119
|
url: "/mockup-api/fetchData/status.json"
|
|
120
|
+
httpMethod: "post"
|
|
76
121
|
refreshAppOnResponse: false # Response is ignored, like a webhook
|
|
77
122
|
- type: div
|
|
78
123
|
content:
|
|
@@ -106,12 +151,179 @@ renderView:
|
|
|
106
151
|
data:
|
|
107
152
|
error_state: "Pending"
|
|
108
153
|
|
|
154
|
+
- type: RjBuildDescriber
|
|
155
|
+
title:
|
|
156
|
+
type: Markdown
|
|
157
|
+
content: |
|
|
158
|
+
Data-Only Update Examples `@ea-lab/reactive-json@0.2.0`
|
|
159
|
+
description:
|
|
160
|
+
- type: Markdown
|
|
161
|
+
content: |
|
|
162
|
+
Properties `updateOnlyData` and `updateDataAtLocation` (added in @ea-lab/reactive-json@0.2.0) allow for more precise data management:
|
|
163
|
+
|
|
164
|
+
- `updateOnlyData: true`: Only updates the data section, preserving templates and renderView
|
|
165
|
+
- `updateDataAtLocation`: Specifies exactly where to place the response data
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
> **⚠️ Important:** When using `updateOnlyData: true`, the server must return **data only**, not a complete RjBuild structure.
|
|
169
|
+
toDescribe:
|
|
170
|
+
additionalDataSource:
|
|
171
|
+
- src: "/mockup-api/fetchData/reset-initial-data.json"
|
|
172
|
+
renderView:
|
|
173
|
+
- type: div
|
|
174
|
+
attributes:
|
|
175
|
+
class: "row mb-3"
|
|
176
|
+
content:
|
|
177
|
+
- type: div
|
|
178
|
+
attributes:
|
|
179
|
+
class: "col-md-6"
|
|
180
|
+
content:
|
|
181
|
+
- type: BsButton
|
|
182
|
+
content: "Complete Data Replacement"
|
|
183
|
+
attributes:
|
|
184
|
+
class: "btn btn-primary mb-2 w-100"
|
|
185
|
+
actions:
|
|
186
|
+
- what: fetchData
|
|
187
|
+
on: click
|
|
188
|
+
url: "/mockup-api/fetchData/complete-replacement.json"
|
|
189
|
+
updateOnlyData: true
|
|
190
|
+
refreshAppOnResponse: true
|
|
191
|
+
|
|
192
|
+
- type: BsAlert
|
|
193
|
+
attributes:
|
|
194
|
+
variant: "info"
|
|
195
|
+
class: "small"
|
|
196
|
+
content: "⚠️ Replaces ALL data (userProfile + settings + status)"
|
|
197
|
+
|
|
198
|
+
- type: div
|
|
199
|
+
attributes:
|
|
200
|
+
class: "col-md-6"
|
|
201
|
+
content:
|
|
202
|
+
- type: BsButton
|
|
203
|
+
content: "Targeted Data Update"
|
|
204
|
+
attributes:
|
|
205
|
+
class: "btn btn-secondary mb-2 w-100"
|
|
206
|
+
actions:
|
|
207
|
+
- what: fetchData
|
|
208
|
+
on: click
|
|
209
|
+
url: "/mockup-api/fetchData/user-profile-update.json"
|
|
210
|
+
updateOnlyData: true
|
|
211
|
+
updateDataAtLocation: "~~.userProfile"
|
|
212
|
+
refreshAppOnResponse: true
|
|
213
|
+
|
|
214
|
+
- type: BsAlert
|
|
215
|
+
attributes:
|
|
216
|
+
variant: "success"
|
|
217
|
+
class: "small"
|
|
218
|
+
content: "✅ Updates ONLY userProfile, preserves settings"
|
|
219
|
+
|
|
220
|
+
- type: div
|
|
221
|
+
attributes:
|
|
222
|
+
class: "text-center mb-3"
|
|
223
|
+
content:
|
|
224
|
+
- type: BsButton
|
|
225
|
+
content: "🔄 Reset to Initial Data"
|
|
226
|
+
attributes:
|
|
227
|
+
class: "btn btn-secondary"
|
|
228
|
+
actions:
|
|
229
|
+
- what: fetchData
|
|
230
|
+
on: click
|
|
231
|
+
url: "/mockup-api/fetchData/reset-initial-data.json"
|
|
232
|
+
updateOnlyData: true
|
|
233
|
+
refreshAppOnResponse: true
|
|
234
|
+
|
|
235
|
+
- type: hr
|
|
236
|
+
|
|
237
|
+
- type: div
|
|
238
|
+
attributes:
|
|
239
|
+
class: "row"
|
|
240
|
+
content:
|
|
241
|
+
- type: div
|
|
242
|
+
attributes:
|
|
243
|
+
class: "col-md-4"
|
|
244
|
+
content:
|
|
245
|
+
- type: h6
|
|
246
|
+
content: "👤 User Profile"
|
|
247
|
+
- type: div
|
|
248
|
+
attributes:
|
|
249
|
+
class: "border p-2 rounded bg-primary bg-opacity-10 small"
|
|
250
|
+
content:
|
|
251
|
+
- type: div
|
|
252
|
+
content:
|
|
253
|
+
- type: strong
|
|
254
|
+
content: "Name: "
|
|
255
|
+
- ~~.userProfile.name
|
|
256
|
+
- type: div
|
|
257
|
+
content:
|
|
258
|
+
- type: strong
|
|
259
|
+
content: "Email: "
|
|
260
|
+
- ~~.userProfile.email
|
|
261
|
+
- type: div
|
|
262
|
+
content:
|
|
263
|
+
- type: strong
|
|
264
|
+
content: "Updated: "
|
|
265
|
+
- ~~.userProfile.lastUpdated
|
|
266
|
+
|
|
267
|
+
- type: div
|
|
268
|
+
attributes:
|
|
269
|
+
class: "col-md-4"
|
|
270
|
+
content:
|
|
271
|
+
- type: h6
|
|
272
|
+
content: "⚙️ Settings"
|
|
273
|
+
- type: div
|
|
274
|
+
attributes:
|
|
275
|
+
class: "border p-2 rounded bg-light small"
|
|
276
|
+
content:
|
|
277
|
+
- type: div
|
|
278
|
+
content:
|
|
279
|
+
- type: strong
|
|
280
|
+
content: "Theme: "
|
|
281
|
+
- ~~.settings.theme
|
|
282
|
+
- type: div
|
|
283
|
+
content:
|
|
284
|
+
- type: strong
|
|
285
|
+
content: "Notifications: "
|
|
286
|
+
- ~~.settings.notifications
|
|
287
|
+
- type: div
|
|
288
|
+
content:
|
|
289
|
+
- type: strong
|
|
290
|
+
content: "Language: "
|
|
291
|
+
- ~~.settings.language
|
|
292
|
+
|
|
293
|
+
- type: div
|
|
294
|
+
attributes:
|
|
295
|
+
class: "col-md-4"
|
|
296
|
+
content:
|
|
297
|
+
- type: h6
|
|
298
|
+
content: "📊 Status"
|
|
299
|
+
- type: div
|
|
300
|
+
attributes:
|
|
301
|
+
class: "border p-2 rounded bg-warning bg-opacity-10 small"
|
|
302
|
+
content:
|
|
303
|
+
- type: div
|
|
304
|
+
content:
|
|
305
|
+
- type: strong
|
|
306
|
+
content: "Online: "
|
|
307
|
+
- ~~.status.online
|
|
308
|
+
- type: div
|
|
309
|
+
content:
|
|
310
|
+
- type: strong
|
|
311
|
+
content: "Last Login: "
|
|
312
|
+
- ~~.status.lastLogin
|
|
313
|
+
|
|
314
|
+
- type: div
|
|
315
|
+
attributes:
|
|
316
|
+
class: "mt-3 alert alert-warning"
|
|
317
|
+
content:
|
|
318
|
+
- type: strong
|
|
319
|
+
content: "How to test:"
|
|
320
|
+
- " Click buttons and watch the data sections above. The first button will replace ALL data, the second will only update the User Profile section."
|
|
321
|
+
|
|
109
322
|
- type: Markdown
|
|
110
323
|
content: |
|
|
111
324
|
## Limitations
|
|
112
325
|
|
|
113
326
|
- Only one request can be active at a time
|
|
114
|
-
- Only GET requests are supported
|
|
115
327
|
- Response must be a valid rjbuild **only** if refreshAppOnResponse is true
|
|
116
328
|
- No built-in error handling beyond console logging
|
|
117
329
|
- No support for request cancellation
|
|
@@ -119,6 +331,7 @@ renderView:
|
|
|
119
331
|
- **No support for dynamic URLs** - URLs must be static strings
|
|
120
332
|
- No support for query parameters in URL templates
|
|
121
333
|
- No support for complex URL routing or path generation
|
|
334
|
+
- **No request body support** - Use `submitData` if you need to send data in the request body
|
|
122
335
|
|
|
123
336
|
- type: Markdown
|
|
124
337
|
content: |
|
|
@@ -153,4 +366,4 @@ renderView:
|
|
|
153
366
|
}
|
|
154
367
|
```
|
|
155
368
|
|
|
156
|
-
Choose the approach that best fits your UX needs.
|
|
369
|
+
Choose the approach that best fits your UX needs.
|
|
@@ -13,16 +13,24 @@
|
|
|
13
13
|
- `data` (object, optional): The data to send. If not specified, data is sent in an object with the structure `{ data: globalDataContext.templateData }`. If `__state` exists in the context, it is automatically added.
|
|
14
14
|
- `refreshAppOnResponse` (boolean, optional): If true (default), reloads the application with the server response. If false, the response is ignored and **no change is made to the application's state or display** (just like `fetchData`).
|
|
15
15
|
- `submitSilently` (boolean, optional): If true, doesn't apply visual disabling styles during submission
|
|
16
|
+
- `updateOnlyData` (boolean, optional): When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false.
|
|
17
|
+
- `updateDataAtLocation` (string, optional): When `updateOnlyData` is true, specifies where to place the response data using template path syntax (e.g., "~~.userProfile", "~.config.settings"). If not specified, replaces the entire data object.
|
|
16
18
|
|
|
17
19
|
## Behavior
|
|
18
20
|
- Only one submission can be active at a time (global lock)
|
|
19
21
|
- The default HTTP method is POST, but can be customized
|
|
20
22
|
- The payload is either the provided `data` object or the full data context
|
|
21
23
|
- Only the first level of the `data` object is evaluated as templates
|
|
22
|
-
- The server response must be a valid rjbuild if `refreshAppOnResponse` is true
|
|
23
|
-
- If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
|
|
24
24
|
- In case of an error, the submission is cancelled and logged to the console
|
|
25
25
|
- Interface elements are visually disabled during submission (unless `submitSilently` is enabled)
|
|
26
|
+
- When `refreshAppOnResponse` is false, the response is ignored (webhook mode)
|
|
27
|
+
- When `refreshAppOnResponse` is true and `updateOnlyData` is false, the server response must be a valid rjbuild and will replace the entire application state
|
|
28
|
+
- When `refreshAppOnResponse` is true and `updateOnlyData` is true:
|
|
29
|
+
- Only the data section is updated, preserving templates and renderView
|
|
30
|
+
- Without `updateDataAtLocation`: **completely replaces** the entire data object
|
|
31
|
+
- With `updateDataAtLocation`: updates only the specified path in the data
|
|
32
|
+
|
|
33
|
+
> **⚠️ Important:** When using `updateOnlyData: true`, the server response must contain **data only**, not a complete RjBuild structure. The response should be the raw data object, not wrapped in `{data: {...}, renderView: [...], templates: {...}}`.
|
|
26
34
|
|
|
27
35
|
## Submission States & Styling
|
|
28
36
|
The system uses a global locking mechanism to handle submissions:
|
|
@@ -125,14 +133,141 @@ This bidirectional state synchronization allows to:
|
|
|
125
133
|
- Save progression state
|
|
126
134
|
- Maintain consistency between client and server
|
|
127
135
|
|
|
136
|
+
## Data Update Behavior
|
|
137
|
+
When using `updateOnlyData: true`:
|
|
138
|
+
|
|
139
|
+
### Without updateDataAtLocation (Complete Data Replacement)
|
|
140
|
+
```yaml
|
|
141
|
+
# Before request - original data:
|
|
142
|
+
data:
|
|
143
|
+
userProfile: { name: "John", email: "john@example.com" }
|
|
144
|
+
settings: { theme: "dark" }
|
|
145
|
+
notifications: { count: 5 }
|
|
146
|
+
|
|
147
|
+
# Server response after submission:
|
|
148
|
+
{
|
|
149
|
+
savedProfile: { name: "Jane", email: "jane@example.com" }
|
|
150
|
+
validationStatus: "success"
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
# After request - data is COMPLETELY REPLACED:
|
|
154
|
+
data:
|
|
155
|
+
savedProfile: { name: "Jane", email: "jane@example.com" }
|
|
156
|
+
validationStatus: "success"
|
|
157
|
+
# ❌ userProfile, settings, notifications are LOST
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### With updateDataAtLocation (Targeted Update)
|
|
161
|
+
```yaml
|
|
162
|
+
# Before request - original data:
|
|
163
|
+
data:
|
|
164
|
+
userProfile: { name: "John", email: "john@example.com" }
|
|
165
|
+
settings: { theme: "dark" }
|
|
166
|
+
notifications: { count: 5 }
|
|
167
|
+
|
|
168
|
+
# Request with updateDataAtLocation: "~~.userProfile"
|
|
169
|
+
# Server response after submission:
|
|
170
|
+
{
|
|
171
|
+
name: "Jane",
|
|
172
|
+
email: "jane@example.com",
|
|
173
|
+
lastUpdated: "2024-01-15T10:30:00Z"
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
# After request - only userProfile is updated:
|
|
177
|
+
data:
|
|
178
|
+
userProfile: { name: "Jane", email: "jane@example.com", lastUpdated: "2024-01-15T10:30:00Z" }
|
|
179
|
+
settings: { theme: "dark" } # ✅ Preserved
|
|
180
|
+
notifications: { count: 5 } # ✅ Preserved
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Use Cases with updateOnlyData: true
|
|
184
|
+
1. **Form submissions** that return updated record data without full page refresh
|
|
185
|
+
2. **Profile updates** that preserve application state and UI structure
|
|
186
|
+
3. **Configuration saves** that update specific settings sections
|
|
187
|
+
4. **Partial data synchronization** after server-side processing
|
|
188
|
+
5. **Status updates** that need to store results in specific data locations
|
|
189
|
+
6. **Multi-step forms** where each step updates different data sections
|
|
190
|
+
|
|
191
|
+
## Example use cases
|
|
192
|
+
|
|
193
|
+
### Data-Only Update (Complete Replacement)
|
|
194
|
+
|
|
195
|
+
In this example, the web service returns the full data that Reactive-JSON
|
|
196
|
+
will load at its data root.
|
|
197
|
+
|
|
198
|
+
```yaml
|
|
199
|
+
actions:
|
|
200
|
+
- what: submitData
|
|
201
|
+
on: click
|
|
202
|
+
url: "/api/user/save"
|
|
203
|
+
data:
|
|
204
|
+
userProfile: ~.userProfile
|
|
205
|
+
refreshAppOnResponse: true
|
|
206
|
+
updateOnlyData: true # Only updates data, preserves templates/renderView
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Targeted Data Update
|
|
210
|
+
|
|
211
|
+
In this example, the web service returns data to put at a specific location.
|
|
212
|
+
|
|
213
|
+
```yaml
|
|
214
|
+
actions:
|
|
215
|
+
- what: submitData
|
|
216
|
+
on: click
|
|
217
|
+
url: "/api/user/profile"
|
|
218
|
+
data:
|
|
219
|
+
name: ~.form.name
|
|
220
|
+
email: ~.form.email
|
|
221
|
+
refreshAppOnResponse: true
|
|
222
|
+
updateOnlyData: true
|
|
223
|
+
updateDataAtLocation: "~~.userProfile" # Updates only userProfile section
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Save Settings to Specific Location
|
|
227
|
+
|
|
228
|
+
In this example, the web service returns data to put at a specific deep location.
|
|
229
|
+
|
|
230
|
+
```yaml
|
|
231
|
+
actions:
|
|
232
|
+
- what: submitData
|
|
233
|
+
on: click
|
|
234
|
+
url: "/api/settings/save"
|
|
235
|
+
data:
|
|
236
|
+
theme: ~.settingsForm.theme
|
|
237
|
+
notifications: ~.settingsForm.notifications
|
|
238
|
+
refreshAppOnResponse: true
|
|
239
|
+
updateOnlyData: true
|
|
240
|
+
updateDataAtLocation: "~~.config.userSettings" # Deep update
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### Form Submission with Response Processing
|
|
244
|
+
|
|
245
|
+
In this example, the submission result returned by the web service is stored
|
|
246
|
+
at a location in data; this location does not need to be initialized before,
|
|
247
|
+
it will be created when needed.
|
|
248
|
+
|
|
249
|
+
```yaml
|
|
250
|
+
actions:
|
|
251
|
+
- what: submitData
|
|
252
|
+
on: click
|
|
253
|
+
url: "/api/form/submit"
|
|
254
|
+
data:
|
|
255
|
+
formData: ~.currentForm
|
|
256
|
+
userId: ~~.currentUser.id
|
|
257
|
+
refreshAppOnResponse: true
|
|
258
|
+
updateOnlyData: true
|
|
259
|
+
updateDataAtLocation: "~~.submissionResult" # Store result separately
|
|
260
|
+
```
|
|
261
|
+
|
|
128
262
|
## Limitations
|
|
129
263
|
- Only one submission can be active at a time (global lock)
|
|
130
264
|
- Only the first level of the `data` object is evaluated as templates
|
|
131
265
|
- Only POST (or custom method) requests are supported
|
|
132
|
-
- The server response must be a valid rjbuild if `refreshAppOnResponse` is true
|
|
266
|
+
- The server response must be a valid rjbuild if `refreshAppOnResponse` is true and `updateOnlyData` is false
|
|
133
267
|
- No built-in error handling beyond console logging
|
|
134
268
|
- No support for request cancellation
|
|
135
269
|
- No support for timeouts
|
|
136
270
|
- No support for dynamic URLs (URLs must be static strings)
|
|
137
271
|
- No support for query parameters in URL templates
|
|
138
|
-
- No support for complex URL routing or path generation
|
|
272
|
+
- No support for complex URL routing or path generation
|
|
273
|
+
- `updateDataAtLocation` paths must be valid template paths that resolve to data locations
|
|
@@ -15,6 +15,8 @@ renderView:
|
|
|
15
15
|
- `data` (object, optional): The data to send. If not specified, data is sent in an object with the structure `{ data: globalDataContext.templateData }`. If `__state` exists in the context, it is automatically added.
|
|
16
16
|
- `refreshAppOnResponse` (boolean, optional): If true (default), reloads the application with the server response. If false, the response is ignored and **no change is made to the application's state or display** (just like `fetchData`).
|
|
17
17
|
- `submitSilently` (boolean, optional): If true, doesn't apply visual disabling styles during submission
|
|
18
|
+
- `updateOnlyData` (boolean, optional): When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false.
|
|
19
|
+
- `updateDataAtLocation` (string, optional): When `updateOnlyData` is true, specifies where to place the response data using template path syntax (e.g., "~~.userProfile", "~.config.settings"). If not specified, replaces the entire data object.
|
|
18
20
|
|
|
19
21
|
## Behavior
|
|
20
22
|
- Only one submission can be active at a time (global lock)
|
|
@@ -127,15 +129,61 @@ renderView:
|
|
|
127
129
|
- Save progression state
|
|
128
130
|
- Maintain consistency between client and server
|
|
129
131
|
|
|
132
|
+
## Data-Only Update Examples (@ea-lab/reactive-json@0.2.0)
|
|
133
|
+
|
|
134
|
+
The properties `updateOnlyData` and `updateDataAtLocation` work identically for `submitData` and `fetchData`.
|
|
135
|
+
|
|
136
|
+
> **⚠️ Important:** When using `updateOnlyData: true`, the server response must contain **data only**, not a complete RjBuild structure. The response should be the raw data object, not wrapped in `{data: {...}, renderView: [...], templates: {...}}`.
|
|
137
|
+
|
|
138
|
+
> **Since this documentation site only supports GET requests**, interactive examples for `submitData` cannot be demonstrated here. However, the behavior is exactly the same as `fetchData`.
|
|
139
|
+
|
|
140
|
+
### ➡️ **See Interactive Examples**
|
|
141
|
+
|
|
142
|
+
Please refer to the **[fetchData documentation](/docs/core/reaction/fetchData)** to see fully interactive demonstrations of:
|
|
143
|
+
|
|
144
|
+
- **Complete Data Replacement** with `updateOnlyData: true`
|
|
145
|
+
- **Targeted Data Updates** with `updateDataAtLocation`
|
|
146
|
+
- **Visual feedback** showing exactly which data sections change
|
|
147
|
+
|
|
148
|
+
### 🔄 **For submitData, the syntax is identical:**
|
|
149
|
+
|
|
150
|
+
```yaml
|
|
151
|
+
# Complete data replacement after form submission
|
|
152
|
+
actions:
|
|
153
|
+
- what: submitData
|
|
154
|
+
on: click
|
|
155
|
+
url: "/api/user/save"
|
|
156
|
+
data: ~~.formData
|
|
157
|
+
updateOnlyData: true
|
|
158
|
+
refreshAppOnResponse: true
|
|
159
|
+
|
|
160
|
+
# Targeted update after form submission
|
|
161
|
+
actions:
|
|
162
|
+
- what: submitData
|
|
163
|
+
on: click
|
|
164
|
+
url: "/api/user/save"
|
|
165
|
+
data: ~~.formData
|
|
166
|
+
updateOnlyData: true
|
|
167
|
+
updateDataAtLocation: "~~.savedProfile"
|
|
168
|
+
refreshAppOnResponse: true
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### 💡 **Common Use Cases for submitData:**
|
|
172
|
+
|
|
173
|
+
- **Form submissions** that return updated record data
|
|
174
|
+
- **Profile updates** that preserve application state
|
|
175
|
+
- **Configuration saves** that update specific settings sections
|
|
176
|
+
- **Multi-step forms** where each step updates different data sections
|
|
177
|
+
|
|
130
178
|
## Limitations
|
|
131
179
|
- Only one submission can be active at a time (global lock)
|
|
132
180
|
- Only the first level of the `data` object is evaluated as templates
|
|
133
181
|
- Only POST (or custom method) requests are supported
|
|
134
|
-
- The server response must be a valid rjbuild if `refreshAppOnResponse` is true
|
|
182
|
+
- The server response must be a valid rjbuild if `refreshAppOnResponse` is true and `updateOnlyData` is false
|
|
183
|
+
- When `updateOnlyData` is true, the response must contain **data only** (not a complete RjBuild structure)
|
|
135
184
|
- No built-in error handling beyond console logging
|
|
136
185
|
- No support for request cancellation
|
|
137
186
|
- No support for timeouts
|
|
138
187
|
- No support for dynamic URLs (URLs must be static strings)
|
|
139
188
|
- No support for query parameters in URL templates
|
|
140
189
|
- No support for complex URL routing or path generation
|
|
141
|
-
|
|
@@ -873,7 +873,6 @@ renderView:
|
|
|
873
873
|
**Need help?**
|
|
874
874
|
|
|
875
875
|
- Check the [Troubleshooting Guide](/docs/troubleshooting/)
|
|
876
|
-
- Join our [Community Discord](https://discord.gg/reactive-json)
|
|
877
876
|
- Open an issue on [GitHub](https://github.com/Ealab-collab/reactive-json/issues)
|
|
878
877
|
|
|
879
878
|
templates:
|