Published khoảng 2 giờ trước 6 min read

Joomla Bài học 30: Đóng gói (Packaging) file cài đặt Template chuẩn và kiểm thử tương thích đa thiết bị

Chúng ta đã đi qua một hành trình tuyệt vời trong Phần 3 (Bài 21 - 30) từ việc nghiên cứu Cassiopeia, tạo Child Template, xây dựng template độc lập joomlalab từ con số 0, lập trình file index.php, cấu hình Web Asset Manager (joomla.asset.json), làm chủ Template Overrides, JLayout, Template Parameters cho đến việc tinh chỉnh các trang hệ thống (error.php, offline.php, component.php).

Hôm nay, chúng ta sẽ khép lại Phần 3 với Joomla Bài học 30: Quy trình đóng gói mã nguồn thành một gói cài đặt chuẩn (.zip) có thể phân phối thương mại, cùng phương pháp kiểm thử tính tương thích đa thiết bị (Responsive Testing) và tối ưu hóa hiệu năng tổng thể cho Template trước khi đưa lên môi trường Production.

1. Cấu trúc đóng gói một Template Joomla tiêu chuẩn

Khi bạn muốn gửi template joomlalab cho khách hàng, bán trên chợ ứng dụng (JED), hoặc cài đặt tự động lên một máy chủ mới qua màn hình Extensions: Install, gói tin .zip của bạn bắt buộc phải tuân theo cấu trúc phẳng: Toàn bộ các file mã nguồn của template phải nằm ngay ở thư mục gốc của file nén, không được nằm ẩn bên trong một thư mục trung gian nào khác.

Sơ đồ cấu trúc file bên trong gói `joomlalab.zip`:

Plaintext

joomlalab.zip (Gói cài đặt chuẩn)
├── index.php
├── component.php
├── error.php
├── offline.php
├── joomla.asset.json
├── templateDetails.xml
├── html/
│   ├── com_content/
│   └── layouts/
├── language/
│   ├── en-GB/
│   └── vi-VN/
└── media/                        <-- (Lưu ý: Thư mục media đặt ngang hàng templateDetails.xml)
    └── templates/
        └── site/
            └── joomlalab/
                ├── css/
                ├── js/
                └── images/

Lỗi kinh điển của lập trình viên mới: Khi nén file .zip, nhiều bạn bấm chuột phải vào thư mục joomlalab rồi chọn Compress. Thao tác này tạo ra một thư mục cha joomlalab/ bọc bên ngoài, khiến khi cài đặt lên Joomla sẽ báo lỗi: "Error installing template. The XML file is not set up or could not be found" (Không tìm thấy file Manifest).

2. Viết Bash Script tự động đóng gói (DevOps Automation)

Là một Backend Engineer, chúng ta không bao giờ đóng gói thủ công bằng tay. Bạn có thể sử dụng đoạn mã Bash Script dưới đây để tự động hóa hoàn toàn việc dọn dẹp file tạm, biên dịch CSS (nếu có) và nén thành phẩm thành file joomlalab_v1.0.0.zip đặt sẵn trong thư mục dist/:

Tạo file scripts/package_template.sh trong dự án Docker:

Bash

#!/usr/bin/env bash
# File: scripts/package_template.sh - Tự động đóng gói Template Joomla 5
set -e

VERSION="1.0.0"
TEMPLATE_NAME="joomlalab"
BUILD_DIR="dist"
SRC_DIR="src"

echo "=== [1/3] Đang làm sạch thư mục build cũ ==="
rm -rf ${BUILD_DIR}
mkdir -p ${BUILD_DIR}

echo "=== [2/3] Đang sao lưu và đồng bộ tài nguyên từ source code ==="
# Kiểm tra sự tồn tại của thư mục media và template
if [ ! -d "${SRC_DIR}/templates/${TEMPLATE_NAME}" ]; then
    echo "Lỗi: Không tìm thấy thư mục template tại ${SRC_DIR}/templates/${TEMPLATE_NAME}"
    exit 1
fi

echo "=== [3/3] Đang tiến hành nén gói cài đặt .zip tiêu chuẩn ==="
cd "${SRC_DIR}/templates/${TEMPLATE_NAME}"

# Đóng gói toàn bộ nội dung bên trong thư mục template và media tương ứng
zip -r "../../../${BUILD_DIR}/${TEMPLATE_NAME}_v${VERSION}.zip" . \
    -x "*.DS_Store" \
    -x "*.scss" \
    -x "node_modules/*"

