Back to Main Site

Hướng dẫn tạo Shortcode tùy biến trong PolyCMS cho RISE CRM

Last updated on Nov 22, 2026 7:38 AM 7:38 AM 2,097.63 ms

Shortcode trong PolyCMS cho RISE CRM cho phép biên tập viên chèn nhanh các khối giao diện động như nút kêu gọi hành động, hộp FAQ đóng mở hay danh sách bài viết mới ngay trong trình soạn thảo TinyMCE bằng cú pháp dấu ngoặc vuông mà không cần viết HTML thủ công. Hoạt động dựa trên thư viện Libraries/Blog_shortcode.php, hệ thống cung cấp các hàm chuẩn polycms_register_shortcode(), polycms_unregister_shortcode(), polycms_do_shortcode() và Blog_shortcode::parse_attributes() giúp plugin và theme mở rộng thành phần động an toàn, chống XSS hiệu quả.

Shortcode tích hợp sẵn và Bộ API cốt lõi

PolyCMS đi kèm sẵn ba shortcode cốt lõi nằm trong plugins/polycms/shortcodes/: [polycms_post], [polycms_category] và [polycms_tag]. Cả shortcode mặc định lẫn shortcode tùy biến đều sử dụng chung bộ API trong Helpers/polycms_template_helper.php và Libraries/Blog_shortcode.php:

Hàm / Phương thức Cú pháp Chức năng
polycms_register_shortcode() polycms_register_shortcode(string $tag, callable $callback): bool Đăng ký hàm xử lý cho thẻ [tag]
polycms_unregister_shortcode() polycms_unregister_shortcode(string $tag): bool Gỡ bỏ một thẻ shortcode đã đăng ký
polycms_do_shortcode() polycms_do_shortcode(string $content): string Phân tích và biên dịch toàn bộ shortcode có trong chuỗi nội dung
shortcode_atts() shortcode_atts(array $pairs, array $atts): array Gộp thuộc tính biên tập viên truyền vào với mảng giá trị mặc định an toàn
Blog_shortcode::parse_attributes() Blog_shortcode::parse_attributes(string $text): array Tách cặp key="value" và tự động ép kiểu boolean (true, false, yes, no, 1, 0, on, off) cùng chuỗi số sang int
Blog_shortcode::exists() Blog_shortcode::exists(string $tag): bool Kiểm tra thẻ shortcode đã được đăng ký hay chưa
Blog_shortcode::strip_shortcodes() Blog_shortcode::strip_shortcodes(string $content): string Loại bỏ toàn bộ mã shortcode khỏi văn bản (hữu ích khi tạo trích dẫn thuần)

Đăng ký một Shortcode tự đóng (Self-Closing)

Hãy đăng ký shortcode tùy biến trong tệp PHP chính của sub-plugin tại plugins/polycms/plugins/{slug}/{slug}.php hoặc tệp functions.php của theme đang hoạt động. Hàm callback nhận ba tham số ($atts, $content = '', $tag = '') và trả về chuỗi HTML.

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

polycms_register_shortcode('my_cta', function ($atts, $content = '', $tag = '') {
    $atts = shortcode_atts([
        'text'  => 'Tìm hiểu thêm',
        'url'   => '#',
        'color' => 'primary',
    ], $atts);

    // Chỉ cho phép các lớp nút hợp lệ
    $allowed_colors = ['primary', 'secondary', 'success', 'dark'];
    $color = in_array((string) $atts['color'], $allowed_colors, true) ? (string) $atts['color'] : 'primary';

    // Chỉ chấp nhận đường dẫn tương đối hoặc http(s) để chặn tấn công javascript: XSS
    $url = trim((string) $atts['url']);
    if ($url !== '#' && !preg_match('#^(/|https?://)#i', $url)) {
        $url = '#';
    }

    return '<div class="cta-block my-4">'
        . '<a href="' . esc_attr($url) . '" class="btn btn-' . esc_attr($color) . '">'
        . html_escape((string) $atts['text'])
        . '</a>'
        . '</div>';
});

Cách biên tập viên sử dụng trong bài viết

[my_cta text="Bắt đầu ngay" url="/bang-gia" color="success"]

Cơ chế phân tích thuộc tính và ép kiểu tự động

Khi Blog_shortcode::do_shortcode() gọi Blog_shortcode::parse_attributes(), cần lưu ý hai đặc điểm kỹ thuật sau:

  1. Cú pháp dấu nháy: Các thuộc tính phải đặt trong cặp dấu nháy kép hoặc nháy đơn (key="value" hoặc key='value').
  2. Tự động ép kiểu: Các giá trị true, 1, yes, on tự động chuyển thành true; các giá trị false, 0, no, off chuyển thành false; chuỗi số nguyên chuyển thành int.

Vì vậy, khi kiểm tra cờ bật/tắt trong callback, hãy chuẩn hóa điều kiện cho cả kiểu boolean lẫn chuỗi:

$is_open = ($atts['open'] === true || $atts['open'] === 'true' || $atts['open'] === '1');

Shortcode dạng bao đóng và lồng nhau (Enclosing & Nested)

Shortcode bao đóng kẹp nội dung giữa thẻ mở [tag] và thẻ đóng [/tag]. Hãy gọi polycms_do_shortcode($content) bên trong callback để các shortcode lồng nhau được biên dịch đệ quy chính xác.

