Cài đặt và sử dụng — UI Templates

Tổng quan

Plugin cung cấp hệ thống template cho UI widgets/blocks. Bạn có thể lưu bất kỳ block đã cấu hình nào thành template, sau đó tái sử dụng ở nhiều trang khác nhau với chế độ reference (liên kết) hoặc copy (sao chép).

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

Vào Settings → Plugin Manager, tìm plugin-ui-templates và bật.

Hoặc kích hoạt qua dòng lệnh:

yarn pm enable plugin-ui-templates

Bước 2: Lưu block thành template

1. Mở trang có block muốn lưu thành template
2. Vào Design Mode → click block → chọn Save as Template
3. Nhập tên và mô tả cho template
4. Template sẽ được lưu vào collection uiWidgetTemplates

Bước 3: Sử dụng template

Chế độ Reference (liên kết)

Khi chọn chế độ reference, widget trỏ đến template gốc:

• Ưu điểm: Sửa template 1 lần → tất cả nơi sử dụng tự động cập nhật
• Hạn chế: Không thể tùy chỉnh riêng cho từng nơi

Cách plugin lưu reference:

// Trong options của widget
{
  stepParams: {
    referenceSettings: {
      useTemplate: {
        mode: 'reference',
        templateUid: 'tpl-xxx-xxx'
      }
    }
  }
}

Chế độ Copy (sao chép)

Khi chọn chế độ copy, plugin tạo bản sao hoàn chỉnh:

• Ưu điểm: Tùy chỉnh thoải mái, không ảnh hưởng template gốc
• Hạn chế: Không nhận được cập nhật khi template gốc thay đổi

Mẹo

Dùng reference khi muốn đồng bộ (ví dụ: header, footer chung). Dùng copy khi cần điểm khởi đầu rồi tùy chỉnh riêng.

Bước 4: Quản lý templates

Vào Settings → UI Templates để xem tất cả templates:

Thông tin	Mô tả
Tên	Tên template
Mô tả	Mô tả ngắn
Loại widget	Block, Form Grid, v.v.
Collection	Collection liên kết
Số nơi sử dụng	Đếm từ uiWidgetTemplateUsages

Cơ chế Usage Tracking

Plugin tự động theo dõi nơi nào đang sử dụng template nào thông qua collection uiWidgetTemplateUsages. Cơ chế:

Plugin lắng nghe các sự kiện:

Sự kiện	Hành động
uiWidgets.afterSaveWithAssociations	Đồng bộ template usages
uiWidgets.afterDestroy	Xóa usage records của widget bị xóa
Resource action save	Đồng bộ usages cho tree widgets
Resource action destroy	Xóa usages của tree bị xóa
Resource action duplicate	Tạo usages cho bản sao
Resource action mutate	Xử lý batch operations (upsert, destroy, duplicate)

Popup Template Reference

Ngoài block template, plugin còn hỗ trợ popup template — template cho popup/modal view:

// Trong options của widget
{
  stepParams: {
    popupSettings: {
      openView: {
        popupTemplateUid: 'tpl-popup-xxx',
        popupTemplateMode: 'reference'  // hoặc 'copy'
      }
    }
  }
}

Audit Trail

Plugin đăng ký các action sau với audit manager:

Action	Mô tả
uiWidgetTemplates:create	Tạo template mới
uiWidgetTemplates:update	Cập nhật template
uiWidgetTemplates:destroy	Xóa template
uiWidgetTemplateUsages:create	Liên kết template với widget
uiWidgetTemplateUsages:destroy	Xóa liên kết

Lưu ý quan trọng

• Template không chứa dữ liệu, chỉ chứa cấu hình widget/block (layout, fields, settings)
• Khi xóa template đang được reference, các widget sử dụng nó sẽ mất nội dung
• Plugin tự động dọn dẹp usage records khi widget bị xóa — không có dữ liệu rác
• Mỗi node trong widget tree đều được gán uid duy nhất — nếu thiếu, plugin tự động tạo