Hướng dẫn tự viết Plugin tùy biến cho PolyCMS — Khung cấu trúc mẫu

Tổng quan

PolyCMS sử dụng một kiến trúc plugin lấy cảm hứng từ WordPress cho phép bạn thêm các tính năng mà không cần chạm vào mã nguồn của mô-đun cốt lõi. Mỗi plugin được đóng gói độc lập trong thư mục riêng với cấu trúc tiêu chuẩn hóa.

Hướng dẫn này sẽ dẫn dắt bạn qua các bước xây dựng một plugin từ con số không. Kết thúc hướng dẫn, bạn sẽ có một khung cấu trúc plugin hoàn chỉnh và hoạt động được để tùy biến cho bất kỳ mục đích nào.

Yêu cầu tiên quyết: Có hiểu biết cơ bản về PHP, framework CodeIgniter và hệ thống hooks của PolyCMS.

Cấu trúc thư mục Plugin

Tất cả các plugin đều nằm trong thư mục modules/polycms/plugins/. Mỗi plugin có cấu trúc như sau:

modules/polycms/plugins/
└── my-custom-plugin/
    ├── plugin.json          # Tệp khai báo thông tin plugin (bắt buộc)
    ├── my-custom-plugin.php # Tệp khởi chạy chính (bắt buộc)
    ├── assets/
    │   ├── css/
    │   │   └── style.css    # CSS của plugin
    │   └── js/
    │       └── script.js    # JS của plugin
    ├── language/
    │   └── english/
    │       └── my_custom_plugin_lang.php
    └── views/
        └── settings.php     # Giao diện trang cài đặt plugin

Mở rộng MTBuilder từ Plugin của bạn

Nếu mục tiêu của bạn là tăng tốc phân phối giao diện người dùng bằng các tài nguyên trực quan hiện có, hãy sử dụng cấu trúc plugin để mở rộng MTBuilder thay vị viết mã cứng (hardcode) từng phần trang đích trong các mẫu PHP.

Các trường hợp sử dụng điển hình:

• Thêm các khối nội dung chuyên biệt (Biểu mẫu liên hệ, Bảng giá, Bảng chạy phản hồi khách hàng, Bộ đếm chỉ số KPI).
• Chèn các thiết lập trực quan có thể tái sử dụng để các nhóm lưu dưới dạng MTBuilder Template Parts.
• Thêm lược đồ cấu hình (settings schema) cho từng khối để người dùng không chuyên kỹ thuật có thể tùy chỉnh.

Cấu trúc thư mục mở rộng được khuyên dùng:

my-custom-plugin/
├── assets/
│   ├── js/
│   │   ├── script.js
│   │   └── mtbuilder-blocks.js   # đăng ký khối block + bộ lọc sidebar
│   └── css/
│       └── mtbuilder-blocks.css  # các kiểu css tùy chọn cho editor/frontend
├── includes/
│   └── class-mtbuilder-extension.php
└── views/
    └── settings.php

Bước 1: Tạo tệp plugin.json

Tệp khai báo plugin.json định nghĩa các siêu dữ liệu (metadata) của plugin của bạn. Tệp này là bắt buộc.

{
    "name": "My Custom Plugin",
    "slug": "my-custom-plugin",
    "description": "Một plugin mẫu minh họa cho kiến trúc plugin của PolyCMS.",
    "version": "1.0.0",
    "author": "Tên Của Bạn",
    "author_url": "https://website-cua-ban.com",
    "requires_polycms": "1.0.0",
    "main_file": "my-custom-plugin.php"
}

Bước 2: Tạo tệp PHP chính của Plugin

Tệp chính sẽ được tải khi plugin được kích hoạt. Đây là nơi bạn đăng ký các hooks và filters của mình.

my-custom-plugin.php

<?php
defined('BASEPATH') or exit('No direct script access allowed');

/**
 * My Custom Plugin cho PolyCMS
 *
 * @version 1.0.0
 * @author  Tên Của Bạn
 */

// =============================================
// ĐĂNG KÝ HOOKS
// =============================================

// Thêm nội dung tùy biến sau mỗi bài viết
polycms_add_filter('polycms_post_content', 'mcp_append_author_box', 20, 1);

// Chèn CSS vào thẻ head của giao diện frontend\polycms_add_action('polycms_head', 'mcp_inject_styles');

// Xử lý tùy biến khi lưu bài viết\polycms_add_action('polycms_post_saved', 'mcp_on_post_saved', 10, 1);