polycms_register_shortcode('my_highlight', function ($atts, $content = '') {
    $atts = shortcode_atts([
        'bg' => '#fef08a',
    ], $atts);

    // Chỉ chấp nhận mã màu hex hợp lệ
    $bg = preg_match('/^#[0-9a-fA-F]{3,6}$/', (string) $atts['bg']) ? (string) $atts['bg'] : '#fef08a';

    return '<span class="polycms-highlight px-1 rounded" style="background-color:' . esc_attr($bg) . ';">'
        . polycms_do_shortcode($content)
        . '</span>';
});

Cách dùng trong nội dung

[my_highlight bg="#dcfce7"]Bản cập nhật quan trọng dành cho quản trị viên RISE CRM.[/my_highlight]

Ví dụ thực tế 1: Shortcode Accordion hỏi đáp không cần JS nội dòng

Ví dụ dưới đây dùng cặp thẻ chuẩn HTML5 &lt;details&gt; và &lt;summary&gt;, vừa nhẹ vừa không phụ thuộc JavaScript nội dòng:

polycms_register_shortcode('my_accordion', function ($atts, $content = '') {
    $atts = shortcode_atts([
        'title' => 'Nhấn để mở rộng',
        'open'  => false,
    ], $atts);

    $open_attr = ($atts['open'] === true || $atts['open'] === 'true') ? ' open' : '';

    return '<details class="polycms-accordion border rounded p-3 mb-3"' . $open_attr . '>'
        . '<summary class="fw-semibold" style="cursor:pointer;">'
        . html_escape((string) $atts['title'])
        . '</summary>'
        . '<div class="accordion-body mt-2">'
        . polycms_do_shortcode($content)
        . '</div>'
        . '</details>';
});

Kết hợp lồng nhiều Shortcode

[my_accordion title="Làm sao để bật REST API trong PolyCMS?" open="true"]
  [my_highlight bg="#fef08a"]Mẹo:[/my_highlight] Mở PolyCMS Settings, chọn tab REST API và tạo khóa API mới.
[/my_accordion]

Ví dụ thực tế 2: Shortcode truy vấn bài viết mới nhất

Bạn có thể truy vấn dữ liệu trực tiếp từ các model PolyCMS thông qua polycms_ci() và tạo liên kết chuẩn bằng polycms_get_post_permalink():

polycms_register_shortcode('my_recent_posts', function ($atts) {
    $atts = shortcode_atts([
        'limit'       => 3,
        'category_id' => 0,
    ], $atts);

    $CI = &polycms_ci();
    $CI->load->model('polycms/Blog_post_model');

    $filters = [
        'status'     => 'published',
        'limit'      => max(1, min(12, (int) $atts['limit'])),
        'sort_by'    => 'published_at',
        'sort_order' => 'DESC',
    ];
    if ((int) $atts['category_id'] > 0) {
        $filters['category_id'] = (int) $atts['category_id'];
    }

    $posts = $CI->Blog_post_model->get($filters);
    if (empty($posts)) {
        return '';
    }

    $html = '<ul class="list-unstyled my-recent-posts">';
    foreach ($posts as $post) {
        $url = polycms_get_post_permalink($post);
        $html .= '<li class="mb-2"><a href="' . esc_attr($url) . '">'
            . html_escape($post->title)
            . '</a></li>';
    }
    $html .= '</ul>';

    return $html;
});

Ghi đè hoặc hủy đăng ký Shortcode

Để thay thế một shortcode mặc định hoặc tắt shortcode do plugin khác cung cấp, gọi polycms_unregister_shortcode() trước khi đăng ký phiên bản tùy biến của bạn:

polycms_add_action('polycms_init', function () {
    polycms_unregister_shortcode('polycms_tag');
    polycms_register_shortcode('polycms_tag', 'myplugin_custom_tag_handler');
});

Các nguyên tắc phát triển an toàn

  1. Luôn hợp nhất giá trị mặc định bằng shortcode_atts(): Không giả định biên tập viên luôn nhập đủ thuộc tính.
  2. Khử mã độc đầu ra triệt để: Luôn dùng html_escape(), esc_attr() hoặc polycms_safe_output(), đồng thời kiểm tra định dạng URL và mã màu trước khi đưa vào thuộc tính HTML.
  3. Hỗ trợ lồng ghép qua polycms_do_shortcode($content): Gọi hàm biên dịch lồng bên trong mọi shortcode bao đóng.
  4. Đặt tiền tố cho tên thẻ shortcode: Gắn tiền tố theo tên plugin (ví dụ acme_pricing_table) để tránh trùng lặp với các plugin khác.
  5. Đăng ký vô điều kiện khi plugin khởi tạo: Đảm bảo shortcode hoạt động nhất quán cả khi hiển thị frontend, xem trước MTBuilder lẫn qua REST API.

Hỗ trợ kỹ thuật

Bạn cần hỗ trợ xây dựng hoặc gỡ lỗi shortcode tùy biến trong PolyCMS cho RISE CRM? Hãy để lại câu hỏi tại trang danh mục sản phẩm PolyXGO trên CodeCanyon để nhận hỗ trợ hoàn toàn miễn phí.

Tài liệu liên quan