Joomla Bài học 21: Khám phá Template mặc định Cassiopeia, cấu trúc Bootstrap 5 và CSS Grid trong Joomla

Chào mừng bạn bước sang Phần 3: Thiết kế & Lập trình Giao diện - Template Development (Bài 21 - 30). Sau khi đã nắm vững quản trị hệ thống, phân quyền ACL, SEO và vận hành ở 20 bài học đầu tiên, từ bài học này chúng ta sẽ đi sâu vào tầng hiển thị (Presentation Layer) của Joomla 5.

Mở đầu Phần 3 là Joomla Bài học 21, nơi chúng ta giải phẫu Cassiopeia — giao diện Frontend mặc định của Joomla 5. Thay vì sử dụng các thư viện nặng nề hay cấu trúc lưới div.row > div.col-* lồng nhau phức tạp cho bố cục tổng thể, Cassiopeia kết hợp khéo léo giữa CSS Grid (cho khung bố cục trang vĩ mô) và Bootstrap 5 (cho các thành phần UI vi mô bên trong), đồng thời loại bỏ hoàn toàn sự phụ thuộc vào jQuery.

1. Kiến trúc tổng quan của Template Cassiopeia trong Joomla 5

Trên Joomla 5, mã nguồn của một Template hiện đại không còn nằm gom chung một chỗ mà được tách làm 2 khu vực vật lý rõ rệt nhằm mục đích bảo mật và tối ưu hóa bộ nhớ đệm (Static Assets Caching):

Plaintext

/var/www/html/
├── templates/
│   └── cassiopeia/                 <-- Chứa logic PHP, XML và HTML Overrides
│       ├── html/                   (Ghi đè giao diện Component/Module/Layouts)
│       ├── index.php               (File khung xương chính của trang web)
│       ├── component.php           (Giao diện tối giản dùng cho In ấn / Popup)
│       ├── error.php               (Giao diện trang báo lỗi 404/403/500)
│       ├── offline.php             (Giao diện khi bật chế độ bảo trì)
│       ├── joomla.asset.json       (Khai báo quản lý file CSS/JS cho Web Asset Manager)
│       └── templateDetails.xml     (Khai báo thông tin, Positions và Tham số cấu hình)
│
└── media/
    └── templates/
        └── site/
            └── cassiopeia/         <-- Chứa toàn bộ tài nguyên tĩnh công khai
                ├── css/            (File template.min.css, global colors, vendor...)
                ├── js/             (Các script thuần Vanilla JS)
                ├── images/         (Logo, icons, hình nền mặc định)
                └── scss/           (Mã nguồn SASS gốc để biên dịch ra CSS)

Lý do tách thư mục /media/templates/site/cassiopeia/: Như chúng ta đã học ở Bài 18 (Bảo mật), việc đưa toàn bộ file .css, .js, .webp sang thư mục /media giúp Web Server (Nginx/Apache) có thể phục vụ các file tĩnh này trực tiếp với tốc độ cao nhất, đồng thời cho phép khóa chặt quyền truy cập trực tiếp vào các file .php và .xml bên trong thư mục /templates/.

2. Hệ thống Module Positions và Bố cục CSS Grid của Cassiopeia

Khác với các giao diện cổ điển dùng Bootstrap Grid (container > row > col-md-3) để chia cột trái - giữa - phải, Cassiopeia sử dụng Native CSS Grid (display: grid) trên thẻ <body> (class .site-grid).

A. Sơ đồ 17 Vị trí (Module Positions) của Cassiopeia

Để nhìn thấy trực quan vị trí của từng khu vực ngay trên trang web của bạn mà không cần đoán mò:

1. Truy cập System $\rightarrow$ Site Templates $\rightarrow$ Bấm nút Options (góc trên bên phải).

2. Bật Preview Module Positions = Enabled $\rightarrow$ Bấm Save & Close.

