Cài đặt và sử dụng — Hello (Plugin mẫu)

Tổng quan

Plugin @digiforce-nc/plugin-hello là plugin mẫu (boilerplate/template) dành cho developer muốn học cách phát triển plugin cho DigiForce. Plugin minh hoạ đầy đủ cấu trúc, vòng đời, cách đăng ký UI widget (Block, Action, Field), và cách tích hợp client/server.

Mục đích

Đây không phải plugin dùng trong production. Hãy dùng làm điểm khởi đầu khi tạo plugin mới.

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-hello và bật lên.

Bước 2: Khám phá code mẫu

Sau khi kích hoạt, plugin đăng ký các widget mẫu vào hệ thống. Mục đích chính là đọc source code để hiểu cấu trúc.

Cấu trúc thư mục

plugin-hello/
├── src/
│   ├── index.ts              # Entry point
│   ├── server/
│   │   ├── plugin.ts         # PluginHelloServer (lifecycle hooks)
│   │   └── collections/      # Định nghĩa collection mẫu
│   ├── client/
│   │   ├── index.tsx          # PluginHelloClient (đăng ký widgets)
│   │   └── locale.ts         # Đa ngôn ngữ
│   └── locale/                # File dịch

Vòng đời plugin phía server

PluginHelloServer kế thừa class Plugin và implement các lifecycle method:

Method	Thời điểm	Mục đích
`afterAdd()`	Sau khi plugin được thêm vào app	Đăng ký sớm trước khi load
`beforeLoad()`	Trước khi load	Đăng ký hooks, middleware, ACL
`load()`	Khi load plugin	Import collections, đăng ký resources, actions
`install()`	Lần cài đặt đầu tiên	Seed data, tạo dữ liệu ban đầu
`afterEnable()`	Sau khi bật plugin	Xử lý khi admin bật plugin
`afterDisable()`	Sau khi tắt plugin	Dọn dẹp khi admin tắt plugin
`remove()`	Khi gỡ plugin	Xoá dữ liệu, clean up

Plugin đăng ký tổng cộng 14 widget mẫu để minh hoạ các loại widget khác nhau:

Widget	Kế thừa	Scene	Mô tả
`Hello1BlockWidget`	`BlockWidget`	—	Block đơn giản nhất, không cần data source
`Hello2BlockWidget`	`DataBlockWidget`	—	Block có data source
`Hello3BlockWidget`	`CollectionBlockWidget`	`many`	Block hiển thị nhiều bản ghi
`Hello4BlockWidget`	`CollectionBlockWidget`	`oam`	Block one-and-many
`Hello5BlockWidget`	`CollectionBlockWidget`	`new`	Block tạo mới bản ghi
`Hello6BlockWidget`	`CollectionBlockWidget`	`select`	Block chọn bản ghi
`Hello7BlockWidget`	`CollectionBlockWidget`	`one`	Block hiển thị một bản ghi
`Hello8BlockWidget`	`FilterBlockWidget`	—	Block bộ lọc

Widget	Scene	Mô tả
`Hello1ActionWidget`	`collection`	Action áp dụng cho collection
`Hello2ActionWidget`	`record`	Action áp dụng cho từng record
`Hello3ActionWidget`	`all`	Action áp dụng mọi context
`Hello4ActionWidget`	`all`	Popup Action — mở popup khi click

Widget	Loại	Binding	Mô tả
`Hello1FieldWidget`	Display	`DisplayItemWidget` → `input`	Hiển thị giá trị (chỉ đọc)
`Hello2FieldWidget`	Editable	`EditableItemWidget` + `FilterableItemWidget` → `input`	Input có thể chỉnh sửa và lọc

Cách tạo plugin mới từ template

Bước 1: Copy và đổi tên

bash

cp -r packages/plugins/@digiforce/plugin-hello packages/plugins/@digiforce/plugin-my-feature

Bước 2: Cập nhật `package.json`

json

{
  "name": "@digiforce-nc/plugin-my-feature",
  "version": "1.0.0",
  "displayName": "My Feature"
}

Bước 3: Đổi tên class

PluginHelloServer → PluginMyFeatureServer
PluginHelloClient → PluginMyFeatureClient

Bước 4: Implement logic

Thêm collection vào server/collections/
Đăng ký action handler trong server/plugin.ts
Tạo UI widget trong client/index.tsx

Bước 5: Đăng ký plugin

Thêm plugin vào danh sách plugin của ứng dụng.

Lưu ý quan trọng

Server plugin hiện tại là shell trống — tất cả lifecycle method đều rỗng
Toàn bộ logic mẫu nằm ở client (đăng ký widget)
Mỗi widget mẫu render "Hello, Digiforce!" — thay bằng logic riêng của bạn
Plugin không có displayName hay description trong package.json — nhớ thêm khi tạo plugin thật