@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/{fui-skill → fui}/references/ui-crosswindow-patterns.md

@@ -1,321 +1,321 @@
-# FUI Cross-window Patterns — openWindow & data exchange
-
-> Owns: **`openWindow`, cross-window data exchange (`#PARENT`/`#Win`), `set.menu` for child modules, `onclose`**.
-
-Open a module as a sub-window and exchange data between windows/iframes (`#PARENT`, `#WinID`). From project **security-manager** and `ex-v3-*` examples. See also [ui-patterns.md](ui-patterns.md), [default-function.md](default-function.md) (`openWindow`, `windowSendMessage`).
-
----
-
-## 1. openWindow
-
-Opens another module as a separate popup window. `id` is the handle for later references.
-
-```json
-{
-  "FUN": "openWindow",
-  "IN": {
-    "id": "`Win1",
-    "title": "`User Permission",
-    "url": "`/UserPermission",
-    "data": "danhSachChoTable",
-    "width": "`800px",
-    "height": "`600px",
-    "onclose": {
-      "CALL": "reloadData"
-    }
-  }
-}
-```
-
-| Param              | Required | Description                                                                 |
-| ------------------ | -------- | --------------------------------------------------------------------------- |
-| `id`               | ✅       | Window id (backtick = literal) — referenced as `#Win1`                      |
-| `url`              | ✅       | Module URL — no `?menu=0`; child declares `"set": { "menu": false }` itself |
-| `title`            | ❌       | Dialog title                                                                |
-| `data`             | ❌       | Data passed to the child — child reads `#PARENT.data`                       |
-| `width` / `height` | ❌       | Window size (`"800px"`, `"50%"`)                                            |
-| `onclose`          | ❌       | Action run after the sub-window closes                                      |
-
-> **Child module:** never pass `?menu=0` in the URL. The child declares `"set": { "menu": false }` in its module.json to hide the menu permanently, regardless of how it's opened. URL carries only the IDs needed to query the DB.
-
-**`onclose` targeting another window:**
-
-```json
-"onclose": {
-  "#Win1": { "CALL": "cmdThongBao" }
-}
-```
-
-> When Win2 closes → runs `cmdThongBao` in Win1 (not the current window).
-
----
-
-## 2. Cross-window data exchange
-
-`#PARENT` and `#WinID` exchange data between windows (iframes). Works same-domain and cross-domain (via `postMessage`).
-
-### Read (value position)
-
-```json
-"data": [
-  {
-    "sUserID":      "#PARENT.sUserID",
-    "sFullName":    "#PARENT.sFullName",
-    "dataFromWin1": "#Win1.apiChart"
-  }
-]
-```
-
-| Syntax            | Meaning                                    |
-| ----------------- | ------------------------------------------ |
-| `"#PARENT.field"` | Read `vueData.field` from parent           |
-| `"#Win1.field"`   | Read `vueData.field` from iframe id `Win1` |
-
-### Write (key position)
-
-```json
-"data": [
-  {
-    "#PARENT.abcdef": 1234567890,
-    "#Win1.dulieuTuForm2": "`huynh cao tuan"
-  }
-]
-```
-
-```json
-":action": {
-  "#PARENT.val4": "DauRaTuCauTruc_IN"
-}
-```
-
-| Syntax                   | Meaning                           |
-| ------------------------ | --------------------------------- |
-| `"#PARENT.field": value` | Write to parent's `vueData.field` |
-| `"#Win1.field": value`   | Write to Win1's `vueData.field`   |
-
-### Call an action in another window
-
-```json
-":action": {
-  "#PARENT": { "CALL": "cmdSETData" }
-}
-```
-
-```json
-"#Win1": { "CALL": "cmdThongBao" }
-```
-
-- `"#PARENT"` (no field) with an action value → `runAction(value)` in parent
-- `"#Win1"` with an action value → `runAction(value)` in Win1
-
-### Receive data passed by openWindow
-
-Parent opens child with `"data": "sourceData"`:
-
-```json
-"data": [
-  {
-    "LayDuLieuWinCha": "#PARENT.Win1"
-  }
-]
-```
-
-> `#PARENT.Win1` reads parent variable `Win1`. When the parent calls `openWindow` with `id: "Win1"`, FUI sets `vueData.Win1 = passed_data` in the parent before opening.
-
-### Full pattern — child receives parent data
-
-**Parent (ex-v3-1SetData):**
-
-```json
-":action": {
-  "FUN": "openWindow",
-  "IN": {
-    "id":   "`Win1",
-    "url":  "`/ex/ex-v3-2CauTruc",
-    "data": "danhSachChoTable"
-  }
-}
-```
-
-**Child (ex-v3-2CauTruc):**
-
-```json
-"data": [
-  {
-    "IF": "typeof menu != 'undefined' && menu=='0'",
-    "THEN": { "v_Set.menu": false }
-  },
-  {
-    "LayDuLieuWinCha":    "#PARENT.Win1",
-    "GiaTriTuCHA.thu.xem": "#PARENT.val7",
-    "GiaTriSetTuCHA":      null
-  }
-]
-```
-
-> Put `#PARENT.*` BEFORE startup CALLs so data is ready before the first API runs.
-
----
-
-## 3. Sub-window checklist
-
-A module opened via `openWindow` needs:
-
-- `"set": { "menu": false }` — hides the navigation header (in module.json, not `?menu=0` in the URL)
-- URL params are injected into `vueData` before `data[]` runs — a trailing `{ "CALL": "apiLoad" }` is enough
-- URL passes only the parent record **ID** the child actually uses — no names or fields re-queryable from the DB
-
-```json
-// module.json của module con
-"set": { "menu": false },
-"data": [
-  { "ContestID": null },
-  {
-    "getDetail": {
-      "API": "/SM_Contest_Detail",
-      "IN": { "ContestID": "ContestID" },
-      "OUT": "dsDetail"
-    }
-  },
-  { "CALL": "getDetail" }
-]
-// ContestID tự động inject từ URL ?ContestID=xxx trước khi data[] chạy
-```
-
----
-
-## 4. Complete parent ↔ child example (`ex-v3-1SetData` → `ex-v3-2CauTruc`)
-
-Standard: **parent opens child via `openWindow` passing table data; child reads/writes/calls back up to parent.**
-
-### 4.1 Parent — f-table + open button, pass `data`
-
-`openWindow.IN.data` passes an object/array (here table list `danhSachChoTable`) to the child; child reads `#PARENT.<id>`.
-
-```json
-{
-  "el": "f-table",
-  "attr": {
-    "label": "Danh sách",
-    ":items": "danhSachChoTable",
-    ":headers": [
-      { "text": "STT", "value": "STT" },
-      { "text": "Họ",  "value": "ho" },
-      { "text": "Tên", "value": "ten" }
-    ]
-  },
-  "w": "6"
-},
-{
-  "el": "f-button",
-  "attr": {
-    "label": "Open Window",
-    ":action": {
-      "FUN": "openWindow",
-      "IN": {
-        "id": "`Win1",
-        "title": "`Chỉnh sửa cho module",
-        "url": "`/ex/ex-v3-2CauTruc",
-        "data": "danhSachChoTable"
-      }
-    }
-  },
-  "w": "3"
-}
-```
-
-Parent can also declare **named actions** for the child to call, and write into the child from `data[]`:
-
-```json
-"data": [
-  { "#PARENT.abcdef": 1234567890, "#Win1": { "CALL": "cmdTHONGBao" } },
-  {
-    "cmdSETData": [
-      { "MESS": "Lệnh của form CHA được gọi từ form CON" },
-      { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }
-    ]
-  }
-]
-```
-
-### 4.2 Child — read parent, write back, call parent, open another child
-
-```json
-// data[] của con: đọc dữ liệu cha NGAY đầu tiên
-"data": [
-  {
-    "LayDuLieuWinCha": "#PARENT.Win1",   // = data cha đã truyền qua openWindow (id=Win1)
-    "GiaTriTuCHA.thu.xem": "#PARENT.val7",
-    "GiaTriSetTuCHA": null
-  }
-],
-"set": { "menu": false, "login": false }
-```
-
-```json
-// Các nút trong controls của con:
-{ "el": "f-button", "attr": { "label": "Lấy dữ liệu từ cha",
-  ":action": { "USERINFO": "#PARENT.val4" } } },
-
-{ "el": "f-button", "attr": { "label": "Set dữ liệu xuống cha",
-  ":action": { "#PARENT.val4": "DauRaTuCauTruc_IN" } } },
-
-{ "el": "f-button", "attr": { "label": "Gọi lệnh ở cha",
-  ":action": { "#PARENT": { "CALL": "cmdSETData" } } } },
-
-{ "el": "f-button", "attr": { "label": "Mở thêm form con",
-  ":action": { "FUN": "openWindow", "IN": {
-    "id": "`Win2",
-    "url": "`https://fui.vn/ex/ex-v3-1SetData",
-    "onclose": { "#Win1": { "CALL": "cmdThongBaoCuaFormNay" } }
-  } } } }
-```
-
-**Syntax summary (value = read, key = write):**
-
-| Syntax                         | Meaning                                                |
-| ------------------------------ | ------------------------------------------------------ |
-| `"x": "#PARENT.field"`         | Read parent `field` into `x`                           |
-| `"x": "#Win1.field"`           | Read `field` of window `Win1`                          |
-| `"#PARENT.field": "src"`       | Write `src` to parent `field`                          |
-| `"#Win1.field": "src"`         | Write to window `Win1`                                 |
-| `"#PARENT": { "CALL": "cmd" }` | Call action `cmd` in parent                            |
-| `"#Win1": { "CALL": "cmd" }`   | Call action in `Win1`                                  |
-| `openWindow.IN.data`           | Pass object/array to child; child reads `#PARENT.<id>` |
-| `openWindow.IN.onclose`        | Action after child closes (may target `#WinX`)         |
-
-> Works **same-domain and cross-domain** (runtime uses `postMessage` across domains).
-
----
-
-## 5. f-table / f-sheet + detail window
-
-Common: list table → click a row → open child window to view/edit that row.
-
-- In `f-table` `headers`, use `t-button` or `t-menu` with `:action` calling `openWindow`; `item` is the current row.
-- Pass **only the row ID** via URL (child queries DB), or the whole row object via `openWindow.IN.data`.
-
-```json
-{
-  "el": "t-button",
-  "text": "Chi tiết",
-  "value": "ID",
-  "align": "center",
-  "attr": {
-    "icon-text": "mdi-eye",
-    "color": "primary",
-    ":action": {
-      "FUN": "openWindow",
-      "IN": {
-        "id": "`WinDetail",
-        "title": "`Chi tiết",
-        "url": "`/DetailModule?RecordID={{item.ID}}",
-        "onclose": { "CALL": "reloadList" }
-      }
-    }
-  }
-}
-```
-
-- **`f-sheet`** (grid-entry spreadsheet) works the same: a button/menu in the sheet calls `openWindow`, or save the sheet's `vueData` then open a child for extra input; the child writes back via `#PARENT.<field>` on close.
-- Reload after child closes: `onclose: { "CALL": "reloadList" }` (runs in the opener window) — see §1.
+# FUI Cross-window Patterns — openWindow & data exchange
+
+> Owns: **`openWindow`, cross-window data exchange (`#PARENT`/`#Win`), `set.menu` for child modules, `onclose`**.
+
+Open a module as a sub-window and exchange data between windows/iframes (`#PARENT`, `#WinID`). From project **security-manager** and `ex-v3-*` examples. See also [ui-patterns.md](ui-patterns.md), [default-function.md](default-function.md) (`openWindow`, `windowSendMessage`).
+
+---
+
+## 1. openWindow
+
+Opens another module as a separate popup window. `id` is the handle for later references.
+
+```json
+{
+  "FUN": "openWindow",
+  "IN": {
+    "id": "`Win1",
+    "title": "`User Permission",
+    "url": "`/UserPermission",
+    "data": "danhSachChoTable",
+    "width": "`800px",
+    "height": "`600px",
+    "onclose": {
+      "CALL": "reloadData"
+    }
+  }
+}
+```
+
+| Param              | Required | Description                                                                 |
+| ------------------ | -------- | --------------------------------------------------------------------------- |
+| `id`               | ✅       | Window id (backtick = literal) — referenced as `#Win1`                      |
+| `url`              | ✅       | Module URL — no `?menu=0`; child declares `"set": { "menu": false }` itself |
+| `title`            | ❌       | Dialog title                                                                |
+| `data`             | ❌       | Data passed to the child — child reads `#PARENT.data`                       |
+| `width` / `height` | ❌       | Window size (`"800px"`, `"50%"`)                                            |
+| `onclose`          | ❌       | Action run after the sub-window closes                                      |
+
+> **Child module:** never pass `?menu=0` in the URL. The child declares `"set": { "menu": false }` in its module.json to hide the menu permanently, regardless of how it's opened. URL carries only the IDs needed to query the DB.
+
+**`onclose` targeting another window:**
+
+```json
+"onclose": {
+  "#Win1": { "CALL": "cmdThongBao" }
+}
+```
+
+> When Win2 closes → runs `cmdThongBao` in Win1 (not the current window).
+
+---
+
+## 2. Cross-window data exchange
+
+`#PARENT` and `#WinID` exchange data between windows (iframes). Works same-domain and cross-domain (via `postMessage`).
+
+### Read (value position)
+
+```json
+"data": [
+  {
+    "sUserID":      "#PARENT.sUserID",
+    "sFullName":    "#PARENT.sFullName",
+    "dataFromWin1": "#Win1.apiChart"
+  }
+]
+```
+
+| Syntax            | Meaning                                    |
+| ----------------- | ------------------------------------------ |
+| `"#PARENT.field"` | Read `vueData.field` from parent           |
+| `"#Win1.field"`   | Read `vueData.field` from iframe id `Win1` |
+
+### Write (key position)
+
+```json
+"data": [
+  {
+    "#PARENT.abcdef": 1234567890,
+    "#Win1.dulieuTuForm2": "`huynh cao tuan"
+  }
+]
+```
+
+```json
+":action": {
+  "#PARENT.val4": "DauRaTuCauTruc_IN"
+}
+```
+
+| Syntax                   | Meaning                           |
+| ------------------------ | --------------------------------- |
+| `"#PARENT.field": value` | Write to parent's `vueData.field` |
+| `"#Win1.field": value`   | Write to Win1's `vueData.field`   |
+
+### Call an action in another window
+
+```json
+":action": {
+  "#PARENT": { "CALL": "cmdSETData" }
+}
+```
+
+```json
+"#Win1": { "CALL": "cmdThongBao" }
+```
+
+- `"#PARENT"` (no field) with an action value → `runAction(value)` in parent
+- `"#Win1"` with an action value → `runAction(value)` in Win1
+
+### Receive data passed by openWindow
+
+Parent opens child with `"data": "sourceData"`:
+
+```json
+"data": [
+  {
+    "LayDuLieuWinCha": "#PARENT.Win1"
+  }
+]
+```
+
+> `#PARENT.Win1` reads parent variable `Win1`. When the parent calls `openWindow` with `id: "Win1"`, FUI sets `vueData.Win1 = passed_data` in the parent before opening.
+
+### Full pattern — child receives parent data
+
+**Parent (ex-v3-1SetData):**
+
+```json
+":action": {
+  "FUN": "openWindow",
+  "IN": {
+    "id":   "`Win1",
+    "url":  "`/ex/ex-v3-2CauTruc",
+    "data": "danhSachChoTable"
+  }
+}
+```
+
+**Child (ex-v3-2CauTruc):**
+
+```json
+"data": [
+  {
+    "IF": "typeof menu != 'undefined' && menu=='0'",
+    "THEN": { "v_Set.menu": false }
+  },
+  {
+    "LayDuLieuWinCha":    "#PARENT.Win1",
+    "GiaTriTuCHA.thu.xem": "#PARENT.val7",
+    "GiaTriSetTuCHA":      null
+  }
+]
+```
+
+> Put `#PARENT.*` BEFORE startup CALLs so data is ready before the first API runs.
+
+---
+
+## 3. Sub-window checklist
+
+A module opened via `openWindow` needs:
+
+- `"set": { "menu": false }` — hides the navigation header (in module.json, not `?menu=0` in the URL)
+- URL params are injected into `vueData` before `data[]` runs — a trailing `{ "CALL": "apiLoad" }` is enough
+- URL passes only the parent record **ID** the child actually uses — no names or fields re-queryable from the DB
+
+```json
+// module.json của module con
+"set": { "menu": false },
+"data": [
+  { "ContestID": null },
+  {
+    "getDetail": {
+      "API": "/SM_Contest_Detail",
+      "IN": { "ContestID": "ContestID" },
+      "OUT": "dsDetail"
+    }
+  },
+  { "CALL": "getDetail" }
+]
+// ContestID tự động inject từ URL ?ContestID=xxx trước khi data[] chạy
+```
+
+---
+
+## 4. Complete parent ↔ child example (`ex-v3-1SetData` → `ex-v3-2CauTruc`)
+
+Standard: **parent opens child via `openWindow` passing table data; child reads/writes/calls back up to parent.**
+
+### 4.1 Parent — f-table + open button, pass `data`
+
+`openWindow.IN.data` passes an object/array (here table list `danhSachChoTable`) to the child; child reads `#PARENT.<id>`.
+
+```json
+{
+  "el": "f-table",
+  "attr": {
+    "label": "Danh sách",
+    ":items": "danhSachChoTable",
+    ":headers": [
+      { "text": "STT", "value": "STT" },
+      { "text": "Họ",  "value": "ho" },
+      { "text": "Tên", "value": "ten" }
+    ]
+  },
+  "w": "6"
+},
+{
+  "el": "f-button",
+  "attr": {
+    "label": "Open Window",
+    ":action": {
+      "FUN": "openWindow",
+      "IN": {
+        "id": "`Win1",
+        "title": "`Chỉnh sửa cho module",
+        "url": "`/ex/ex-v3-2CauTruc",
+        "data": "danhSachChoTable"
+      }
+    }
+  },
+  "w": "3"
+}
+```
+
+Parent can also declare **named actions** for the child to call, and write into the child from `data[]`:
+
+```json
+"data": [
+  { "#PARENT.abcdef": 1234567890, "#Win1": { "CALL": "cmdTHONGBao" } },
+  {
+    "cmdSETData": [
+      { "MESS": "Lệnh của form CHA được gọi từ form CON" },
+      { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }
+    ]
+  }
+]
+```
+
+### 4.2 Child — read parent, write back, call parent, open another child
+
+```json
+// data[] của con: đọc dữ liệu cha NGAY đầu tiên
+"data": [
+  {
+    "LayDuLieuWinCha": "#PARENT.Win1",   // = data cha đã truyền qua openWindow (id=Win1)
+    "GiaTriTuCHA.thu.xem": "#PARENT.val7",
+    "GiaTriSetTuCHA": null
+  }
+],
+"set": { "menu": false, "login": false }
+```
+
+```json
+// Các nút trong controls của con:
+{ "el": "f-button", "attr": { "label": "Lấy dữ liệu từ cha",
+  ":action": { "USERINFO": "#PARENT.val4" } } },
+
+{ "el": "f-button", "attr": { "label": "Set dữ liệu xuống cha",
+  ":action": { "#PARENT.val4": "DauRaTuCauTruc_IN" } } },
+
+{ "el": "f-button", "attr": { "label": "Gọi lệnh ở cha",
+  ":action": { "#PARENT": { "CALL": "cmdSETData" } } } },
+
+{ "el": "f-button", "attr": { "label": "Mở thêm form con",
+  ":action": { "FUN": "openWindow", "IN": {
+    "id": "`Win2",
+    "url": "`https://fui.vn/ex/ex-v3-1SetData",
+    "onclose": { "#Win1": { "CALL": "cmdThongBaoCuaFormNay" } }
+  } } } }
+```
+
+**Syntax summary (value = read, key = write):**
+
+| Syntax                         | Meaning                                                |
+| ------------------------------ | ------------------------------------------------------ |
+| `"x": "#PARENT.field"`         | Read parent `field` into `x`                           |
+| `"x": "#Win1.field"`           | Read `field` of window `Win1`                          |
+| `"#PARENT.field": "src"`       | Write `src` to parent `field`                          |
+| `"#Win1.field": "src"`         | Write to window `Win1`                                 |
+| `"#PARENT": { "CALL": "cmd" }` | Call action `cmd` in parent                            |
+| `"#Win1": { "CALL": "cmd" }`   | Call action in `Win1`                                  |
+| `openWindow.IN.data`           | Pass object/array to child; child reads `#PARENT.<id>` |
+| `openWindow.IN.onclose`        | Action after child closes (may target `#WinX`)         |
+
+> Works **same-domain and cross-domain** (runtime uses `postMessage` across domains).
+
+---
+
+## 5. f-table / f-sheet + detail window
+
+Common: list table → click a row → open child window to view/edit that row.
+
+- In `f-table` `headers`, use `t-button` or `t-menu` with `:action` calling `openWindow`; `item` is the current row.
+- Pass **only the row ID** via URL (child queries DB), or the whole row object via `openWindow.IN.data`.
+
+```json
+{
+  "el": "t-button",
+  "text": "Chi tiết",
+  "value": "ID",
+  "align": "center",
+  "attr": {
+    "icon-text": "mdi-eye",
+    "color": "primary",
+    ":action": {
+      "FUN": "openWindow",
+      "IN": {
+        "id": "`WinDetail",
+        "title": "`Chi tiết",
+        "url": "`/DetailModule?RecordID={{item.ID}}",
+        "onclose": { "CALL": "reloadList" }
+      }
+    }
+  }
+}
+```
+
+- **`f-sheet`** (grid-entry spreadsheet) works the same: a button/menu in the sheet calls `openWindow`, or save the sheet's `vueData` then open a child for extra input; the child writes back via `#PARENT.<field>` on close.
+- Reload after child closes: `onclose: { "CALL": "reloadList" }` (runs in the opener window) — see §1.