ui-soxo-bootstrap-core 2.6.40-dev.0 → 2.6.40-dev.11

package/core/modules/reporting/components/reporting-dashboard/README.md

@@ -1,316 +1,316 @@
-# Reporting Dashboard
-
-This module renders configurable reports using:
-- backend-driven `input_parameters` (filter form)
-- backend-driven `display_columns` (table columns)
-- report data from `CoreScripts.getReportingLisitng(...)`
-
-Main component:
-- `core/modules/reporting/components/reporting-dashboard/reporting-dashboard.js`
-
-Display column internals:
-- `core/modules/reporting/components/reporting-dashboard/display-columns/build-display-columns.js`
-- `core/modules/reporting/components/reporting-dashboard/display-columns/display-cell-renderer.js`
-
-## Data Flow Overview
-
-1. Dashboard loads `CoreScripts.getRecord({ id, dbPtr })`.
-2. It parses:
-- `input_parameters` JSON string -> filter form configuration
-- `display_columns` JSON string -> table column configuration
-3. It submits filter values to `CoreScripts.getReportingLisitng(coreScriptId, formBody, dbPtr)`.
-4. It renders the table with configured display columns.
-
-If `display_columns` is missing, columns are auto-generated from response keys.
-
-## ReportingDashboard Props
-
-Common props:
-- `match` / `reportId`: report id source (`reportId` overrides route id)
-- `dbPtr`: db pointer (falls back to `localStorage.db_ptr`)
-- `CustomComponents`: map of reusable custom components
-- `scope`: optional object to override filter payload body
-- `dashBoardIds`: optional cards for dashboard switching
-- `showScanner`: enables QR scanner button
-- `barcodeFilterKey`: field used to match scanned QR value
-- `isFixedIndex`: fixes index `#` column to left
-- `attributes`: JSON string for extra UI controls (for example `buttonAttributes`)
-
-## Input Parameters Configuration
-
-`input_parameters` is stored as a JSON string in backend and parsed at runtime.
-
-Example:
-
-```json
-[
-  {
-    "title": "From Date",
-    "field": "start",
-    "type": "date",
-    "default": "startOfDay",
-    "required": true
-  },
-  {
-    "title": "To Date",
-    "field": "end",
-    "type": "date",
-    "default": "endOfDay",
-    "required": true
-  },
-  {
-    "title": "Department",
-    "field": "dept_id",
-    "type": "reference-select",
-    "modelName": "Department",
-    "required": false
-  },
-  {
-    "title": "Status",
-    "field": "status",
-    "type": "select",
-    "options": [
-      { "label": "Pending", "value": "Pending" },
-      { "label": "Completed", "value": "Completed" }
-    ]
-  }
-]
-```
-
-### Supported default date values
-
-For `type: "date"`, supported `default` values:
-- `startOfDay`
-- `endOfDay`
-- `startOfWeek`
-- `endOfWeek`
-- `currentDate`
-
-If no date default is provided, current date is used.
-
-### URL synchronization
-
-- On load, if URL contains `?field=value`, that value is used over defaults.
-- On submit, active input values are written back to URL query params.
-- Date values are URL-formatted as `YYYY-MM-DD`.
-
-### Hiding input parameter form
-
-If `other_details1` JSON includes:
-
-```json
-{ "isDisableInputParameters": true }
-```
-
-the input form is hidden, but report data still loads.
-
-## Display Columns Configuration
-
-`display_columns` is also a backend JSON string.
-
-Each entry maps to one table column.
-
-Basic example:
-
-```json
-[
-  { "title": "OP No", "field": "opno", "isSortingEnabled": true },
-  { "title": "Guest Name", "field": "guest_name", "isFilterEnabled": true },
-  { "title": "Amount", "field": "amount", "type": "number", "width": 120 }
-]
-```
-
-### Common column keys
-
-- `title`: header text
-- `tooltip`: optional header tooltip override
-- `field`: record key to display
-- `width`: numeric width (default `160`)
-- `isFixedColumn`: AntD fixed position (`"left"` / `"right"`)
-- `isFilterEnabled`: generates unique-value filters from table data
-- `isSortingEnabled`: enables string sort on `field`
-- `color`: default text color
-- `type: "number"`: right-aligns cell
-
-## Action Columns (Backward-Compatible Rules)
-
-Action logic is intentionally layered to avoid breaking existing reports.
-
-Compatibility rules:
-1. `entry.field === "action"` -> **legacy action** behavior
-2. else if `entry.type === "action"` -> **new action layer**
-3. all other types use existing non-action behavior
-
-### Legacy action example (existing reports)
-
-```json
-{
-  "title": "Action",
-  "field": "action",
-  "redirect_link": "/process/@opb_id;",
-  "replace_variables": [{ "field": "opb_id" }],
-  "display_name_link": "View"
-}
-```
-
-Legacy label behavior:
-- `display_name_link` or `"View"`
-
-### New action layer example (dynamic API label)
-
-```json
-{
-  "title": "Action",
-  "type": "action",
-  "field": "action_text",
-  "redirect_link": "/process/@opb_id;",
-  "replace_variables": [{ "field": "opb_id" }],
-  "label": "View"
-}
-```
-
-New action label fallback order:
-1. `record[entry.field]` (example: `record.action_text`)
-2. `entry.label`
-3. `entry.display_name_link`
-4. `"View"`
-
-## Other Display Types
-
-### External link column
-
-```json
-{ "title": "Report", "field": "report_url", "type": "link" }
-```
-
-Renders anchor with `View` label if URL exists.
-
-### Color tag or span
-
-```json
-{ "title": "Status", "field": "status", "enableColor": true, "columnType": "tag" }
-```
-
-or
-
-```json
-{ "title": "Status", "field": "status", "enableColor": true, "columnType": "span" }
-```
-
-Uses `record.color_code`.
-
-### Dynamic icon mapping
-
-```json
-{
-  "title": "State",
-  "field": "state",
-  "displayIcons": {
-    "Pending": { "icon": "ClockCircleOutlined", "color": "orange", "size": "14px" },
-    "Done": { "icon": "CheckCircleOutlined", "color": "green", "size": "14px" }
-  }
-}
-```
-
-Icon names are taken from `@ant-design/icons`.
-
-### Custom component column
-
-```json
-{
-  "title": "Info",
-  "field": "custom",
-  "component": "ResultEntryInfo",
-  "props": [
-    { "field": "description_text", "value": "description" },
-    { "field": "opb_id", "value": "opbId" }
-  ],
-  "config": { "allowEdit": true }
-}
-```
-
-How it resolves:
-- `component` must exist in merged `CustomComponents`
-- each `props` item maps `record[field]` to prop key `value`
-- `config` is spread as static props
-- `callback` prop triggers dashboard `refresh()`
-
-## Redirect Template Variables
-
-Action redirects support template replacement in `redirect_link`:
-- placeholder format: `@field;`
-- replacements defined in `replace_variables`
-
-Example:
-
-```json
-{
-  "redirect_link": "/lab/@opb_id;/visit/@opno;",
-  "replace_variables": [{ "field": "opb_id" }, { "field": "opno" }]
-}
-```
-
-With row `{ "opb_id": 12, "opno": "OP-55" }`:
-- result -> `/lab/12/visit/OP-55`
-
-## QR Scanner Behavior
-
-When scanner is enabled:
-- scanned value is matched against `patient[barcodeFilterKey]`
-- redirect uses first configured action column with this priority:
-1. legacy action column (`field === "action"`)
-2. new action column (`type === "action"`)
-
-## Export Behavior
-
-- Export uses current table columns.
-- For `field === "custom"`, export attempts to read the prop mapping where `value === "description"` and exports that source field.
-- Other columns export `record[field]`.
-
-## End-to-End Example
-
-`display_columns`:
-
-```json
-[
-  { "title": "OP No", "field": "opno", "isSortingEnabled": true, "width": 140 },
-  { "title": "Guest", "field": "guest_name", "isFilterEnabled": true, "width": 220 },
-  {
-    "title": "Status",
-    "field": "status",
-    "enableColor": true,
-    "columnType": "tag"
-  },
-  {
-    "title": "Action",
-    "type": "action",
-    "field": "action_text",
-    "redirect_link": "/process-detail/@opb_id;",
-    "replace_variables": [{ "field": "opb_id" }],
-    "label": "View"
-  }
-]
-```
-
-Sample API row:
-
-```json
-{
-  "opb_id": 1001,
-  "opno": "OP-1001",
-  "guest_name": "Aisha Rahman",
-  "status": "Pending",
-  "color_code": "orange",
-  "action_text": "Start Consultation"
-}
-```
-
-Rendered action label:
-- `Start Consultation` (dynamic value from API)
-
-## Notes for Developers
-
-- Keep `display_columns` as JSON string in DB for backward compatibility.
-- Prefer `type: "action"` for new dynamic action labels.
-- Reserve `field: "action"` for legacy behavior.
-- If adding new display types, implement in `display-cell-renderer.js` and keep order explicit.
+# Reporting Dashboard
+
+This module renders configurable reports using:
+- backend-driven `input_parameters` (filter form)
+- backend-driven `display_columns` (table columns)
+- report data from `CoreScripts.getReportingLisitng(...)`
+
+Main component:
+- `core/modules/reporting/components/reporting-dashboard/reporting-dashboard.js`
+
+Display column internals:
+- `core/modules/reporting/components/reporting-dashboard/display-columns/build-display-columns.js`
+- `core/modules/reporting/components/reporting-dashboard/display-columns/display-cell-renderer.js`
+
+## Data Flow Overview
+
+1. Dashboard loads `CoreScripts.getRecord({ id, dbPtr })`.
+2. It parses:
+- `input_parameters` JSON string -> filter form configuration
+- `display_columns` JSON string -> table column configuration
+3. It submits filter values to `CoreScripts.getReportingLisitng(coreScriptId, formBody, dbPtr)`.
+4. It renders the table with configured display columns.
+
+If `display_columns` is missing, columns are auto-generated from response keys.
+
+## ReportingDashboard Props
+
+Common props:
+- `match` / `reportId`: report id source (`reportId` overrides route id)
+- `dbPtr`: db pointer (falls back to `localStorage.db_ptr`)
+- `CustomComponents`: map of reusable custom components
+- `scope`: optional object to override filter payload body
+- `dashBoardIds`: optional cards for dashboard switching
+- `showScanner`: enables QR scanner button
+- `barcodeFilterKey`: field used to match scanned QR value
+- `isFixedIndex`: fixes index `#` column to left
+- `attributes`: JSON string for extra UI controls (for example `buttonAttributes`)
+
+## Input Parameters Configuration
+
+`input_parameters` is stored as a JSON string in backend and parsed at runtime.
+
+Example:
+
+```json
+[
+  {
+    "title": "From Date",
+    "field": "start",
+    "type": "date",
+    "default": "startOfDay",
+    "required": true
+  },
+  {
+    "title": "To Date",
+    "field": "end",
+    "type": "date",
+    "default": "endOfDay",
+    "required": true
+  },
+  {
+    "title": "Department",
+    "field": "dept_id",
+    "type": "reference-select",
+    "modelName": "Department",
+    "required": false
+  },
+  {
+    "title": "Status",
+    "field": "status",
+    "type": "select",
+    "options": [
+      { "label": "Pending", "value": "Pending" },
+      { "label": "Completed", "value": "Completed" }
+    ]
+  }
+]
+```
+
+### Supported default date values
+
+For `type: "date"`, supported `default` values:
+- `startOfDay`
+- `endOfDay`
+- `startOfWeek`
+- `endOfWeek`
+- `currentDate`
+
+If no date default is provided, current date is used.
+
+### URL synchronization
+
+- On load, if URL contains `?field=value`, that value is used over defaults.
+- On submit, active input values are written back to URL query params.
+- Date values are URL-formatted as `YYYY-MM-DD`.
+
+### Hiding input parameter form
+
+If `other_details1` JSON includes:
+
+```json
+{ "isDisableInputParameters": true }
+```
+
+the input form is hidden, but report data still loads.
+
+## Display Columns Configuration
+
+`display_columns` is also a backend JSON string.
+
+Each entry maps to one table column.
+
+Basic example:
+
+```json
+[
+  { "title": "OP No", "field": "opno", "isSortingEnabled": true },
+  { "title": "Guest Name", "field": "guest_name", "isFilterEnabled": true },
+  { "title": "Amount", "field": "amount", "type": "number", "width": 120 }
+]
+```
+
+### Common column keys
+
+- `title`: header text
+- `tooltip`: optional header tooltip override
+- `field`: record key to display
+- `width`: numeric width (default `160`)
+- `isFixedColumn`: AntD fixed position (`"left"` / `"right"`)
+- `isFilterEnabled`: generates unique-value filters from table data
+- `isSortingEnabled`: enables string sort on `field`
+- `color`: default text color
+- `type: "number"`: right-aligns cell
+
+## Action Columns (Backward-Compatible Rules)
+
+Action logic is intentionally layered to avoid breaking existing reports.
+
+Compatibility rules:
+1. `entry.field === "action"` -> **legacy action** behavior
+2. else if `entry.type === "action"` -> **new action layer**
+3. all other types use existing non-action behavior
+
+### Legacy action example (existing reports)
+
+```json
+{
+  "title": "Action",
+  "field": "action",
+  "redirect_link": "/process/@opb_id;",
+  "replace_variables": [{ "field": "opb_id" }],
+  "display_name_link": "View"
+}
+```
+
+Legacy label behavior:
+- `display_name_link` or `"View"`
+
+### New action layer example (dynamic API label)
+
+```json
+{
+  "title": "Action",
+  "type": "action",
+  "field": "action_text",
+  "redirect_link": "/process/@opb_id;",
+  "replace_variables": [{ "field": "opb_id" }],
+  "label": "View"
+}
+```
+
+New action label fallback order:
+1. `record[entry.field]` (example: `record.action_text`)
+2. `entry.label`
+3. `entry.display_name_link`
+4. `"View"`
+
+## Other Display Types
+
+### External link column
+
+```json
+{ "title": "Report", "field": "report_url", "type": "link" }
+```
+
+Renders anchor with `View` label if URL exists.
+
+### Color tag or span
+
+```json
+{ "title": "Status", "field": "status", "enableColor": true, "columnType": "tag" }
+```
+
+or
+
+```json
+{ "title": "Status", "field": "status", "enableColor": true, "columnType": "span" }
+```
+
+Uses `record.color_code`.
+
+### Dynamic icon mapping
+
+```json
+{
+  "title": "State",
+  "field": "state",
+  "displayIcons": {
+    "Pending": { "icon": "ClockCircleOutlined", "color": "orange", "size": "14px" },
+    "Done": { "icon": "CheckCircleOutlined", "color": "green", "size": "14px" }
+  }
+}
+```
+
+Icon names are taken from `@ant-design/icons`.
+
+### Custom component column
+
+```json
+{
+  "title": "Info",
+  "field": "custom",
+  "component": "ResultEntryInfo",
+  "props": [
+    { "field": "description_text", "value": "description" },
+    { "field": "opb_id", "value": "opbId" }
+  ],
+  "config": { "allowEdit": true }
+}
+```
+
+How it resolves:
+- `component` must exist in merged `CustomComponents`
+- each `props` item maps `record[field]` to prop key `value`
+- `config` is spread as static props
+- `callback` prop triggers dashboard `refresh()`
+
+## Redirect Template Variables
+
+Action redirects support template replacement in `redirect_link`:
+- placeholder format: `@field;`
+- replacements defined in `replace_variables`
+
+Example:
+
+```json
+{
+  "redirect_link": "/lab/@opb_id;/visit/@opno;",
+  "replace_variables": [{ "field": "opb_id" }, { "field": "opno" }]
+}
+```
+
+With row `{ "opb_id": 12, "opno": "OP-55" }`:
+- result -> `/lab/12/visit/OP-55`
+
+## QR Scanner Behavior
+
+When scanner is enabled:
+- scanned value is matched against `patient[barcodeFilterKey]`
+- redirect uses first configured action column with this priority:
+1. legacy action column (`field === "action"`)
+2. new action column (`type === "action"`)
+
+## Export Behavior
+
+- Export uses current table columns.
+- For `field === "custom"`, export attempts to read the prop mapping where `value === "description"` and exports that source field.
+- Other columns export `record[field]`.
+
+## End-to-End Example
+
+`display_columns`:
+
+```json
+[
+  { "title": "OP No", "field": "opno", "isSortingEnabled": true, "width": 140 },
+  { "title": "Guest", "field": "guest_name", "isFilterEnabled": true, "width": 220 },
+  {
+    "title": "Status",
+    "field": "status",
+    "enableColor": true,
+    "columnType": "tag"
+  },
+  {
+    "title": "Action",
+    "type": "action",
+    "field": "action_text",
+    "redirect_link": "/process-detail/@opb_id;",
+    "replace_variables": [{ "field": "opb_id" }],
+    "label": "View"
+  }
+]
+```
+
+Sample API row:
+
+```json
+{
+  "opb_id": 1001,
+  "opno": "OP-1001",
+  "guest_name": "Aisha Rahman",
+  "status": "Pending",
+  "color_code": "orange",
+  "action_text": "Start Consultation"
+}
+```
+
+Rendered action label:
+- `Start Consultation` (dynamic value from API)
+
+## Notes for Developers
+
+- Keep `display_columns` as JSON string in DB for backward compatibility.
+- Prefer `type: "action"` for new dynamic action labels.
+- Reserve `field: "action"` for legacy behavior.
+- If adding new display types, implement in `display-cell-renderer.js` and keep order explicit.