Back to Main Site

Hướng dẫn xây dựng Theme tùy biến cho PolyCMS trên RISE CRM

Last updated on Nov 22, 2026 11:38 AM 11:38 AM 2,030.49 ms

Theme của PolyCMS đặt trong thư mục plugins/polycms/themes/{slug}/ và kiểm soát toàn bộ giao diện website cũng như blog công khai trên RISE CRM theo cơ chế phân cấp template lấy cảm hứng từ WordPress, hỗ trợ child theme, khai báo Theme Options trực quan và tương thích hoàn hảo với trình dựng trang MTBuilder. Hướng dẫn này cung cấp đầy đủ khung mã nguồn để bạn tạo, xem trước và kích hoạt giao diện tại Appearance > Themes cùng cấu hình không cần mã tại Appearance > Theme Options.

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

Mọi giao diện tùy biến đều đặt trong plugins/polycms/themes/. Để vượt qua bước kiểm tra hợp lệ, theme chỉ bắt buộc có style.css và index.php, còn các tệp mẫu chuyên biệt cho phép bạn tùy biến chi tiết từng loại trang:

plugins/polycms/themes/
\-- my-theme/
    |-- style.css            # Tiêu đề khai báo theme (bắt buộc)
    |-- index.php            # Mẫu dự phòng cuối cùng (bắt buộc)
    |-- header.php           # Phần đầu trang dùng chung
    |-- footer.php           # Phần chân trang dùng chung
    |-- single.php           # Mẫu bài viết chi tiết
    |-- page.php             # Mẫu trang tĩnh mặc định
    |-- page-landing.php     # Mẫu trang rộng toàn màn hình cho MTBuilder
    |-- category.php         # Mẫu danh sách theo chuyên mục
    |-- tag.php              # Mẫu danh sách theo thẻ tag
    |-- author.php           # Mẫu lưu trữ theo tác giả
    |-- archive.php          # Mẫu lưu trữ chung
    |-- search.php           # Mẫu kết quả tìm kiếm
    |-- 404.php              # Mẫu trang không tìm thấy
    |-- functions.php        # Hàm và hook riêng của theme (tùy chọn)
    |-- theme-options.php    # Khai báo cấu hình Theme Options (tùy chọn)
    |-- screenshot.png       # Ảnh xem trước trong quản trị (tùy chọn)
    |-- partials/            # Các tệp giao diện con tái sử dụng
    |-- assets/
    |   |-- css/theme.css
    |   |-- js/theme.js
    |   \-- images/
    \-- languages/
        \-- english/
            \-- mytheme_lang.php

Phân cấp Template và hỗ trợ Child Theme

Khi kết xuất một đường dẫn công khai, thư viện Libraries/Blog_theme_loader.php tìm kiếm tệp giao diện theo thứ tự ưu tiên từ cụ thể đến tổng quát: theme hiện tại (child theme) -> theme cha (nếu có khai báo Template: trong style.css) -> mẫu mặc định của plugin (plugins/polycms/Views/frontend/).

Bài viết chi tiết: single-{post_slug}.php -> single.php -> archive.php -> index.php
Trang tĩnh:        {page_template}.php -> page.php -> index.php
Chuyên mục:        category-{category_slug}.php -> category.php -> archive.php -> index.php
Thẻ tag:           tag-{tag_slug}.php -> tag.php -> archive.php -> index.php
Tác giả:           author.php -> archive.php -> index.php
Tìm kiếm:          search.php -> archive.php -> index.php
Trang chủ:         home.php -> index.php
Trang 404:         404.php -> Views/frontend/404.php

Tạo Child Theme kế thừa từ head-random

Để tùy biến giao diện mặc định head-random an toàn khi cập nhật PolyCMS, bạn chỉ cần thêm dòng Template: head-random vào đầu tệp style.css của child theme. PolyCMS sẽ nạp functions.php của theme cha trước rồi nạp functions.php của theme con, đồng thời tự động lấy các tệp template hoặc partial còn thiếu từ theme cha.

Đảm bảo tương thích với MTBuilder ngay từ đầu

