Page fragment trong trang admin là cơ chế cho phép can thiệp vào giao diện admin thông qua nội dung cấu hình, không cần sửa template hay build lại mã nguồn. Với EzyArticle, điểm móc cho admin đã có sẵn trong layout ezyadmin.html, nên việc cần làm là xác định đúng template của màn hình admin, suy ra pageName, rồi tạo page fragment tương ứng.

Nguyên lý hoạt động

Khi một trang admin được render, EzyArticle lấy đường dẫn template của trang đó, chuyển thành tên view, rồi thêm tiền tố admin_ để tạo pageName cho page fragment.
Ví dụ:
Template path: ezyarticle/posts/list
Page fragment pageName: admin_ezyarticle_posts_list
Fragment name: container
Trong layout admin, fragment container được đọc ở ba vùng:
  • additionalHead: chèn thêm nội dung vào phần <head>, thường dùng cho CSS, meta, link.
  • content: thay thế vùng nội dung chính của trang admin.
  • additionalFoot: chèn thêm nội dung gần cuối trang, thường dùng cho script.
flowchart TD
    A[Người dùng mở trang admin] --> B[Admin controller trả về template]
    B --> C[EzyArticle đổi template path thành view name]
    C --> D[Thêm tiền tố admin_ để tạo pageName]
    D --> E[Lấy pageFragments theo pageName]
    E --> F[ezyadmin.html kiểm tra fragment container]
    F --> G{Có content tùy biến?}
    G -->|Có| H[Render content của fragment container]
    G -->|Không| I[Render nội dung gốc của trang]
Điểm quan trọng: nếu container.content khác giá trị mặc định container, layout admin sẽ render nội dung fragment thay cho nội dung gốc của trang. Vì vậy đây là cơ chế can thiệp mạnh, có thể thay toàn bộ phần nội dung chính của một màn hình admin.

Lấy template path bằng Template Explorer

Để biết cần tạo fragment cho màn hình nào, vào:
EzyArticle Admin > Pages > Template Explorer
Hoặc mở trực tiếp:
/ezyarticle/pages/template-explorer
Trong Template Explorer:
  1. Chọn nhóm admin-plugin.
  2. Mở plugin cần kiểm tra.
  3. Tìm file template của màn hình muốn can thiệp, ví dụ:
templates/ezyarticle/posts/list.html
Sau đó lấy phần đường dẫn template bằng cách bỏ templates/ và bỏ .html:
ezyarticle/posts/list
Tiếp theo đổi / và - thành _, rồi thêm tiền tố admin_:
ezyarticle/posts/list
=> ezyarticle_posts_list
=> admin_ezyarticle_posts_list
Đây chính là pageName khi tạo page fragment.

Tạo page fragment trên admin

Sau khi có pageName, vào màn hình Page Fragments:
/ezyarticle/pages/fragments
Tạo hoặc mở fragment theo dạng:
/ezyarticle/pages/{pageName}/fragments/container
Ví dụ với màn hình danh sách bài viết:
/ezyarticle/pages/admin_ezyarticle_posts_list/fragments/container
Nếu fragment chưa tồn tại, hệ thống sẽ tự tạo một post loại FRAGMENT và chuyển sang màn hình chỉnh sửa.
Thông tin fragment cần nhớ:
pageName: admin_ezyarticle_posts_list
fragmentName: container
postType: FRAGMENT
editor: text

Công thức đặt tên

Với trang admin, fragment mặc định nên dùng:
fragmentName = container
Công thức tổng quát:
pageName = admin_ + templatePath.replace("/", "_").replace("-", "_")
fragmentName = container
Ví dụ:
Template path: ezyarticle/pages/list
Page name: admin_ezyarticle_pages_list
Fragment URL: /ezyarticle/pages/admin_ezyarticle_pages_list/fragments/container

Template path: ezyarticle/setting/index
Page name: admin_ezyarticle_setting_index
Fragment URL: /ezyarticle/pages/admin_ezyarticle_setting_index/fragments/container

Viết nội dung fragment

Nếu muốn thay vùng nội dung chính của trang admin, viết HTML vào phần content của fragment:
<div class="card">
    <div class="card-header">
        <h3 class="card-title">Nội dung quản trị tùy biến</h3>
    </div>
    <div class="card-body">
        Nội dung này sẽ thay thế phần content mặc định của trang admin.
    </div>
</div>
Nếu chỉ muốn thêm CSS hoặc script mà vẫn giữ nội dung gốc, không thay content. Chỉ điền additionalHead hoặc additionalFoot.
Ví dụ CSS trong additionalHead:
<style>
.custom-admin-block {
    border-left: 4px solid #007bff;
    padding-left: 12px;
}
</style>
Ví dụ script trong additionalFoot:
<script>
console.log('Custom admin fragment loaded');
</script>

Quản lý bằng VS Code

Ngoài tạo trực tiếp trên admin, có thể dùng EzyArticle VS Code extension để quản lý page fragment dạng file.
Cấu trúc thư mục:
page-fragments
    admin_ezyarticle_posts_list
        container
            content.html
            head.html
            foot.html
            meta.json
Trong đó:
  • admin_ezyarticle_posts_list là pageName.
  • container là fragmentName.
  • content.html là nội dung chính.
  • head.html tương ứng additionalHead.
  • foot.html tương ứng additionalFoot.
  • meta.json chứa metadata của fragment.
Ví dụ meta.json: 
{
  "title": "Admin posts list container",
  "contentType": "HTML",
  "status": "DRAFT"
}
Ví dụ content.html:
<div class="card">
    <div class="card-header">
        <h3 class="card-title">Nội dung admin tùy biến</h3>
    </div>
    <div class="card-body">
        Nội dung này sẽ thay thế phần content mặc định của trang admin.
    </div>
</div>
Luồng làm việc trong VS Code:
  1. Mở project EzyArticle đã khởi tạo bằng extension.
  2. Tạo thư mục theo cấu trúc page-fragments/{pageName}/{fragmentName}.
  3. Viết nội dung vào content.html, head.html, foot.html.
  4. Chuột phải vào folder fragment hoặc file fragment.
  5. Chọn Publish Content To Server để publish lên admin server.
Nếu fragment đã tồn tại trên server, có thể đồng bộ về local bằng các menu:
  • Sync Page Fragment: đồng bộ danh sách page fragment.
  • Sync Page Fragment Folder: đồng bộ toàn bộ một fragment.
  • Refresh Page Fragment File: đồng bộ riêng từng file content.html, head.html, foot.html, meta.json.
Lưu ý: lưu file trong VS Code chỉ lưu local hoặc lịch sử nội dung, chưa làm thay đổi giao diện admin. Muốn giao diện admin thay đổi thật thì phải Publish Content To Server.

Lưu ý khi sử dụng

Fragment container có thể thay thế toàn bộ nội dung gốc của trang admin. Vì vậy chỉ nên ghi content khi thật sự muốn override giao diện chính.
Nếu mục tiêu chỉ là thêm CSS, thêm script, hoặc can thiệp nhỏ, nên dùng head.html hoặc foot.html và giữ content.html ở trạng thái mặc định.
Cơ chế này cũng phụ thuộc vào setting cho phép thêm page fragment vào admin view. Nếu setting này chưa bật, biến pageFragments sẽ không được inject vào view và fragment sẽ không ảnh hưởng tới giao diện admin.