HeadRandom
Back to Main Site

Hướng dẫn tự tạo mã Shortcode tùy biến trong PolyCMS

Last updated on Jul 10, 2026 4:16 AM

Shortcodes là gì?

Shortcodes là các thẻ ký hiệu dạng dấu ngoặc vuông [...] sẽ tự động được hệ thống biên dịch và thay thế bằng các đoạn mã HTML động khi bài viết hiển thị ra ngoài giao diện. Shortcode cho phép các biên tập viên chèn nhanh các thành phần hiển thị phức tạp (như slide ảnh, khố accordion, các khối nút kêu gọi hành động) vào bài viết mà hoàn toàn không cần phải biết viết mã HTML.

Đăng ký một Shortcode tùy biến

Bạn có thể đăng ký các mã shortcode mới trong tệp tin chính của plugin hoặc trong file functions.php của theme đang hoạt động:

polycms_add_shortcode('my_cta', function($atts, $content = '') {
    $defaults = [
        'text'  => 'Learn More',
        'url'   => '#',
        'color' => 'primary',
    ];
    $atts = shortcode_atts($defaults, $atts);

    return '<div class="cta-block cta-' . esc_attr($atts['color']) . '">'
         . '<a href="' . esc_url($atts['url']) . '">' . esc_html($atts['text']) . '</a>'
         . '</div>';
});

Sử dụng trong bài viết

[my_cta text="Get Started" url="/pricing" color="green"]

Các thuộc tính trong Shortcode (Attributes)

Các thuộc tính được truyền dưới dạng các cặp khóa-giá trị ngay bên trong thẻ shortcode:

[shortcode_name key1="value1" key2="value2"]

Hãy luôn sử dụng hàm shortcode_atts() để gộp các tham số do người dùng truyền vào với các giá trị mặc định đã định nghĩa sẵn. Cơ chế này đảm bảo nếu biên tập viên bỏ sót thuộc tính thì shortcode vẫn hoạt động an toàn với giá trị mặc định.

Shortcode dạng bao đóng (Enclosing Shortcodes)

Shortcode có thể bao bọc lấy một phần nội dung văn bản nằm giữa thẻ mở và thẻ đóng:

polycms_add_shortcode('highlight', function($atts, $content = '') {
    $defaults = ['color' => 'yellow'];
    $atts = shortcode_atts($defaults, $atts);

    return '<span class="highlight" style="background:' . esc_attr($atts['color']) . ';">'
         . do_shortcode($content) // Xử lý các shortcode lồng bên trong
         . '</span>';
});

Cách sử dụng

[highlight color="yellow"]Đoạn văn bản này sẽ được tô nền màu vàng.[/highlight]

Ví dụ mẫu: Tạo shortcode khối Accordion

polycms_add_shortcode('accordion', function($atts, $content = '') {
    $defaults = [
        'title' => 'Click to expand',
        'open'  => 'false',
    ];
    $atts = shortcode_atts($defaults, $atts);

    $id = 'accordion-' . uniqid();
    $openClass = $atts['open'] === 'true' ? 'open' : '';

    return '<div class="polycms-accordion ' . $openClass . '" id="' . $id . '">'
         . '<div class="accordion-header" onclick="this.parentElement.classList.toggle(\'open\')">'
         . esc_html($atts['title'])
         . '</div>'
         . '<div class="accordion-body">' . do_shortcode($content) . '</div>'
         . '</div>';
});

Xử lý shortcode lồng nhau (Nested Shortcodes)

Bạn cần gọi hàm do_shortcode($content) bên trong hàm xử lý shortcode của mình để đảm bảo bất kỳ mã shortcode nào nằm lồng bên trong khối nội dung cũng đều được biên dịch chính xác. Kỹ thuật này giúp bạn tạo ra các cấu trúc nội dung phân tầng linh hoạt:

[accordion title="FAQ Item 1"]
  [highlight color="green"]Lưu ý:[/highlight] Đây là câu trả lời chi tiết.
[/accordion]

Các nguyên tắc phát triển tốt nhất (Best Practices)

  • Luôn khai thác hàm shortcode_atts() để xác định giá trị mặc định và chuẩn hóa dữ liệu đầu vào.
  • Thực hiện lọc dữ liệu đầu ra bằng các hàm esc_attr(), esc_html(), và esc_url() để phòng chống lỗi bảo mật XSS.
  • Sử dụng hàm do_shortcode($content) cho các shortcode dạng bao đóng để hỗ trợ biên dịch lồng ghép.
  • Đặt tiền tố (prefix) trước tên gọi shortcode để tránh xảy ra xung đột tên trùng lặp với các plugin khác (ví dụ: myplugin_gallery).
  • Tiến hành đăng ký shortcode trong quá trình plugin khởi tạo, tránh đăng ký trong các khối kiểm tra điều kiện rẽ nhánh.

Liên hệ hỗ trợ

Bạn gặp khó khăn hay cần tư vấn khi xây dựng các shortcode tùy biến? Hãy để lại bình luận trên trang CodeCanyon của PolyXGO. Chúng tôi cung cấp dịch vụ hỗ trợ hoàn toàn miễn phí cho tất cả khách hàng sử dụng PolyCMS — bao gồm cả việc cung cấp code mẫu và gỡ lỗi (debugging) mã nguồn.

Tài liệu hướng dẫn liên quan