Để các bố cục dựng sẵn, Template Parts và khối tùy biến của MTBuilder hiển thị sắc nét tràn viền mà không xung đột CSS, hãy tuân thủ 4 nguyên tắc sau:

  1. Cung cấp mẫu trang rộng toàn màn hình (page-landing.php): Không bó buộc vào khung container hẹp hoặc sidebar cố định.
  2. Luôn lọc nội dung qua polycms_apply_filters('polycms_post_content', $content, $page): Giúp MTBuilder biên dịch các shortcode động và lưới cột responsive chính xác.
  3. Gọi đủ hook đầu và chân trang: Đặt polycms_do_action('polycms_head'), polycms_do_action('polycms_footer') và polycms_do_action('polycms_footer_scripts') để MTBuilder và các plugin đang bật nạp mtbuilder-frontend.css cùng tài nguyên cần thiết.
  4. Hạn chế ghi đè CSS toàn cục quá mạnh: Tránh định nghĩa quy tắc rộng ảnh hưởng toàn bộ thẻ a, button, h1-h6, .row và .col-* gây lệch kiểu dáng của từng khối block.

Ví dụ mẫu trang rộng toàn màn hình cho MTBuilder (page-landing.php)

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main landing-main">
    <?php
    if (isset($page) && is_object($page)) {
        echo polycms_apply_filters('polycms_post_content', $page->content, $page);
    }
    ?>
</main>

<?php include __DIR__ . '/footer.php'; ?>

Bước 1: Tạo tệp style.css (Khai báo Theme)

PolyCMS đọc khối chú thích CSS ở đầu style.css để hiển thị thông tin giao diện tại Appearance > Themes.

/*
Theme Name: My Custom Theme
Theme URI: https://your-website.com/my-theme
Description: Giao diện Bootstrap 5 gọn nhẹ, phản hồi tốt cho PolyCMS trên RISE CRM.
Version: 1.0.0
Author: Tên Của Bạn
Author URI: https://your-website.com
Text Domain: my-theme
Requires PolyCMS: 1.3.0
Requires PHP: 8.1
License: Commercial
*/

/* Quy tắc CSS có thể đặt trực tiếp tại đây hoặc trong assets/css/theme.css */

Bước 2: Tạo tệp header.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<!DOCTYPE html>
<html lang="<?php echo esc_attr((string) polycms_get_option('active_language', 'vi')); ?>">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <?php
    if (!empty($seo_meta_tags)) {
        echo $seo_meta_tags;
    } elseif (!empty($title)) {
        echo '<title>' . html_escape($title) . '</title>' . "\n";
    }
    if (!empty($og_tags)) {
        echo $og_tags;
    }
    if (!empty($twitter_tags)) {
        echo $twitter_tags;
    }
    ?>

    <link rel="stylesheet" href="<?php echo esc_attr(polycms_theme_url('my-theme', 'assets/css/theme.css')); ?>">

    <?php polycms_do_action('polycms_head'); ?>
</head>
<body class="<?php echo esc_attr(polycms_body_class()); ?>">
<?php
polycms_do_action('polycms_body_start');

if (function_exists('polycms_render_admin_bar')) {
    polycms_render_admin_bar();
}
?>

<header class="site-header">
    <div class="container d-flex align-items-center justify-content-between py-3">
        <a href="<?php echo esc_attr(polycms_get_blog_url()); ?>" class="site-logo fw-bold text-decoration-none">
            <?php echo html_escape((string) polycms_get_theme_option('blog_title', polycms_get_option('companyname', 'RISE CRM'))); ?>
        </a>
        <?php polycms_render_menu('main'); ?>
    </div>
</header>

Bước 3: Tạo tệp footer.php

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

<footer class="site-footer py-4 mt-5 border-top">
    <div class="container">
        <div class="footer-widgets mb-3">
            <?php polycms_render_widget_area('footer'); ?>
        </div>
        <p class="mb-0 text-muted">
            &copy; <?php echo date('Y'); ?> <?php echo html_escape((string) polycms_get_option('companyname', 'RISE CRM')); ?>. Bản quyền đã được bảo lưu.
        </p>
    </div>
</footer>

<script src="<?php echo esc_attr(polycms_theme_url('my-theme', 'assets/js/theme.js')); ?>"></script>
<?php
polycms_do_action('polycms_footer');
polycms_do_action('polycms_footer_scripts');
?>
</body>
</html>