# Thêm thư mục media vào chung gói zip
cd "../../../${SRC_DIR}"
if [ -d "media/templates/site/${TEMPLATE_NAME}" ]; then
    zip -ur "../${BUILD_DIR}/${TEMPLATE_NAME}_v${VERSION}.zip" "media/templates/site/${TEMPLATE_NAME}" \
        -x "*.DS_Store" \
        -x "*.scss"
fi

echo "✅ Đóng gói thành công! File cài đặt nằm tại: ${BUILD_DIR}/${TEMPLATE_NAME}_v${VERSION}.zip"

Chạy lệnh trên terminal của Docker:

Bash

bash scripts/package_template.sh

3. Kiểm thử tương thích đa thiết bị (Responsive Testing)

Một template đẹp trên màn hình iMac 27-inch nhưng bị vỡ vách ngăn hoặc tràn chữ trên iPhone SE là dấu hiệu của việc thiếu kiểm thử responsive. Khi lập trình với Bootstrap 5 và CSS Grid, bạn cần tuân thủ 4 bước kiểm thử sau trước khi bàn giao:

Kiểm tra Breakpoints chuẩn của Bootstrap 5:
- xs (< 576px): Điện thoại dọc.
- sm ( $\ge$ 576px): Điện thoại ngang.
- md ( $\ge$ 768px): Máy tính bảng (Tablet).
- lg ( $\ge$ 992px): Laptop / Desktop nhỏ.
- xl ( $\ge$ 1200px) & xxl ( $\ge$ 1400px): Màn hình độ phân giải cao.
Xử lý hiện tượng tràn ngang (Horizontal Scrollbar Bug):
- Nguyên nhân phổ biến nhất là do các khối chứa ảnh hoặc bảng dữ liệu có chiều định dạng cứng (width: 1200px) mà không bọc trong class img-fluid hoặc table-responsive. Hãy luôn kiểm tra bằng cách thu nhỏ trình duyệt về kích thước 375px và lướt xem có bị tràn thanh cuộn ngang hay không.
Kiểm tra hành vi Menu Mobile (Offcanvas / Collapse):
- Đảm bảo khi bấm vào nút Hamburger Menu trên màn hình nhỏ, thanh điều hướng xổ xuống mượt mà và tự động đóng lại khi người dùng click chọn một mục menu bên trong.
Kiểm thử trên thiết bị thật:
- Sử dụng tính năng Remote Debugging (kết nối điện thoại thật qua mạng LAN cùng máy tính thông qua IP Local như [http://192.168.](http://192.168.)x.x:8080) để kiểm tra cảm giác vuốt chạm thực tế trên iOS Safari và Android Chrome.

4. Checklist tối ưu hóa hiệu năng trước khi phát hành (Production Checklist)

Trước khi đưa template joomlalab lên môi trường chạy thực tế, hãy rà soát lại danh sách kiểm tra sau đây để đảm bảo điểm số Google PageSpeed luôn đạt trên 90 điểm:

[ ] Bật chế độ System Cache & Redis (Như đã học ở Bài 16).
[ ] Kiểm tra tính năng minified: Đảm bảo các file template.min.css và template.min.js đã được biên dịch và khai báo chính xác trong joomla.asset.json.
[ ] Tối ưu hóa hình ảnh: Toàn bộ ảnh tĩnh trong thư mục images/ phải được chuyển sang định dạng WebP hoặc AVIF để giảm nhẹ dung lượng truyền tải mạng.
[ ] Khóa quyền file configuration.php: Đảm bảo phân quyền file ở mức 444 trên Linux.

5. Tổng kết Phần 3 & Định hướng Phần 4

Chúc mừng bạn đã hoàn thành trọn vẹn Phần 3: Thiết kế & Lập trình Giao diện - Template Development (Bài 21 - 30)!

Bạn đã làm chủ từ cách vận hành Cassiopeia, tạo Child Template, xây dựng template độc lập từ con số 0 với file templateDetails.xml và index.php.
Thành thạo quản lý tài nguyên qua Web Asset Manager, tùy biến giao diện qua Template Overrides và JLayout, cấu hình tham số động trong trang quản trị, cho đến việc xử lý các trang hệ thống (error.php, offline.php, component.php) và quy trình đóng gói chuẩn.

Bắt đầu từ Bài học 31, chúng ta sẽ bước sang một chương mới vô cùng mạnh mẽ của lập trình viên Backend Joomla: Phần 4: Lập trình Component chuyên sâu - MVC Architecture (Bài 31 - 40), nơi bạn sẽ tự tay xây dựng một Custom Component hoàn chỉnh từ tầng cơ sở dữ liệu (sql/install.sql), lập trình Controller, Model, View cho cả hai phía Administrator và Frontend!

joomla