Hướng dẫn tạo Custom Blocks và Templates cho MTBuilder trên RISE CRM
MTBuilder trong PolyCMS cho RISE CRM vận hành trên bộ máy trạng thái Virtual DOM tách biệt hoàn toàn giao diện kéo thả lúc thiết kế khỏi mã HTML sạch hiển thị cho khách truy cập. Lập trình viên có thể đăng ký khối nội dung tùy biến từ bất kỳ sub-plugin nào thông qua API MTBuilder.registerBlock(), mở rộng bảng điều khiển bằng JavaScript filters, nhúng trực tiếp biểu mẫu thu thập khách hàng tiềm năng của RISE CRM và biên dịch gói tài nguyên nén bằng Webpack.
Kiến trúc cốt lõi và vòng đời lưu trữ
Khi biên tập viên nhấn Save trong MTBuilder, hai lớp dữ liệu đồng bộ được lưu vào cơ sở dữ liệu MySQL của RISE CRM (sử dụng tiền tố động {db_prefix}, mặc định là rise_):
- Lược đồ JSON Virtual DOM (
mtbuilder_data): Lưu trong bảng{db_prefix}blog_page_meta(rise_blog_page_meta). Cây JSON này bảo toàn toàn bộ cấu trúc phần, hàng, cột, cấu hình thuộc tính và lớp CSS để các phiên chỉnh sửa sau tải lại đúng nguyên trạng bố cục. - Bộ nhớ đệm HTML sạch (
content): Được biên dịch quagenerateCleanHtml(), loại bỏ hoàn toàn khung bọc trình dựng, lớp phủ kéo thả và điều khiển quản trị trước khi ghi trực tiếp vào bảng{db_prefix}blog_pages(rise_blog_pages), giúp trang công khai đạt tốc độ tải gần như tức thì.
Các mẫu toàn trang và Template Parts tái sử dụng được lưu trong {db_prefix}blog_mtbuilder_templates (cùng các mẫu giao diện dựng sẵn trong rise_blog_templates / rise_blog_mtbuilder_templates).
API đăng ký khối bằng JavaScript
Lập trình viên đăng ký khối kéo thả mới từ sub-plugin PolyCMS thông qua MTBuilder.registerBlock(blockType, config). Mỗi khối khai báo nhóm thanh bên, biểu tượng, lược đồ cấu hình Inspector và hàm render() hỗ trợ song song hai ngữ cảnh (xem trước trong Editor và mã thực thi ngoài Frontend).
Ví dụ: Tạo khối Biểu mẫu Thu thập Khách hàng RISE CRM
Tạo tệp plugins/polycms/plugins/my-custom-plugin/assets/js/crm-lead-block.js:
MTBuilder.registerBlock('rise_crm_lead_form', {
name: 'RISE CRM Lead Capture Form',
icon: 'fa fa-user-plus',
group: 'crm_integrations',
acceptChildren: false,
// Khai báo cấu hình hiển thị trên thanh bên Inspector
settingsSchema: [
{
key: 'formId',
label: 'Mã biểu mẫu RISE Lead',
type: 'select',
options: {
'1': 'Biểu mẫu đăng ký nhận tin & tư vấn',
'2': 'Biểu mẫu yêu cầu demo doanh nghiệp'
},
default: '1'
},
{
key: 'bgColor',
label: 'Màu nền',
type: 'color',
default: '#f8fafc'
},
{
key: 'buttonText',
label: 'Nhãn nút xem trước',
type: 'text',
default: 'Gửi yêu cầu'
}
],
// Hàm render cho cả khung soạn thảo Editor lẫn trang công khai Frontend
render: function (node, renderChild, isFrontend) {
const el = document.createElement('div');
const formId = encodeURIComponent(node.settings.formId || '1');
const bgColor = node.settings.bgColor || '#f8fafc';
const btnText = node.settings.buttonText || 'Gửi yêu cầu';
el.className = 'mtb-rise-lead-wrap rounded shadow-sm p-4 w-100';
el.style.backgroundColor = bgColor;
if (isFrontend) {
// Frontend công khai: nhúng biểu mẫu thu thập Lead thực tế của RISE CRM
el.innerHTML = `
<div class="rise-crm-lead-form">
Nạp tệp Script khối tùy biến vào trình soạn thảo MTBuilder
Trên RISE CRM, tệp plugins/polycms/index.php gắn vào hook app_hook_layout_main_view_extension trên các trang quản trị PolyCMS rồi kích hoạt cầu nối app_admin_footer. Hãy móc script đăng ký khối vào app_admin_footer và chỉ nạp đúng trên tuyến đường chỉnh sửa MTBuilder để tránh làm nặng các màn hình CRM khác:
app_hooks()->add_action('app_admin_footer', function () {
$CI = &polycms_ci();
$uri = $CI->uri->uri_string();
if (strpos($uri, 'polycms/mtbuilder/editor') !== false) {
$src = polycms_asset_url('plugins/my-custom-plugin/assets/js/crm-lead-block.js');
echo '<script src="' . esc_attr($src) . '"></script>' . "\n";
}
});
Quy trình kết hợp với khung Theme và Plugin
Khi triển khai website thực tế trên RISE CRM, hãy áp dụng trình tự tách biệt trách nhiệm sau:
- Khởi tạo từ một PolyCMS Theme để định hình hệ thống kiểu chữ, đầu trang, chân trang và mẫu trang đích rộng toàn màn hình.
- Đóng gói các khối MTBuilder tùy biến và tích hợp dữ liệu CRM bên trong một PolyCMS Sub-Plugin.
- Để đội ngũ biên tập và tiếp thị lắp ráp nhanh trang đích từ MTBuilder Template Parts cùng các khối tùy biến của bạn.
Liên kết tham khảo nhanh:
- Xây dựng Theme tùy biến cho PolyCMS
- Xây dựng Plugin tùy biến cho PolyCMS
- Hướng dẫn sử dụng trình dựng trang MTBuilder
Tài liệu Hooks và Filters cho lập trình viên
1. Bộ lọc PHP Filters (Biến đổi nội dung)
polycms_post_content và polycms_page_content
Kích hoạt ngay trước khi nội dung HTML của bài viết hoặc trang tĩnh được xuất ra frontend. MTBuilder gắn filter_the_content ở độ ưu tiên 10 để biên dịch các mã ngắn động như [mtbuilder_blog_posts], [mtbuilder_blog_search] và [mtbuilder_blog_directory].
polycms_add_filter('polycms_page_content', function ($content, $page) {
if (function_exists('is_mtbuilder_used') && is_mtbuilder_used($page->id)) {
$content .= '<div class="custom-campaign-banner text-center my-5 p-4 bg-light rounded">'
. '<h3>Cần bản demo theo quy trình riêng?</h3>'
. '<p>Đặt lịch trao đổi trực tiếp cùng đội ngũ triển khai RISE CRM của chúng tôi.</p>'
. '<a href="/lien-he" class="btn btn-primary">Đặt lịch demo</a>'
. '</div>';
}
return $content;
}, 15, 2);
polycms_the_content
Bộ lọc nội dung thống nhất của PolyCMS nơi MTBuilder hoạt động ở độ ưu tiên 10 để giải mã an toàn các shortcode trực quan lồng nhau mà vẫn giữ nguyên các thuộc tính bố cục hợp lệ.
2. Action Hooks PHP (Vòng đời và nạp tài nguyên)
polycms_head
Chạy trong thẻ <head> của theme đang kích hoạt. MTBuilder sử dụng điểm neo này để nạp tệp mtbuilder-frontend.css, đảm bảo hệ thống lưới cột, thẻ bài viết và nút bấm hiển thị chuẩn xác.
polycms_plugin_activated và polycms_plugin_deactivated
Kích hoạt khi quản trị viên bật hoặc tắt sub-plugin trong PolyCMS > Plugins. MTBuilder lắng nghe polycms_plugin_activated để tạo bảng mẫu và khởi tạo sẵn 6 mẫu giao diện chất lượng cao vào {db_prefix}blog_mtbuilder_templates (rise_blog_templates / rise_blog_mtbuilder_templates).
polycms_add_action('polycms_plugin_activated', function ($plugin_file) {
if ($plugin_file === 'mtbuilder/mtbuilder.php') {
$seeder = polycms_module_dir_path('polycms', 'plugins/mtbuilder/includes/seeder.php');
if (is_file($seeder)) {
require_once $seeder;
MTBuilder_Preset_Seeder::run();
}
}
}, 10, 1);
app_admin_footer (Bắc cầu qua app_hook_layout_main_view_extension)
Được kích hoạt ở cuối giao diện quản trị PolyCMS thông qua hook app_hook_layout_main_view_extension của RISE CRM trong plugins/polycms/index.php. MTBuilder dùng điểm neo này để chèn nút Edit with MTBuilder trên màn hình chỉnh sửa Bài viết/Trang và chỉ nạp builder.js tại màn hình polycms/mtbuilder/editor.
app_hooks()->add_action('app_admin_footer', function () {
$CI = &polycms_ci();
$uri = $CI->uri->uri_string();
if (strpos($uri, 'polycms/mtbuilder/editor') !== false) {
echo '<script src="' . esc_attr(polycms_asset_url('plugins/mtbuilder/assets/js/builder.js')) . '"></script>' . "\n";
}
});
3. Bộ lọc JavaScript Filters (Tùy biến không gian làm việc)
Các bộ lọc JavaScript chạy trực tiếp trong trình soạn thảo MTBuilder giúp plugin thêm nhóm danh mục khối mới hoặc mở rộng thuộc tính cho các khối sẵn có.
sidebar_groups
MTBuilder.addFilter('sidebar_groups', function (groups) {
groups.push({
id: 'crm_integrations',
name: 'CRM Integrations',
icon: 'fa fa-handshake'
});
return groups;
});
sidebar_blocks
MTBuilder.addFilter('sidebar_blocks', function (registry) {
if (registry.icon) {
registry.icon.settingsSchema.push({
key: 'customClass',
label: 'Lớp CSS tùy biến',
type: 'text',
default: ''
});
}
return registry;
});
Cô lập CSS và Bảo vệ màu sắc liên kết
Nhằm tránh CSS liên kết toàn cục của theme (đặc biệt trạng thái a:visited) làm sai lệch độ tương phản của nút bấm, MTBuilder áp dụng cơ chế cô lập kiểu dáng ngay trong mtbuilder-frontend.css:
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;
}
Khi biên dịch nút tùy biến, bộ máy kết xuất cũng ghi trực tiếp các thuộc tính kích thước, bo góc và màu sắc vào inline style để giữ giao diện nhất quán trên mọi theme PolyCMS.
Quy trình biên dịch tài nguyên bằng Webpack
MTBuilder sử dụng Webpack kết hợp Terser (nén JavaScript) và Clean-CSS (rút gọn CSS) để xuất gói chạy sản phẩm trong dist/assets/. Sau khi chỉnh sửa mã nguồn trong plugins/polycms/plugins/mtbuilder/assets/, hãy biên dịch lại bằng lệnh:
cd plugins/polycms/plugins/mtbuilder
npm install
npm run build
Luôn tải tài nguyên bằng hàm polycms_asset_url(), hệ thống sẽ tự động trỏ từ đường dẫn phát triển sang tệp .min.js và .min.css đã tối ưu:
echo '<script src="' . esc_attr(polycms_asset_url('plugins/mtbuilder/assets/js/builder.js')) . '"></script>';
// Tự động phân giải thành: /plugins/polycms/plugins/mtbuilder/dist/assets/js/builder.min.js
Tài liệu liên quan
- Xây dựng Plugin tùy biến cho PolyCMS - Khung cấu trúc plugin, PHP docblock header và menu
menu.json. - Xây dựng Theme tùy biến cho PolyCMS - Cách tạo mẫu trang rộng toàn màn hình cho MTBuilder.
- Tài liệu tham khảo đầy đủ về Hooks và Filters - Toàn bộ hook PHP của PolyCMS và RISE CRM.
- Trình dựng trang trực quan MTBuilder - Hướng dẫn sử dụng trình kéo thả và Template Parts cho biên tập viên.