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: docs/SubjectCriteriaBuilderApllication.md
+23-23Lines changed: 23 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ This application is a Streamlit-based tool for interactively building subject se
34
34
35
35
### Pre-requisites
36
36
37
-
Before running the application, you must create a `local.env` file containing your Oracle database credentials.
37
+
Before running the application, you must create a `local.env` file containing your Oracle database credentials.<br>
38
38
You can generate a template for this file by running:
39
39
40
40
```bash
@@ -83,14 +83,14 @@ These credentials are required for the application to connect to the Oracle data
83
83
84
84
### User and Subject Dependencies
85
85
86
-
Some criteria require additional context, such as a User or Subject object.
86
+
Some criteria require additional context, such as a User or Subject object.<br>
87
87
If you select a criterion that has a dependency on "User" or "Subject" (as defined in `criteria.json`):
88
88
89
-
-**User Dependency:**
89
+
-**User Dependency:**
90
90
- A section will appear allowing you to select a user from the list defined in `users.json`.
91
91
- Once selected, the user's name and username are displayed, and a populated user object is created for use in the SQL query.
92
92
93
-
-**Subject Dependency:**
93
+
-**Subject Dependency:**
94
94
- A section will appear allowing you to enter a subject's NHS number.
95
95
- Once entered, the application will attempt to populate a subject object using this NHS number for use in the SQL query.
96
96
@@ -145,16 +145,16 @@ Or, with allowed values and dependencies:
145
145
}
146
146
```
147
147
148
-
-**key:** The unique identifier for the criterion (must match the code).
149
-
-**value_source:** (Optional) The source of the value, can be left blank. This refers to the class + method used in the subject selection query builder. This is not used by the code but is there to allow easier tracking/mapping.
150
-
-**notes:** A clear, user-focused description of what the key is and what the user should input.
151
-
-**allowed_values:** (Optional) An array of allowed values for the dropdown selection.
152
-
-**dependencies:** (Optional) An array that can include `"User"` and/or `"Subject"`. If present, the app will prompt for a user selection or subject NHS number as needed.
148
+
-**`key`:** The unique identifier for the criterion (must match the code).
149
+
-**`value_source`:** (Optional) The source of the value, can be left blank. This refers to the class + method used in the subject selection query builder. This is not used by the code but is there to allow easier tracking/mapping.
150
+
-**`notes`:** A clear, user-focused description of what the key is and what the user should input.
151
+
-**`allowed_values`:** (Optional) An array of allowed values for the dropdown selection.
152
+
-**`dependencies`:** (Optional) An array that can include `"User"` and/or `"Subject"`. If present, the app will prompt for a user selection or subject NHS number as needed.
153
153
154
154
#### To add a new criterion
155
155
156
156
1. Add a new object to the JSON array with the following fields:
157
-
-`"key"`: The Enum member name (must match the code).
157
+
-`"key"`: The `Enum` member name (must match the code).
158
158
-`"value_source"`: (Optional) The value source, can be left blank.
159
159
-`"notes"`: A clear, user-focused description of what the key is and what the user should input.
160
160
-`"allowed_values"`: (Optional) An array of allowed values for the dropdown selection.
@@ -175,19 +175,19 @@ Or, with allowed values and dependencies:
175
175
#### About the `dependencies` field
176
176
177
177
- If a criterion requires a User or Subject context, add a `"dependencies"` array to its entry, e.g.:
178
-
178
+
179
179
```json
180
180
"dependencies": ["User"]
181
181
```
182
182
183
183
or
184
-
184
+
185
185
```json
186
186
"dependencies": ["Subject"]
187
187
```
188
188
189
189
or both:
190
-
190
+
191
191
```json
192
192
"dependencies": ["User", "Subject"]
193
193
```
@@ -198,7 +198,7 @@ Or, with allowed values and dependencies:
198
198
199
199
### Adding New Criteria Keys
200
200
201
-
If you add new keys to the `SubjectSelectionCriteriaKey` Enum in your code, you should also add a corresponding entry in `criteria.json` with a description (`notes`), and (optionally) allowed values and dependencies.
201
+
If you add new keys to the `SubjectSelectionCriteriaKey``Enum` in your code, you should also add a corresponding entry in `criteria.json` with a description (`notes`), and (optionally) allowed values and dependencies.
202
202
203
203
---
204
204
@@ -212,22 +212,22 @@ If you add new keys to the `SubjectSelectionCriteriaKey` Enum in your code, you
212
212
213
213
### Troubleshooting
214
214
215
-
-**A key does not appear in the UI:**
216
-
Ensure it exists in both the `SubjectSelectionCriteriaKey` Enum and in `criteria.json`.
215
+
-**A key does not appear in the UI:**
216
+
Ensure it exists in both the `SubjectSelectionCriteriaKey``Enum` and in `criteria.json`.
217
217
218
-
-**Dropdown is missing for a key:**
218
+
-**Dropdown is missing for a key:**
219
219
Add or update the `"allowed_values"` array for that key in `criteria.json`.
220
220
221
-
-**Descriptions are unclear or missing:**
221
+
-**Descriptions are unclear or missing:**
222
222
Update the `"notes"` field for the relevant key in `criteria.json`.
223
223
224
-
-**App does not reload changes:**
225
-
Save your changes and refresh the Streamlit app in your browser.
224
+
-**App does not reload changes:**
225
+
Save your changes and refresh the `Streamlit` app in your browser.
226
226
227
-
-**Copy to clipboard does not work:**
227
+
-**Copy to clipboard does not work:**
228
228
Some browsers may not support auto-copy. Manually select and copy the JSON from the code block.
229
229
230
-
-**Oracle DB errors:**
230
+
-**Oracle DB errors:**
231
231
Ensure your `local.env` file is present and contains valid values for `ORACLE_USERNAME`, `ORACLE_DB`, and `ORACLE_PASS`.
232
232
233
233
---
@@ -259,5 +259,5 @@ If you add new keys to the `SubjectSelectionCriteriaKey` Enum in your code, you
259
259
-**All configuration is driven by `criteria.json`.**
260
260
-**Descriptions, allowed values, and dependencies are fully customizable.**
261
261
-**No code changes are needed for most updates—just edit the JSON file.**
262
-
-**For new Enum keys, add them to both the `SubjectSelectionCriteriaKey` Enum and the JSON.**
262
+
-**For new `Enum` keys, add them to both the `SubjectSelectionCriteriaKey``Enum` and the JSON.**
263
263
-**For criteria that require user or subject context, use the `dependencies` field.**
0 commit comments