Bước 4: Tạo tệp index.php (Mẫu danh sách bài viết dự phòng)

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main py-5">
    <div class="container">
        <h1 class="mb-4"><?php echo html_escape($title ?? 'Blog'); ?></h1>

        <?php if (!empty($posts)): ?>
            <div class="row g-4">
                <?php foreach ($posts as $post): ?>
                    <div class="col-md-6">
                        <article class="card h-100">
                            <?php if (!empty($post->feature_image)): ?>
                                <img src="<?php echo esc_attr(base_url('files/' . ltrim($post->feature_image, '/'))); ?>"
                                     alt="<?php echo esc_attr($post->title); ?>"
                                     class="card-img-top" loading="lazy">
                            <?php endif; ?>
                            <div class="card-body">
                                <h2 class="h5 card-title">
                                    <a href="<?php echo esc_attr(polycms_get_post_permalink($post)); ?>">
                                        <?php echo html_escape($post->title); ?>
                                    </a>
                                </h2>
                                <div class="text-muted small mb-2">
                                    <time datetime="<?php echo esc_attr($post->published_at ?? ''); ?>">
                                        <?php echo html_escape(polycms_format_date($post->published_at ?? '')); ?>
                                    </time>
                                </div>
                                <p class="card-text"><?php echo html_escape(polycms_get_post_excerpt($post, 150)); ?></p>
                            </div>
                        </article>
                    </div>
                <?php endforeach; ?>
            </div>

            <?php if (!empty($pagination)): ?>
                <div class="mt-4"><?php echo $pagination; ?></div>
            <?php endif; ?>
        <?php else: ?>
            <p>Không tìm thấy bài viết nào.</p>
        <?php endif; ?>
    </div>
</main>

<?php include __DIR__ . '/footer.php'; ?>

Bước 5: Tạo tệp single.php và category.php

single.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main py-5">
    <div class="container">
        <div class="row g-4">
            <div class="col-lg-8">
                <article class="single-post">
                    <header class="mb-4">
                        <h1><?php echo html_escape($post->title); ?></h1>
                        <div class="text-muted small">
                            <span><?php echo html_escape(trim(($post->firstname ?? '') . ' ' . ($post->lastname ?? ''))); ?></span>
                            | <time datetime="<?php echo esc_attr($post->published_at ?? ''); ?>">
                                <?php echo html_escape(polycms_format_date($post->published_at ?? '')); ?>
                            </time>
                        </div>
                    </header>

                    <?php if (!empty($post->feature_image)): ?>
                        <div class="mb-4">
                            <img src="<?php echo esc_attr(base_url('files/' . ltrim($post->feature_image, '/'))); ?>"
                                 alt="<?php echo esc_attr($post->title); ?>" class="img-fluid rounded">
                        </div>
                    <?php endif; ?>

                    <div class="post-content">
                        <?php echo polycms_apply_filters('polycms_post_content', $post->content, $post); ?>
                    </div>

                    <?php if (!empty($post->tags)): ?>
                        <div class="post-tags mt-4">
                            <?php foreach ($post->tags as $tag): ?>
                                <a href="<?php echo esc_attr(polycms_get_tag_url($tag)); ?>" class="badge bg-light text-dark text-decoration-none me-1">
                                    #<?php echo html_escape($tag->name); ?>
                                </a>
                            <?php endforeach; ?>
                        </div>
                    <?php endif; ?>
                </article>

                <?php
                if (isset($blog_theme_loader)) {
                    $blog_theme_loader->get_template_part('comments', null, ['post' => $post]);
                }
                ?>
            </div>

            <aside class="col-lg-4">
                <?php polycms_render_widget_area('sidebar'); ?>
            </aside>
        </div>
    </div>
</main>

<?php include __DIR__ . '/footer.php'; ?>

category.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main py-5">
    <div class="container">
        <header class="mb-4">
            <h1>Chuyên mục: <?php echo html_escape($category->name); ?></h1>
            <?php if (!empty($category->description)): ?>
                <p class="text-muted"><?php echo html_escape($category->description); ?></p>
            <?php endif; ?>
        </header>

        <?php if (!empty($posts)): ?>
            <div class="row g-4">
                <?php foreach ($posts as $post): ?>
                    <div class="col-md-6">
                        <article class="card h-100 p-3">
                            <h2 class="h5">
                                <a href="<?php echo esc_attr(polycms_get_post_permalink($post)); ?>">
                                    <?php echo html_escape($post->title); ?>
                                </a>
                            </h2>
                            <p class="mb-0"><?php echo html_escape(polycms_get_post_excerpt($post, 150)); ?></p>
                        </article>
                    </div>
                <?php endforeach; ?>
            </div>
            <?php if (!empty($pagination)) { echo '<div class="mt-4">' . $pagination . '</div>'; } ?>
        <?php else: ?>
            <p>Chưa có bài viết nào trong chuyên mục này.</p>
        <?php endif; ?>
    </div>
