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
Copy file name to clipboardExpand all lines: aidbox-forms/aidbox-forms-renderer-offline-mode/README.md
+54-12Lines changed: 54 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,17 @@
1
1
# aidbox-forms-renderer-offline-mode
2
2
3
-
Example of using the Aidbox Forms Renderer web component with offline support via request interception (`enable-fetch-proxy` + `onFetch`).
3
+
## Overview
4
+
5
+
### What this example is
6
+
This is a minimal, single-page demo that shows how to render and fill Aidbox Forms with offline support using the <aidbox-forms-renderer> web component and a custom fetch interceptor (`enable-fetch-proxy` + `onFetch`).
7
+
8
+
### Who it’s for
9
+
Teams building caregiver apps where a form can be opened and filled without internet, and then synced to Aidbox when connectivity returns.
10
+
11
+
### Offline behavior
12
+
Previously loaded forms can be opened from the local cache
13
+
Changes are autosaved locally while offline
14
+
Save and submit requests are queued and synchronized when connectivity is restored
4
15
5
16
## How it works
6
17
@@ -66,33 +77,38 @@ When the interceptor returns `null`, the renderer handles the request itself (us
- An Aidbox instance with FHIR resources loaded (Patient, Questionnaires, and pre-created QuestionnaireResponses)
71
-
- A JWT token with access to the FHIR and SDC APIs
80
+
- An Aidbox instance is running localy (e.g. at `http://localhost:8081`).
81
+
- FHIR resources (Patient, Questionnaires, and pre-created QuestionnaireResponses) are added to the Aidbox instance
82
+
- A JWT token with access to the FHIR and SDC APIs is created (see [Aidbox Client Credentials documentation](https://www.health-samurai.io/docs/aidbox/tutorials/security-access-control-tutorials/client-credentials-grant):
83
+
- Go to /ui/console#/iam/sandbox/client.
84
+
- Check the JWT checkbox.
85
+
- Specify the client id and client secret. The default credentials are `client_id=basic`, `secret=secret` (you may replace them with any other valid values. Throughout the documentation, this pair is referred to as client:secret. Use the values you provided in the request)
86
+
- In the sandbox console, execute the API requests by clicking Run for each call sequentially.
87
+
- Copy the JWT from the Access token field.
72
88
- QuestionnaireResponses must be created upfront on the server with:
73
-
-`status: in-progress`
74
-
-`questionnaire` reference pointing to a Questionnaire canonical URL
75
-
-`subject` reference pointing to the patient (e.g. `Patient/pt-1`)
89
+
-`status: in-progress`
90
+
-`questionnaire` reference pointing to a Questionnaire canonical URL
91
+
-`subject` reference pointing to the patient (e.g. `Patient/pt-1`)
76
92
77
93
## Setup
78
94
79
95
1. Open `index.html` in a text editor
80
-
2. Set `AIDBOX_BASE_URL` to your Aidbox instance URL (e.g. `http://localhost:8081`)
96
+
2. Set `AIDBOX_BASE_URL` to your Aidbox instance URL (e.g. `http://localhost:8081`) and adjust `renderer-webcomponent.js` link on line 9 (example: `http://localhost:8081/static/aidbox-forms-renderer-webcomponent.js`)
81
97
3. Set `AIDBOX_TOKEN` to a valid JWT token
82
98
4. Set `PATIENT_ID` to the patient whose assigned forms should be loaded
6. Serve `index.html` via any HTTP server (e.g. `npx serve .`) and open in a browser
103
+
6. Serve `index.html` via any HTTP server (e.g. `npx serve .`) and open generated link in a browser (e.g. `http://localhost:3000`)
88
104
89
105
## Usage
90
106
91
107
1.**First load (online)** — the app fetches assigned QuestionnaireResponses and their Questionnaires, caches them in `localStorage`
92
-
2.**Select a form** — click on a form in the sidebar; status shows "in-progress" or "completed"
108
+
2.**Select a form in left panel** — click on a form in the sidebar; status shows "in-progress" or "completed"
93
109
3.**Fill out forms** — changes auto-save to both `localStorage` and the server
94
110
4.**Submit a form** — status changes to "completed" in the sidebar
95
-
5.**Go offline** (e.g. DevTools Network → Offline) — forms render from cache; saves are queued
111
+
5.**Go offline** (e.g. DevTools Network → Offline) — forms render from cache; saves and submits are stored locally and added to a pending queue.
96
112
6.**Come back online** — pending changes sync automatically
97
113
98
114
The header status bar shows online/offline state, pending change count, and sync progress.
@@ -110,3 +126,29 @@ The header status bar shows online/offline state, pending change count, and sync
110
126
The `onFetch` callback is set as a JS property via the `ref` callback.
111
127
112
128
See the [Aidbox Forms documentation](https://docs.aidbox.app/modules/aidbox-forms/aidbox-ui-builder-alpha/embedding-renderer) for the full list of attributes.
129
+
130
+
### Limitations & data safety notes
131
+
1. Local-only storage: this demo stores cached data and pending operations in localStorage on the current device/browser.
132
+
2. Multiple devices: changes made on one device are not shared with another device. Only the first successful submission will be accepted — avoid filling the same form on multiple devices.
133
+
3. Clearing browser data: if the user clears site data (history/storage) or uses private/incognito mode, offline drafts and cached forms may be lost.
134
+
135
+
### Troubleshooting
136
+
137
+
1. I don’t see any forms in the sidebar:
138
+
- Confirm fixtures are loaded and the patient has assigned QuestionnaireResponses.
139
+
- Confirm PATIENT_ID matches the subject.reference in those QuestionnaireResponses.
140
+
- Confirm your JWT token has permissions to read QuestionnaireResponses and Questionnaires.
141
+
- Confirm you didn't include "Bearer" to the name of the token (`Bearer <token>`).
142
+
2. The form works online but not offline
143
+
- Make sure you opened the page online at least once before going offline.
144
+
- Open the browser devtools and check that cached resources exist in localStorage.
145
+
- Submission requires connectivity; go back online and click Submit again (or wait for auto-sync).
146
+
3. The ./fixtures/load-fixtures.sh http://localhost:8081 client:secret command stalls
147
+
- Verify the client_id and the client secret in client:secret are correct.
148
+
- Verify the Aidbox base URL is correct and reachable (e.g. `http://localhost:8081`).
149
+
- Ensure you run the script from the correct working directory — the one that contains `index.html` (so relative paths used by the script resolve correctly).
150
+
4. The renderer doesn't load
151
+
- Ensure the Aidbox instance URL is correctly specified in `index.html` (line 9) and points to the renderer bundle (e.g. `http://localhost:8081/static/aidbox-forms-renderer-webcomponent.js`)
152
+
- Validate the URL format:
153
+
It should be the full absolute URL with the correct scheme (http) and port.
154
+
Make sure that the link to the renderer bundle contains the correct http type.
0 commit comments