// =============================================
// CÁC HÀM XỬ LÝ (CALLBACKS)
// =============================================

/**
 * Thêm khung thông tin tác giả sau nội dung bài viết
 */
function mcp_append_author_box($content)
{
    $CI = &get_instance();
    $post = $CI->load->get_var('post');

    if (!$post) {
        return $content;
    }

    // Lấy cấu hình plugin
    $show_bio = polycms_get_plugin_option('my-custom-plugin', 'show_author_bio', 'yes');
    if ($show_bio !== 'yes') {
        return $content;
    }

    $author_name = $post->author_name ?? 'Admin';
    $bio_html = '<div class="mcp-author-box">';
    $bio_html .= '<h4>Giới thiệu về Tác giả</h4>';
    $bio_html .= '<p>Bài viết được biên soạn bởi <strong>' . htmlspecialchars($author_name) . '</strong></p>';
    $bio_html .= '</div>';

    return $content . $bio_html;
}

/**
 * Chèn CSS của plugin vào phần đầu trang frontend
 */
function mcp_inject_styles()
{
    $plugin_url = polycms_plugin_url('my-custom-plugin');
    echo '<link rel="stylesheet" href="' . $plugin_url . '/assets/css/style.css">';
}

/**
 * Xử lý khi bài viết được lưu thành công
 */
function mcp_on_post_saved($post)
{
    // Ví dụ: Ghi nhật ký hoạt động lưu bài viết
    log_activity('PolyCMS post saved: ' . $post->title . ' (ID: ' . $post->id . ')');
}

// =============================================
// TRANG CÀI ĐẶT (Tùy chọn)
// =============================================

/**
 * Đăng ký trang cài đặt cho plugin
 */
function mcp_settings_page()
{
    $CI = &get_instance();

    if ($CI->input->post()) {
        // Lưu các tùy chọn cấu hình
        polycms_set_plugin_option('my-custom-plugin', 'show_author_bio', $CI->input->post('show_author_bio'));
        polycms_set_plugin_option('my-custom-plugin', 'bio_template', $CI->input->post('bio_template'));
        set_alert('success', 'Đã lưu cấu hình thành công.');
        redirect(admin_url('polycms/plugins/settings/my-custom-plugin'));
    }

    $data = [
        'show_author_bio' => polycms_get_plugin_option('my-custom-plugin', 'show_author_bio', 'yes'),
        'bio_template'    => polycms_get_plugin_option('my-custom-plugin', 'bio_template', ''),
    ];

    // Tải view cài đặt
    $plugin_path = POLYCMS_PLUGINS_PATH . 'my-custom-plugin/';
    $CI->load->view($plugin_path . 'views/settings', $data);
}

// Đăng ký hàm gọi lại cho trang cấu hình
polycms_register_plugin_settings('my-custom-plugin', 'mcp_settings_page');

Ví dụ Hook MTBuilder trong Plugin

Sử dụng hook app_admin_footer để chỉ tải tệp đăng ký khối khi người dùng đang ở trong trình chỉnh sửa editor:

polycms_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/my-custom-plugin/assets/js/mtbuilder-blocks.js') . '"></script>';
    }
});

Xem thêm hướng dẫn Tạo các khối nội dung tùy biến cho MTBuilder để đăng ký thêm widget mới và Tự thiết kế theme tùy biến cho PolyCMS để hiển thị các khối đó trong các mẫu trang giao diện.

Bước 3: Tạo giao diện cấu hình Settings View

views/settings.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>

<div class="panel_s">
    <div class="panel-heading">
        <h4 class="panel-title">Cấu hình Plugin Tùy biến</h4>
    </div>
    <div class="panel-body">
        <?php echo form_open(admin_url('polycms/plugins/settings/my-custom-plugin')); ?>

        <div class="form-group">
            <label for="show_author_bio">Hiển thị khung thông tin tác giả</label>
            <select name="show_author_bio" id="show_author_bio" class="form-control">
                <option value="yes" <?php echo $show_author_bio === 'yes' ? 'selected' : ''; ?>>Có</option>
                <option value="no" <?php echo $show_author_bio === 'no' ? 'selected' : ''; ?>>Không</option>
            </select>
        </div>

        <div class="form-group">
            <label for="bio_template">Mẫu Bio tùy chọn (HTML)</label>
            <textarea name="bio_template" id="bio_template" class="form-control" rows="5"><?php echo htmlspecialchars($bio_template); ?></textarea>
            <span class="help-block">Để trống để sử dụng mẫu mặc định của hệ thống.</span>
        </div>

        <button type="submit" class="btn btn-primary">Lưu cấu hình</button>
        <?php echo form_close(); ?>
    </div>