3. Mở trang chủ của bạn và thêm tham số ?tp=1 vào cuối đường dẫn (Ví dụ: http://localhost:8080/?tp=1).

Bạn sẽ thấy toàn bộ cấu trúc vị trí của Cassiopeia được phân bổ từ trên xuống dưới như sau:

B. Cách CSS Grid tự động co giãn cột thông minh

Trong file scss/blocks/_css-grid.scss của Cassiopeia, thẻ .site-grid được chia thành 4 cột ảo ở chế độ màn hình lớn (Desktop):

• Nếu bạn không gán bất kỳ Module nào vào sidebar-left và sidebar-right: Khối nội dung chính (main) sẽ tự động chiếm trọn 4/4 cột (100% chiều rộng).

• Nếu bạn bật Module ở sidebar-left: Cột trái chiếm 1 phần (25%), nội dung chính tự động thu lại chiếm 3 phần (75%).

• Nếu bật cả sidebar-left và sidebar-right: Bố cục tự động chia theo tỷ lệ 1 : 2 : 1 (25% - 50% - 25%) mà không cần sửa một dòng code PHP hay tính toán lại class col-md-* nào!

3. Cấu hình Tham số (Template Style Options) trong Administrator

Bạn có thể tùy chỉnh nhanh phong cách của Cassiopeia tại System $\rightarrow$ Site Template Styles $\rightarrow$ Chọn cassiopeia - Default $\rightarrow$ Tab Advanced:

1. Brand (Thương hiệu): Tải lên Logo SVG/WebP, đặt tiêu đề trang (Site Title) và dòng mô tả phụ (Tagline).

2. Fonts Scheme (Bộ phông chữ): Chọn phông chữ có sẵn trên máy (System Fonts - tải siêu nhanh), phông chữ Google Fonts nạp từ CDN hoặc nạp trực tiếp từ thư mục cục bộ (Local Fonts - tuân thủ GDPR).

3. Colour Theme: Chuyển đổi giữa tông màu chuẩn (Standard - Xanh đậm) và tông màu thay thế (Alternative - Đỏ Bordeaux).

4. Layout:

   • Static (Cố định): Khung nội dung căn giữa màn hình với độ rộng giới hạn chuẩn (max-width: 1320px).

   • Fluid (Tràn viền): Toàn bộ nội dung giãn rộng 100% theo kích thước màn hình người dùng.

5. Sticky Header: Bật Yes để giữ thanh Menu luôn bám dính ở đỉnh màn hình khi người dùng cuộn chuột xuống.

4. Tích hợp và Sử dụng Bootstrap 5.3+ trong Joomla 5

Mặc dù bố cục khung lớn (Macro-layout) dùng CSS Grid, nhưng toàn bộ các thành phần bên trong Component và Module (Micro-layout) của Joomla 5 đều được xây dựng trên nền tảng Bootstrap 5.3+ (thuần Vanilla JavaScript, không còn jQuery).

A. Tùy biến số cột hiển thị bằng Bootstrap Class trong Module

Khi bạn đặt nhiều Module vào cùng vị trí top-a hoặc bottom-a, mặc định Cassiopeia xếp chúng nằm ngang bằng nhau (flex: 1). Nếu muốn chia tỷ lệ lệch (ví dụ: Module thứ nhất chiếm 8 phần, Module thứ hai chiếm 4 phần trên thang 12 của Bootstrap):

1. Mở cấu hình Module thứ nhất $\rightarrow$ Tab Advanced.

2. Tại ô Header Class / Module Class, điền thêm class Bootstrap 5: col-lg-8.

3. Mở Module thứ hai $\rightarrow$ Tại ô Module Class, điền: col-lg-4.

B. Cách gọi các Interactive Components của Bootstrap 5 bằng PHP (HTMLHelper)

Để tối ưu hóa hiệu năng, Joomla 5 không nạp toàn bộ file bootstrap.bundle.min.js nặng nề vào mọi trang web. Thay vào đó, trang nào cần dùng tính năng động nào của Bootstrap 5 (như Modal, Collapse, Offcanvas, Tab, Tooltip, Popover, Carousel), bạn mới gọi nạp đúng module JS đó thông qua HTMLHelper:

PHP

use Joomla\CMS\HTML\HTMLHelper;

// 1. Nạp thư viện JS của Bootstrap 5 Modal (Cửa sổ bật lên)
HTMLHelper::_('bootstrap.modal', '.my-custom-modal', [
    'backdrop' => 'static',
    'keyboard' => false
]);

// 2. Nạp thư viện JS cho Bootstrap 5 Tooltip (Chú thích khi di chuột)
HTMLHelper::_('bootstrap.tooltip', '.hasTooltip', [
    'placement' => 'top'
]);

// 3. Nạp thư viện JS cho Bootstrap 5 Dropdown hoặc Collapse (Accordion)
HTMLHelper::_('bootstrap.dropdown', '.dropdown-toggle');
HTMLHelper::_('bootstrap.collapse', '.collapse-box');

Sau khi đã gọi HTMLHelper::_('bootstrap.modal') ở đầu file layout PHP, bạn có thể viết mã HTML chuẩn Bootstrap 5 ngay bên dưới và nó sẽ hoạt động mượt mà:

HTML

<!-- Nút bấm mở Modal chuẩn Bootstrap 5 (chú ý thuộc tính data-bs-*) -->
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#infoModal">
    Xem thông số kỹ thuật
</button>

<!-- Khung Modal -->
<div class="modal fade my-custom-modal" id="infoModal" tabindex="-1" aria-hidden="true">
    <div class="modal-dialog modal-dialog-centered">
        <div class="modal-content">
            <div class="modal-header">
                <h5 class="modal-title">Chi tiết hệ thống</h5>
                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
            </div>
            <div class="modal-body">
                <p>Nội dung được hiển thị bằng Bootstrap 5.3 tích hợp sẵn trong Joomla 5.</p>
            </div>
        </div>
    </div>
</div>

5. Cách thêm CSS và JS riêng (user.css & user.js) trong Cassiopeia

Khi bạn muốn viết thêm CSS hoặc JavaScript để sửa giao diện Cassiopeia, tuyệt đối không sửa trực tiếp vào file template.min.css vì mọi thay đổi của bạn sẽ bị xóa sạch ngay khi nâng cấp Joomla (như đã học ở Bài 20).

Cassiopeia đã lập trình sẵn cơ chế tự động kiểm tra và nạp 2 file tùy chỉnh của người dùng nếu chúng tồn tại:

• Đường dẫn tạo file CSS riêng: /media/templates/site/cassiopeia/css/user.css

• Đường dẫn tạo file JS riêng: /media/templates/site/cassiopeia/js/user.js

Bạn có thể tạo 2 file này trực tiếp trong IDE (VS Code) hoặc tạo ngay trên giao diện quản trị tại: System $\rightarrow$ Site Templates $\rightarrow$ Cassiopeia Details and Files $\rightarrow$ Bấm nút New File $\rightarrow$ Chọn thư mục css (nằm dưới nhánh media) và đặt tên là user.css. File này sẽ luôn được nạp sau cùng trong thẻ <head>, giúp bạn dễ dàng ghi đè mọi biến CSS (--cassiopeia-color-primary) và kiểu dáng mặc định:

CSS

/* File: media/templates/site/cassiopeia/css/user.css */
:root {
    --cassiopeia-color-primary: #0f172a;
    --cassiopeia-color-hover: #2563eb;
    --cassiopeia-font-family-body: 'Inter', sans-serif;
}

.container-header {
    background-image: none;
    background-color: var(--cassiopeia-color-primary);
}

6. Tổng kết bài học

• Hiểu rõ cấu trúc phân tách 2 thư mục của một Template Joomla 5 hiện đại: /templates/cassiopeia (chứa logic PHP/XML) và /media/templates/site/cassiopeia (chứa tài nguyên tĩnh CSS/JS/Images).

• Làm chủ 17 vị trí Module của Cassiopeia qua tham số ?tp=1 và hiểu cách kết hợp giữa CSS Grid (bố cục khung trang) với Bootstrap 5.3 (các thành phần bên trong).

• Biết cách kích hoạt từng module JavaScript của Bootstrap 5 theo nhu cầu bằng HTMLHelper::_('bootstrap.*') và cách tùy biến CSS/JS an toàn qua file user.css / user.js.

Tuy nhiên, nếu bạn cần sửa đổi cả cấu trúc HTML trong file index.php của Cassiopeia mà vẫn không muốn bị mất code khi cập nhật Joomla thì phải làm sao? Trong Bài học 22, chúng ta sẽ giải quyết bài toán này với: Kỹ thuật tạo Child Template để tùy biến giao diện mà không bị mất code khi cập nhật.