Câu hỏi thường gặp (FAQ) — Hello (Plugin mẫu)

Câu hỏi chung

Plugin này có dùng được trong production không?

Không nên. Plugin hello là template/boilerplate để developer học cách phát triển plugin. Nó không cung cấp chức năng nghiệp vụ nào. Hãy dùng làm điểm khởi đầu rồi phát triển plugin riêng.

Làm sao tạo plugin mới từ Hello?

Copy thư mục plugin-hello sang tên plugin mới
Đổi tên package trong package.json
Đổi tên class PluginHelloServer / PluginHelloClient
Xoá các widget mẫu và thay bằng logic riêng
Đăng ký plugin vào ứng dụng

Plugin mẫu minh hoạ 3 loại chính:

Loại	Base class	Mục đích
Block	`BlockWidget`, `DataBlockWidget`, `CollectionBlockWidget`, `FilterBlockWidget`	Khối giao diện hiển thị dữ liệu
Action	`ActionWidget`, `PopupActionWidget`	Nút hành động (submit, delete, popup...)
Field	`FieldWidget`	Component hiển thị/chỉnh sửa trường dữ liệu

BlockSceneEnum có những giá trị gì?

Scene	Mô tả	Ví dụ
`many`	Hiển thị danh sách nhiều bản ghi	Bảng danh sách, grid
`one`	Hiển thị chi tiết một bản ghi	Trang chi tiết
`new`	Tạo bản ghi mới	Form tạo mới
`select`	Chọn bản ghi	Popup chọn record
`oam`	One-and-many (chi tiết + danh sách con)	Master-detail layout

ActionSceneEnum có những giá trị gì?

Scene	Mô tả	Ví dụ
`collection`	Action cho cả collection	Nút "Create", "Import"
`record`	Action cho từng record	Nút "Edit", "Delete" trên dòng
`all`	Action cho mọi context	Nút tuỳ chỉnh

Câu hỏi kỹ thuật

Sự khác biệt giữa BlockWidget, DataBlockWidget, và CollectionBlockWidget?

BlockWidget: Block đơn giản nhất, không có data source. Phù hợp cho block tĩnh (markdown, HTML).
DataBlockWidget: Có data source nhưng không gắn với collection cụ thể. Phù hợp cho block lấy data từ API tuỳ chỉnh.
CollectionBlockWidget: Gắn với một collection và tự tạo resource. Phù hợp cho CRUD block.
FilterBlockWidget: Block dùng để lọc dữ liệu cho block khác.

DisplayItemWidget vs EditableItemWidget vs FilterableItemWidget khác gì?

Widget	Mục đích	Binding mẫu
`DisplayItemWidget`	Hiển thị giá trị (chỉ đọc)	`Hello1FieldWidget` → `input`
`EditableItemWidget`	Cho phép chỉnh sửa giá trị	`Hello2FieldWidget` → `input`
`FilterableItemWidget`	Cho phép dùng trong bộ lọc	`Hello2FieldWidget` → `input`

Phương thức bindWidgetToUI(widgetName, uiTypes) gắn widget với loại UI field (VD: input, textarea, select).

Lifecycle method nào nên đặt logic gì?

Method	Nên dùng cho
`beforeLoad()`	Đăng ký ACL rules, middleware, hooks trên database
`load()`	Import collections, đăng ký resource actions, cấu hình chính
`install()`	Seed data ban đầu (chỉ chạy lần đầu)
`afterEnable()`	Logic cần chạy khi admin bật plugin (VD: khởi tạo kết nối)
`afterDisable()`	Dọn dẹp khi admin tắt plugin
`remove()`	Xoá sạch dữ liệu khi gỡ plugin

Plugin cần những peer dependencies nào?

Tối thiểu:

json

{
  "peerDependencies": {
    "@digiforce-nc/client": "9.x",
    "@digiforce-nc/server": "9.x"
  }
}

Thêm @digiforce-nc/database nếu plugin có collection, @digiforce-nc/test nếu cần viết test.