HeadRandom
Back to Main Site

Hướng dẫn tạo các khối nội dung (Custom Blocks) cho MTBuilder

Last updated on Jul 9, 2026 4:09 PM

Kiến trúc cốt lõi và Vòng đời khối nội dung

MTBuilder vận hành trên một bộ máy trạng thái Virtual DOM hiệu năng cao giúp tách biệt hoàn toàn cấu hình kéo thả lúc thiết kế (design-time) khỏi mã HTML thô hiển thị cho khách truy cập.

Khi người dùng nhấp **Lưu**, hai mô hình dữ liệu sẽ được ghi nhận vào cơ sở dữ liệu MySQL:

  1. Sơ đồ JSON Virtual DOM (mtbuilder_data): Được lưu trữ trong bảng metadata của trang/bài viết (tblblog_page_meta). Tệp này bảo toàn cấu trúc phân cấp lồng nhau, cấu hình thiết lập và ánh xạ class của tất cả các khối nội dung, cho phép trình dựng tải lại giao diện trực quan trong các phiên chỉnh sửa tiếp theo.
  2. Bộ nhớ đệm HTML Sạch (content): Được biên dịch qua trình phân tích sạch (generateCleanHtml()), loại bỏ toàn bộ khung bao của trình biên tập, các lớp phủ kéo thả và menu chuột phải của admin. Mã HTML thô này được lưu trực tiếp vào trường nội dung của bảng tblblog_pages, giúp trang phía frontend tải cực nhanh với độ trễ gần như bằng 0.

---

API đăng ký khối nội dung bằng Javascript

Các lập trình viên có thể mở rộng khung vẽ MTBuilder bằng cách đăng ký các khối nội dung tùy chỉnh từ các plugin độc lập bằng cách sử dụng API JS cốt lõi: MTBuilder.registerBlock(blockType, config).

Ví dụ Code: Tạo khối block "CRM Lead Form"

Tạo một tệp JavaScript tùy chỉnh (ví dụ: crm-lead-block.js) trong phần assets của plugin của bạn:

MTBuilder.registerBlock('crm_lead_form', {
    name: 'CRM Lead Form',
    icon: 'fa fa-user-plus',
    group: 'crm_integrations',
    acceptChildren: false,
    
    // Khai báo schema cấu hình cho bảng điều khiển Sidebar
    settingsSchema: [
        { 
            key: 'formId', 
            label: 'CRM Form', 
            type: 'select', 
            options: { '1': 'Standard Subscription Form', '2': 'Enterprise Contact Form' }, 
            default: '1' 
        },
        { 
            key: 'bgColor', 
            label: 'Màu nền', 
            type: 'color', 
            default: '#f8fafc' 
        },
        { 
            key: 'buttonText', 
            label: 'Nhãn nút', 
            type: 'text', 
            default: 'Gửi yêu cầu' 
        }
    ],

    // Hàm render cho cả giao diện biên tập Editor và giao diện bên ngoài Frontend
    render: function(node, renderChild, isFrontend) {
        const el = document.createElement('div');
        const formId = node.settings.formId || '1';
        const bgColor = node.settings.bgColor || '#f8fafc';
        const btnText = node.settings.buttonText || 'Gửi yêu cầu';
        
        el.className = 'tw-rounded-lg tw-shadow-sm tw-p-6 tw-w-full';
        el.style.backgroundColor = bgColor;
        
        if (isFrontend) {
            // Hiển thị phía Frontend: Render mã nhúng form web-to-lead thực tế của Perfex CRM
            el.innerHTML = `
                <div class="perfex-crm-lead-form">
                    <iframe src="/admin/leads/form/${formId}" width="100%" height="450px" frameborder="0"></iframe>
                </div>
            `;
        } else {
            // Hiển thị trong Editor: Render một khung xem trước tượng trưng để chỉnh sửa kéo thả
            el.innerHTML = `
                <div class="tw-border-2 tw-border-dashed tw-border-slate-200 tw-rounded tw-p-8 tw-text-center">
                    <i class="fa fa-user-plus fa-3x tw-text-indigo-500 tw-mb-2"></i>
                    <h4 class="tw-text-sm tw-font-semibold tw-text-slate-800">Perfex CRM Lead Form</h4>
                    <p class="tw-text-xs tw-text-slate-400 tw-mt-1">Active Form ID: ${formId}</p>
                    <button class="btn btn-primary tw-mt-4">${btnText}</button>
                </div>
            `;
        }
        
        return el;
    }
});

