Phát triển chủ đề: Bắt đầu

Last updated on Jun 24, 2026 02:46

PolyCMS sử dụng công cụ chủ đề dựa trên Blade rất linh hoạt. Mặc dù Bảng điều khiển quản trị là Vue 3 SPA, nhưng giao diện người dùng công khai dựa trên các mẫu Blade được kết xuất phía máy chủ (SSR) truyền thống, cực nhanh theo mặc định (mặc dù nó cũng hỗ trợ đầy đủ các giao diện người dùng dựa trên API không đầu).

Hướng dẫn này trình bày kiến trúc của Chủ đề PolyCMS và cách xây dựng chủ đề đó từ đầu.

1. Cấu trúc thư mục

Tất cả các chủ đề đều nằm trong thư mục themes/.

Hãy xem cấu trúc của một chủ đề tiêu chuẩn, chẳng hạn như bản thiết kế cốt lõi flexiwhite:

themes/
└── flexiwhite/
    ├── theme.json           # The Theme Manifest
    ├── screenshot.png       # 800x600 preview image for the Admin panel
    ├── functions.php        # Optional: PHP logic, Hook registration
    ├── resources/
    │   └── views/           # Blade templates
    │       ├── layouts/
    │       │   └── app.blade.php  # The master wrapper
    │       ├── partials/
    │       └── templates/   # Specialized block templates (Landing pages, etc.)
    └── public/              # Compiled CSS/JS and Images

2. Bản kê khai chủ đề (`theme.json`)

Để đăng ký một chủ đề với hệ thống, bạn phải xác định tệp theme.json. ThemeManager sử dụng điều này để xác định chủ đề và hiển thị các mẫu có sẵn của nó cho Giao diện người dùng quản trị.

{
  "name": "FlexiWhite",
  "slug": "flexiwhite",
  "version": "1.0.0",
  "author": "Polyx Team",
  "description": "A clean, whitespace-heavy corporate theme.",
  "role": "main",
  "templates": {
    "posts": {
      "full-width": "Full Width No Sidebar",
      "gallery": "Gallery Focus Layout"
    },
    "pages": {
      "landing": "Marketing Landing Page",
      "contact": "Contact Form Layout"
    }
  }
}

Chủ đề chính và Chủ đề phụ

Lưu ý phím `"role": "main". PolyCMS triển khai Kiến trúc đa chủ đề:

Chủ đề chính (role: main): Cung cấp bố cục chung (app.blade.php) và CSS trên toàn trang web. Chỉ có một người có thể hoạt động tại một thời điểm.

Chủ đề phụ (vai trò: phụ): Cung cấp các mẫu chuyên biệt (như quy trình thanh toán duy nhất hoặc trang đích Thứ Sáu Đen). Bạn có thể kích hoạt nhiều Chủ đề phụ cùng một lúc. Mẫu của họ sẽ ghi đè Chủ đề chính khi được gán cho các bài đăng hoặc trang cụ thể.

3. Bố cục chính (`app.blade.php`)

Mỗi Chủ đề chính phải có tệp bố cục chính tại resources/views/layouts/app.blade.php. Tệp này xác định khung HTML.

Yêu cầu quan trọng: Để đảm bảo các mô-đun và plugin có thể đưa CSS và JavaScript cần thiết vào (như biểu ngữ Chấp thuận cookie hoặc tập lệnh Analytics), bố cục của bạn phải bao gồm các lệnh @stack.

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    
    <!-- Render SEO Meta Tags dynamically -->
    <title>@yield('meta_title', config('app.name'))</title>
    
    <!-- Include Theme CSS -->
    <link rel="stylesheet" href="{{ theme_asset('css/style.css') }}">
    
    <!-- CRITICAL: Allow modules to inject CSS -->
    @stack('theme-styles')
</head>
<body>
    
    @include('theme::partials.header')

    <main>
        <!-- Render the specific page/post content here -->
        @yield('content')
    </main>

    @include('theme::partials.footer')

    <!-- CRITICAL: Allow modules to inject JS -->
    @stack('theme-scripts')
</body>
</html>

4. Trình trợ giúp `theme_asset()`

Khi liên kết đến CSS, JS hoặc hình ảnh được lưu trữ trong thư mục public/ của chủ đề của bạn, luôn luôn sử dụng hàm trợ giúp theme_asset() thay vì asset() tiêu chuẩn của Laravel.

<!-- CORRECT -->
<img src="{{ theme_asset('images/logo.svg') }}" alt="Logo">

<!-- INCORRECT -->
<img src="{{ asset('themes/flexiwhite/public/images/logo.svg') }}" alt="Logo">

theme_asset() tự động phân giải đường dẫn chính xác dựa trên chủ đề hiện đang hoạt động và xử lý bộ nhớ đệm.

Các bước tiếp theo

Khi bảng kê khai và bố cục của bạn đã hoàn tất, giờ đây chủ đề của bạn có thể được kích hoạt từ Bảng điều khiển quản trị trong Giao diện > Chủ đề.

Để tìm hiểu sâu hơn, hãy khám phá cách Đăng ký khu vực tiện ích hoặc sử dụng functions.php để nhấn vào Hệ thống móc.