</main>

<?php include __DIR__ . '/footer.php'; ?>

Bước 6: Khai báo Theme Options (theme-options.php)

Để quản trị viên tùy chỉnh giao diện không cần sửa mã tại Appearance > Theme Options, hãy trả về mảng khai báo trường trong tệp theme-options.php đặt tại thư mục gốc của theme. Hệ thống hỗ trợ các kiểu trường: text, textarea, number, select, checkbox, color, image và repeater.

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

return [
    'blog_title' => [
        'type'        => 'text',
        'group'       => 'Thương hiệu',
        'label'       => 'Tiêu đề Blog',
        'description' => 'Hiển thị trên thanh tiêu đề website.',
        'default'     => 'Blog Doanh Nghiệp',
    ],
    'primary_color' => [
        'type'    => 'color',
        'group'   => 'Giao diện',
        'label'   => 'Màu chủ đạo',
        'default' => '#3b82f6',
    ],
    'posts_per_row' => [
        'type'    => 'select',
        'group'   => 'Bố cục',
        'label'   => 'Số bài viết trên mỗi hàng',
        'default' => '2',
        'options' => [
            '1' => '1 cột',
            '2' => '2 cột',
            '3' => '3 cột',
        ],
    ],
    'show_sidebar' => [
        'type'    => 'checkbox',
        'group'   => 'Bố cục',
        'label'   => 'Hiển thị thanh bên trên trang bài viết',
        'default' => '1',
    ],
];

Đọc lại các giá trị đã lưu trong bất kỳ tệp template nào bằng polycms_get_theme_option('primary_color', '#3b82f6').

Phối hợp Theme Template Parts với MTBuilder Template Parts

Phân tách vai trò rõ ràng giúp dự án dễ bảo trì lâu dài:

  1. Theme template parts (đặt trong partials/ và gọi bằng polycms_get_template_part()): Phụ trách khung cấu trúc ổn định toàn trang như thanh điều hướng chính, chân trang pháp lý và breadcrumb.
  2. MTBuilder Template Parts: Phụ trách các khối tiếp thị thay đổi thường xuyên như phần mở đầu hero, bảng giá, nhận xét khách hàng và biểu ngữ chiến dịch để biên tập viên chủ động cập nhật mà không cần triển khai lại mã nguồn.

Kích hoạt và Xem trước trên RISE CRM

  1. Đặt thư mục giao diện trong plugins/polycms/themes/my-theme/ (hoặc tải tệp ZIP qua Appearance > Themes).
  2. Truy cập Appearance > Themes trong RISE CRM.
  3. Nhấn Preview để xem trước giao diện trong phiên riêng của nhân sự mà không làm ảnh hưởng khách truy cập, sau đó bấm Activate khi đã hoàn thiện.
  4. Tinh chỉnh logo, màu sắc và bố cục tại Appearance > Theme Options.

Nguyên tắc thiết kế tốt nhất

  1. Luôn gọi polycms_do_action('polycms_head') và polycms_do_action('polycms_footer'): Các plugin đi kèm như Google Analytics, Banner Slider, MTOptimize và MTBuilder đều phụ thuộc hai điểm neo này.
  2. Khử mã độc toàn bộ dữ liệu động: Dùng html_escape() cho nội dung văn bản và esc_attr() cho thuộc tính HTML.
  3. Đi qua bộ lọc polycms_apply_filters('polycms_post_content', ...): Đảm bảo liên kết nội bộ, shortcode và bố cục MTBuilder hoạt động đầy đủ.
  4. Hiển thị polycms_render_admin_bar(): Giúp nhân viên RISE CRM có ngay nút sửa bài và xóa cache ngay khi xem trang công khai.
  5. Kiểm tra hiển thị đa màn hình: Rà soát lưới Bootstrap 5 và menu di động trên điện thoại, máy tính bảng và màn hình lớn.

Hỗ trợ kỹ thuật

Nếu bạn cần hỗ trợ thiết kế giao diện tùy biến, khai báo Theme Options hoặc tạo child theme từ head-random, hãy để lại bình luận 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