Tải mã Script của khối tùy biến vào Admin Editor

Sau khi đăng ký khối block, hãy chèn tệp script này chỉ trên các tuyến đường chỉnh sửa của MTBuilder:

hooks()->add_action('app_admin_footer', function() {
    $CI = &get_instance();
    $uri = $CI->uri->uri_string();

    if (strpos($uri, 'polycms/mtbuilder/editor') !== false) {
        echo '<script src="' . polycms_asset_url('plugins/your-plugin/assets/js/crm-lead-block.js') . '"></script>';
    }
});

---

Quy trình tích hợp với cấu trúc Theme và Plugin

Khi áp dụng MTBuilder trong các dự án thực tế, hãy tuân thủ thứ tự tích hợp sau:

  1. Bắt đầu từ khung cấu trúc theme để xác định các quy tắc bố cục chung, kiểu chữ và các mẫu trang đích rộng toàn màn hình.
  2. Sử dụng cấu trúc plugin để đăng ký các khối block MTBuilder tùy chỉnh và các tích hợp tùy chọn với bên thứ ba.
  3. Xây dựng các trang nội dung với MTBuilder Template Parts và các khối block tùy chỉnh của bạn để tăng tốc phát triển.

Cách tiếp cận này giúp bạn tái sử dụng tối đa các tài nguyên thiết kế sẵn trong khi vẫn hỗ trợ tốt các khối giao diện đặc thù và hành vi dữ liệu riêng của dự án.

Liên kết nhanh:

---

Danh sách Hooks & Filters tham khảo dành cho lập trình viên

MTBuilder sở hữu kiến trúc hướng sự kiện có khả năng mở rộng cao được xây dựng trên hệ thống Hooks & Filters của PolyCMS. Điều này cho phép các nhà phát triển dễ dàng can thiệp vào bố cục hiển thị, chèn thêm khối tùy biến hoặc đính kèm mã theo dõi.

1. Bộ lọc PHP Filters (Biến đổi dữ liệu)

PHP Filters được sử dụng để can thiệp và sửa đổi dữ liệu nội dung trước khi lưu vào database hoặc render ra frontend.

polycms_post_content

  • Thời điểm kích hoạt: Được gọi ngay trước khi một bài viết hoặc trang tĩnh được hiển thị ngoài giao diện frontend cho người xem.
  • Mục đích: Lọc mã HTML đã biên dịch của bố cục visual layout. MTBuilder sử dụng filter này để chèn thêm các khung bọc lưới cột responsive và css riêng của từng khối.
  • Trường hợp sử dụng: Lập trình viên có thể sử dụng hook này để thay đổi động các thành phần, chèn biểu ngữ quảng cáo hoặc chạy các hàm tìm kiếm-thay thế trên nội dung hiển thị.
  • Ví dụ mã nguồn:
  hooks()->add_filter('polycms_post_content', function($content, $post) {
      // Chèn thêm một biểu ngữ kêu gọi hành động (CTA) tùy biến cho các trang dựng bằng MTBuilder
      $is_builder_page = get_post_meta($post->id, 'mtbuilder_data', true);
      if (!empty($is_builder_page)) {
          $content .= '
          <div class="custom-campaign-banner text-center my-5 p-4 bg-light rounded">
              <h3>Ưu đãi giới hạn đặc biệt!</h3>
              <p>Đăng ký ngay hôm nay để nhận ưu đãi giảm giá 20% cho tất cả các dịch vụ.</p>
              <a href="/register" class="btn btn-primary">Nhận mã giảm giá</a>
          </div>';
      }
      return $content;
  }, 15, 2);

polycms_the_content

  • Thời điểm kích hoạt: Được gọi trước khi nội dung chính của trang/bài viết được xuất ra bởi theme template.
  • Mục đích: Bộ lọc nội dung gốc của PolyCMS. MTBuilder kết nối vào đây với độ ưu tiên (priority) là 10 để xử lý an toàn và giải phóng các mã ngắn shortcodes hoặc khối hình ảnh, bỏ qua các bộ lọc xử lý văn bản mặc định của CRM có thể làm mất thuộc tính HTML sạch.

---

2. Bộ neo sự kiện PHP Action Hooks (Thực thi tác vụ)

PHP Actions được kích hoạt tại các điểm mốc cụ thể trong vòng đời CRM, cho phép các plugin thực thi tác vụ nền hoặc chèn thêm mã header/footer.