</div>

Bước 4: Thêm tệp CSS

assets/css/style.css

.mcp-author-box {
    margin-top: 2rem;
    padding: 1.5rem;
    background: #f8f9fa;
    border-left: 4px solid #82b440;
    border-radius: 8px;
}

.mcp-author-box h4 {
    margin: 0 0 0.5rem 0;
    color: #333;
    font-size: 1rem;
}

Bước 5: Thêm hỗ trợ ngôn ngữ

language/english/my_custom_plugin_lang.php

<?php
defined('BASEPATH') or exit('No direct script access allowed');

$lang['mcp_plugin_name']      = 'My Custom Plugin';
$lang['mcp_show_author_bio']  = 'Show Author Bio Box';
$lang['mcp_bio_template']     = 'Custom Bio Template';
$lang['mcp_settings_saved']   = 'Settings saved successfully.';

Các hàm hỗ trợ Plugin sẵn có

Các hàm trợ giúp sau đây được cung cấp sẵn để sử dụng trong plugin của bạn:

Quy trình cài đặt

1. Tạo thư mục my-custom-plugin/ trong modules/polycms/plugins/.
2. Thêm đầy đủ các tệp tin như mô tả ở trên.
3. Truy cập mục Blog → Plugins trong quản trị Perfex CRM.
4. Tìm plugin "My Custom Plugin" và nhấp vào Kích hoạt (Activate).
5. Cấu hình các tùy chọn thông qua trang Cài đặt của plugin.

Nguyên tắc khuyến nghị

1. Đặt tiền tố (prefix) cho toàn bộ các hàm của bạn (ví dụ: mcp_) để tránh xung đột tên hàm với hệ thống.
2. Luôn kiểm tra hằng số BASEPATH ở đầu mỗi tệp tin PHP.
3. Sử dụng các tùy chọn plugin (options) thay vì viết các câu lệnh truy vấn cơ sở dữ liệu thô để lưu trữ thiết lập.
4. Tối giản tài nguyên tải trang — chỉ tải CSS/JS khi thực sự cần thiết.
5. Hỗ trợ đa ngôn ngữ bằng cách áp dụng cấu trúc thư mục tệp ngôn ngữ chuẩn.
6. Kiểm tra tắt kích hoạt (deactivation) — đảm bảo dọn dẹp sạch sẽ tài nguyên khi tắt plugin.

Cần trợ giúp trong quá trình xây dựng Plugin?

Nếu bạn cần hỗ trợ phát triển plugin tùy biến, có câu hỏi về các API hooks/filters, hoặc muốn thảo luận về ý tưởng tích hợp của mình — hãy liên hệ với chúng tôi bất kỳ lúc nào. Chúng tôi cung cấp hỗ trợ hoàn toàn miễn phí cho tất cả khách hàng PolyCMS.

Chỉ cần để lại câu hỏi của bạn trên trang danh mục sản phẩm của PolyXGO trên CodeCanyon, đội ngũ phát triển của chúng tôi sẽ phản hồi kèm theo hướng dẫn chi tiết, mã nguồn mẫu hoặc hỗ trợ khắc phục sự cố. Cho dù bạn đang xây dựng plugin đầu tiên hay một tích hợp phức tạp, chúng tôi đều sẵn lòng hỗ trợ.

Tài liệu liên quan

• Hướng dẫn tạo các khối nội dung custom blocks cho MTBuilder — Đăng ký các khối widget tùy biến và hệ thống lưới hiển thị trên khung vẽ trực quan của MTBuilder.
• Tài liệu tham khảo đầy đủ về Hooks & Filters — Danh sách chi tiết toàn bộ các điểm neo hooks có sẵn.
• Trình dựng trang trực quan MTBuilder — Tìm hiểu cách các khối nội dung và template parts được sử dụng trong giao diện thiết kế.
• Hướng dẫn tự thiết kế theme tùy biến cho PolyCMS — Khung mẫu phát triển theme tùy chỉnh.
• Tạo Shortcodes tùy chỉnh — Đăng ký các mã ngắn shortcodes từ plugin của bạn.
• Tổng quan về kiến trúc PolyCMS — Hiểu rõ hơn cấu trúc tổng quan của toàn bộ hệ thống.