Giao diện
@digiforce-nc/plugin-ui-core
Plugin UI Core engine — quản lý widget tree, xử lý biến template, và cung cấp query service cho giao diện động.
Plugin này làm gì?
Nếu plugin-ui-schema-storage lưu cấu trúc giao diện, thì plugin-ui-core là bộ máy vận hành — nó biết cách đọc widget schema, resolve biến template thành giá trị thực, và chạy query để lấy dữ liệu hiển thị. Ba thành phần này phối hợp tạo nên hệ thống giao diện động hoàn chỉnh.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Widget management | CRUD uiWidgets, duplicate, attach vào parent, move, mutate batch |
| 2 | Variables resolution | Resolve biến template (cú pháp mustache) thành giá trị thực tế |
| 3 | Query service | Chạy query dữ liệu, lưu query tái sử dụng, data binding cho widget |
Kiến trúc — luồng render widget
API endpoints
Widget resource
| Endpoint | Mô tả |
|---|---|
uiWidgets:findOne | Lấy widget theo UID |
uiWidgets:schema | Lấy schema đơn lẻ của widget |
uiWidgets:schemas | Lấy nhiều schema cùng lúc |
uiWidgets:schemaBundle | Bundle schema + toàn bộ descendants |
uiWidgets:save | Lưu widget (tạo mới hoặc cập nhật) |
uiWidgets:duplicate | Nhân bản widget kèm descendants |
uiWidgets:attach | Gắn widget vào parent tại vị trí chỉ định |
uiWidgets:move | Di chuyển widget sang parent khác |
uiWidgets:destroy | Xóa widget kèm descendants |
uiWidgets:mutate | Thực hiện batch operations trên nhiều widget |
Variables
| Endpoint | Mô tả |
|---|---|
variables:resolve | Resolve biến template — nhận danh sách biến dạng path (VD: ctx.currentUser.id), trả về giá trị tương ứng |
Lưu ý: Cú pháp biến sử dụng dạng mustache — tên biến được bao trong cặp ngoặc nhọn kép. Tuy nhiên, plugin thực tế nhận path string qua API, không parse template phía server.
Query service
| Endpoint | Mô tả |
|---|---|
queryService:run | Chạy query trực tiếp (truyền SQL/filter) |
queryService:runById | Chạy query đã lưu theo ID |
queryService:save | Lưu query để tái sử dụng |
queryService:getBind | Lấy data binding — ánh xạ giữa query result và widget field |
Database — 3 bảng chính
| Bảng | Chứa gì | Ví dụ |
|---|---|---|
uiWidgets | Widget definitions (uid, type, options JSON) | { uid: 'w1', type: 'table', options: {...} } |
uiWidgetTreePath | Quan hệ cây widget (closure table) | { ancestor: 'w1', descendant: 'w2', depth: 1 } |
queryService | Query đã lưu (uid, dataSourceKey, sql) | { uid: 'q1', sql: 'SELECT * FROM orders' } |
Thành phần chính phía server
| Thành phần | Mô tả |
|---|---|
UiWidgetRepository | Repository xử lý CRUD widget + tree operations |
UiWidgetSchemaService | Service resolve schema bundle, xử lý inheritance |
Widget Schema Registry | Registry đăng ký widget type mới từ plugin khác |
VariablesService | Service resolve biến template thành giá trị |
QueryServiceManager | Quản lý query execution và caching |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/database | Database ORM (peer) |
@digiforce-nc/server | Server framework (peer) |
@digiforce-nc/client | Client framework (peer) |
@digiforce-nc/plugin-localization | Localization cho widget labels |
Mục lục chi tiết
- Kiến trúc — Widget repository, schema service, variable resolution, query service
- API reference — uiWidgets resource, variables:resolve, queryService
- Database schema — ER diagram, closure table, 3 bảng
- FAQ — Câu hỏi thường gặp