Hướng dẫn tạo Shortcode tùy biến trong PolyCMS cho RISE CRM
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:
- 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ặckey='value'). - Tự động ép kiểu: Các giá trị
true,1,yes,ontự động chuyển thànhtrue; các giá trịfalse,0,no,offchuyển thànhfalse; chuỗi số nguyên chuyển thànhint.
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 <details> và <summary>, 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
- 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. - Khử mã độc đầu ra triệt để: Luôn dùng
html_escape(),esc_attr()hoặcpolycms_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. - 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. - Đặ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. - Đă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
- Widgets và Sidebars trong PolyCMS - Tìm hiểu các shortcode mặc định và khu vực widget.
- Xây dựng Plugin tùy biến cho PolyCMS - Đóng gói shortcode tùy biến trong khung cấu trúc plugin chuẩn.
- Template Tags và Hàm bổ trợ Helper - Các hàm URL, model và bảo mật dùng trong callback shortcode.
- Tài liệu tham khảo đầy đủ về Hooks và Filters - Can thiệp vào
polycms_post_contentvàpolycms_the_content.