polycms_head

  • Thời điểm kích hoạt: Nằm trong thẻ <head> của theme giao diện đang kích hoạt.
  • Mục đích: Phù hợp để tải các tệp css hoặc phông chữ web dynamic. MTBuilder sử dụng action này để tải file mtbuilder-frontend.css giúp các nút bấm, lưới cột và hiệu ứng hiển thị chuẩn xác với khách truy cập.

polycms_plugin_activated

  • Thời điểm kích hoạt: Kích hoạt khi một plugin PolyCMS được chuyển sang trạng thái "Active".
  • Mục đích: MTBuilder sử dụng sự kiện này để đồng bộ và chèn 6 Mẫu giao diện Premium đi kèm cùng các bố cục mặc định vào bảng tblblog_templates.

app_admin_footer

  • Thời điểm kích hoạt: Kích hoạt ở phần chân trang (footer) quản trị của Perfex CRM.
  • Mục đích: MTBuilder sử dụng action này để tải bộ điều khiển Javascript chính của trình biên tập là builder.js và các schema cấu hình. Việc tải này được giới hạn nghiêm ngặt chỉ trong màn hình editor để tránh làm nặng các trang quản trị thông thường khác của CRM.

---

3. Bộ lọc JavaScript Filters (Tùy biến bảng điều khiển Editor)

JS filters chạy bên trong không gian làm việc của editor để cho phép các plugin thay đổi động cấu trúc thanh bên, mở rộng menu hoặc chỉnh sửa khối khi đang kéo thả thiết kế.

sidebar_groups

  • Mục đích: Cho phép plugin của bên thứ ba đăng ký thêm danh mục nhóm khối mới trong danh sách Blocks/Layouts ở thanh bên.
  • Ví dụ mã nguồn:
  MTBuilder.addFilter('sidebar_groups', function(groups) {
      // Thêm nhóm danh mục crm_integrations vào thanh công cụ kéo thả
      groups.push({
          id: 'crm_integrations',
          name: 'CRM Integrations',
          icon: 'fa fa-handshake-o'
      });
      return groups;
  });

---

Cô lập CSS và Bảo vệ liên kết

Để ngăn chặn các định dạng liên kết toàn cục của theme và các trạng thái liên kết đã truy cập (a:visited) làm sai lệch màu sắc nút bấm tùy chỉnh, MTBuilder trang bị một bộ máy cô lập phong cách (Style Isolation Engine):

  • Cô lập trạng thái Visited Link: Các khai báo CSS rõ ràng trong mtbuilder-frontend.css khóa cứng các thuộc tính màu chữ và nền của các class nút bấm hành động chính bằng từ khóa !important:
  a.mtb-button-primary,
  a.mtb-button-primary:visited,
  a.mtb-button-primary:hover {
      color: var(--btn-color) !important;
      background-color: var(--btn-bg) !important;
      text-decoration: none !important;
  }
  • Chèn Style trực tiếp (Inline Style Injection): Khi render các nút tùy chỉnh, trình Javascript sẽ chèn các thuộc tính kích thước, đường viền và màu sắc trực tiếp vào thuộc tính style của phần tử với cờ ưu tiên cao nhất, vượt qua tất cả các khai báo ghi đè mặc định của theme trên mọi khung hình.

---

Hệ thống biên dịch tài nguyên Webpack (Asset Compilation)

PolyCMS sử dụng một **quy trình biên dịch nén Webpack** để tối ưu hóa và phân phối các tệp tài nguyên. Cấu hình build của MTBuilder sẽ tự động nén các file script JS và rút gọn các file stylesheet CSS bằng Terser và Clean-CSS.

Các lệnh Webpack Build

Nếu bạn cập nhật mã nguồn CSS hoặc JS trong thư mục phát triển /assets của plugin, hãy chạy lệnh sau để biên dịch lại:

cd modules/polycms/plugins/mtbuilder
npm install
npm run build

Tải các tài nguyên đã biên dịch

Để duy trì tốc độ và tránh độ trễ của bộ nhớ đệm (cache lag), hãy luôn tải các file tài nguyên thông qua hàm bổ trợ của PolyCMS là polycms_asset_url(). Hàm này tự động hướng các truy vấn đến các gói nén đã rút gọn trong thư mục /dist/assets:

// Hàm phân giải file asset động
echo '<script src="' . polycms_asset_url('plugins/mtbuilder/assets/js/builder.js') . '"></script>';

// Kết quả thực tế: /modules/polycms/plugins/mtbuilder/dist/assets/js/builder.min.js

---

Tài liệu liên quan