Joomla Bài học 23: Cấu trúc thư mục chuẩn của một Joomla Template từ con số 0 và chi tiết file templateDetails.xml

Ở hai bài học trước, chúng ta đã tìm hiểu cách tùy biến và tạo Child Template dựa trên giao diện mặc định Cassiopeia. Tuy nhiên, khi nhận một dự án doanh nghiệp với bản thiết kế Figma độc quyền (hoặc sử dụng các framework CSS khác như Tailwind CSS, UIkit thay vì Bootstrap 5), việc xây dựng một Standalone Template (Giao diện độc lập) từ con số 0 sẽ giúp mã nguồn sạch tuyệt đối, không bị dư thừa CSS/JS và mang thương hiệu riêng của bạn.

Trong Joomla Bài học 23, chúng ta sẽ tự tay khởi tạo cấu trúc thư mục chuẩn mực của một Template Joomla 5 độc lập (đặt tên là joomlalab), phân tích từng thẻ cấu hình bên trong tệp tin xương sống templateDetails.xml và sử dụng cơ chế Discover Install để cài đặt giao diện ngay trong quá trình code.

1. Cấu trúc thư mục chuẩn của một Template Joomla 5 từ con số 0

Một Template hiện đại trên Joomla 5 tuân thủ kiến trúc tách biệt giữa Logic hiển thị (/templates/<tên_template>) và Tài nguyên tĩnh công khai (/media/templates/site/<tên_template>).

Hãy tạo cây thư mục cho giao diện mới tên là joomlalab bên trong thư mục mã nguồn src/ của dự án Docker như sau:

Plaintext

src/
├── templates/
│   └── joomlalab/                      <-- [1] Thư mục chứa Logic PHP, XML & Overrides
│       ├── html/                       (Chứa các bản ghi đè giao diện Component/Module)
│       │   └── layouts/                (Chứa các JLayout tùy chỉnh)
│       ├── language/                   (Chứa file ngôn ngữ đa quốc gia của Template)
│       │   ├── en-GB/
│       │   │   ├── en-GB.tpl_joomlalab.ini
│       │   │   └── en-GB.tpl_joomlalab.sys.ini
│       │   └── vi-VN/
│       │       ├── vi-VN.tpl_joomlalab.ini
│       │       └── vi-VN.tpl_joomlalab.sys.ini
│       ├── index.php                   (Bắt buộc: Khung HTML chính của toàn trang)
│       ├── component.php               (Giao diện rút gọn khi gọi ?tmpl=component / In ấn)
│       ├── error.php                   (Giao diện bắt lỗi HTTP 403, 404, 500)
│       ├── offline.php                 (Giao diện khi bật chế độ Bảo trì)
│       ├── joomla.asset.json           (Bắt buộc: Khai báo CSS/JS cho Web Asset Manager)
│       └── templateDetails.xml         (Bắt buộc: File Manifest định danh Template)
│
└── media/
    └── templates/
        └── site/
            └── joomlalab/              <-- [2] Thư mục chứa Static Assets (Browser tải trực tiếp)
                ├── css/
                │   ├── template.css    (File CSS chính của giao diện)
                │   └── user.css        (File CSS dự phòng cho người dùng tự ghi đè)
                ├── js/
                │   └── template.js     (File JS xử lý hiệu ứng giao diện)
                └── images/
                    ├── logo.svg
                    ├── template_preview.png   (Ảnh phóng to 800x600 xem trước trong Admin)
                    └── template_thumbnail.png (Ảnh thu nhỏ 200x150 trong danh sách Admin)

2. Vai trò của từng File cốt lõi trong Template

Trước khi viết code chi tiết cho từng file ở các bài sau, bạn cần nắm rõ nhiệm vụ của các thành phần trong cây thư mục trên:

3. Giải phẫu chi tiết file templateDetails.xml chuẩn Joomla 5

Hãy tạo file src/templates/joomlalab/templateDetails.xml với nội dung hoàn chỉnh dưới đây. Mọi chuẩn mực mới nhất của Joomla 5 (như thẻ <inheritable> và <media>) đều được áp dụng:

XML

<?xml version="1.0" encoding="utf-8"?>
<extension type="template" client="site" method="upgrade">
    <!-- 1. THÔNG TIN ĐỊNH DANH (METADATA) -->
    <name>joomlalab</name>
    <version>1.0.0</version>
    <creationDate>2026-11</creationDate>
    <author>Hieu Nguyen</author>
    <authorEmail>hhoang02052004@gmail.com</authorEmail>
    <copyright>Copyright (C) 2026 Hieu Nguyen. All rights reserved.</copyright>
    <license>GNU General Public License version 2 or later</license>
    <description>TPL_JOOMLALAB_XML_DESCRIPTION</description>

    <!-- 2. CHO PHÉP TẠO CHILD TEMPLATE TỪ GIAO DIỆN NÀY (CHUẨN JOOMLA 5) -->
    <inheritable>1</inheritable>

    <!-- 3. KHAI BÁO CÁC FILE VÀ THƯ MỤC LOGIC TRONG /templates/joomlalab/ -->
    <files>
        <filename>index.php</filename>
        <filename>component.php</filename>
        <filename>error.php</filename>
        <filename>offline.php</filename>
        <filename>joomla.asset.json</filename>
        <filename>templateDetails.xml</filename>
        <folder>html</folder>
    </files>

    <!-- 4. KHAI BÁO THƯ MỤC TÀI NGUYÊN TĨNH TRONG /media/templates/site/joomlalab/ -->
    <media destination="templates/site/joomlalab" folder="media">
        <folder>css</folder>
        <folder>js</folder>
        <folder>images</folder>
    </media>

    <!-- 5. KHAI BÁO GÓI NGÔN NGỮ ĐI KÈM -->
    <languages folder="language">
        <language tag="en-GB">en-GB/en-GB.tpl_joomlalab.ini</language>
        <language tag="en-GB">en-GB/en-GB.tpl_joomlalab.sys.ini</language>
        <language tag="vi-VN">vi-VN/vi-VN.tpl_joomlalab.ini</language>
        <language tag="vi-VN">vi-VN/vi-VN.tpl_joomlalab.sys.ini</language>
    </languages>

    <!-- 6. ĐỊNH NGHĨA CÁC VỊ TRÍ MODULE (MODULE POSITIONS) -->
    <positions>
        <position>topbar</position>
        <position>header</position>
        <position>menu</position>
        <position>search</position>
        <position>hero-banner</position>
        <position>breadcrumbs</position>
        <position>sidebar-left</position>
        <position>main-top</position>
        <position>main-bottom</position>
        <position>sidebar-right</position>
        <position>footer</position>
        <position>debug</position>
    </positions>

    <!-- 7. CẤU HÌNH THAM SỐ ĐỘNG TRONG ADMIN (TEMPLATE PARAMETERS) -->
    <config>
        <fields name="params">
            <fieldset name="advanced">
                <field
                    name="logoFile"
                    type="media"
                    label="TPL_JOOMLALAB_LOGO_LABEL"
                    description="TPL_JOOMLALAB_LOGO_DESC"
                    default=""
                />
                <field
                    name="siteTitle"
                    type="text"
                    label="TPL_JOOMLALAB_SITETITLE_LABEL"
                    default="Joomla 5 Enterprise"
                    filter="string"
                />
                <field
                    name="primaryColor"
                    type="color"
                    label="TPL_JOOMLALAB_PRIMARY_COLOR_LABEL"
                    default="#2563eb"
                />
                <field
                    name="stickyHeader"
                    type="radio"
                    label="TPL_JOOMLALAB_STICKY_HEADER_LABEL"
                    layout="joomla.form.field.radio.switcher"
                    default="1"
                    filter="integer"
                >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

Phân tích các thuộc tính quan trọng trong templateDetails.xml:

• <extension type="template" client="site" method="upgrade">:

  • client="site": Khai báo đây là giao diện cho người dùng cuối (Frontend). Nếu làm giao diện cho trang quản trị thì đổi thành client="administrator".

  • method="upgrade": Cho phép cài đè bản cập nhật mới lên bản cũ mà không cần gỡ cài đặt trước.

• <name>joomlalab</name>: Tên định danh hệ thống (viết thường, không dấu, không khoảng trắng). Tên này bắt buộc phải trùng khớp 100% với tên thư mục /templates/joomlalab/ và /media/templates/site/joomlalab/.

• <inheritable>1</inheritable>: Kích hoạt khả năng làm Parent Template. Nhờ dòng này, sau khi hoàn thiện joomlalab, bạn có thể bấm nút Create Child Template từ giao diện của chính bạn giống hệt như Cassiopeia!

4. Tạo file index.php tối thiểu và Cài đặt bằng Discover

Khi bạn tự tạo thư mục templates/joomlalab trực tiếp trong mã nguồn (thay vì nén .zip rồi upload), cơ sở dữ liệu của Joomla (bảng #__extensions và #__template_styles) vẫn chưa biết đến sự tồn tại của template này.

Joomla cung cấp tính năng Discover (Khám phá phần mở rộng) cực kỳ tiện lợi cho lập trình viên:

Bước 1: Tạo file index.php và joomla.asset.json khung tối thiểu

1. Tạo file src/templates/joomlalab/joomla.asset.json với cấu trúc JSON hợp lệ:

   JSON

   {
     "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
     "name": "joomlalab",
     "version": "1.0.0",
     "description": "JoomlaLab Custom Template Assets",
     "license": "GPL-2.0-or-later",
     "assets": []
   }
   
   

2. Tạo file src/templates/joomlalab/index.php tạm thời để kiểm tra:

   PHP

   <?php
   \defined('_JEXEC') or die;
   ?>
   <!DOCTYPE html>
   <html lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>">
   <head>
       <jdoc:include type="metas" />
       <jdoc:include type="styles" />
       <jdoc:include type="scripts" />
   </head>
   <body>
       <header><h1>Giao diện JoomlaLab từ con số 0!</h1></header>
       <main>
           <jdoc:include type="message" />
           <jdoc:include type="component" />
       </main>
   </body>
   </html>
   
   

Bước 2: Chạy lệnh Discover trong Administrator (hoặc qua CLI)

• Cách 1 (Trên giao diện Admin):

  1. Truy cập System $\rightarrow$ Install $\rightarrow$ Discover.

  2. Bấm nút Discover ở góc trên bên trái. Joomla sẽ quét toàn bộ thư mục /templates, phát hiện ra joomlalab chưa có trong Database và liệt kê lên màn hình.

  3. Tích chọn joomlalab và bấm nút Install.

• Cách 2 (Qua Joomla CLI trong Docker):

  Bash

  # Quét và liệt kê các extension mới tạo trong mã nguồn
  docker exec -it joomla_php php cli/joomla.php extension:discover:list
  
  # Cài đặt toàn bộ các extension vừa được Discover phát hiện
  docker exec -it joomla_php php cli/joomla.php extension:discover:install
  
  

Sau khi chạy xong, bạn vào System $\rightarrow$ Site Template Styles, bạn sẽ thấy dòng joomlalab - Default xuất hiện. Chỉ cần bấm vào biểu tượng Ngôi sao vàng trên dòng này và tải lại trang chủ http://localhost:8080, giao diện mới tinh của bạn đã chính thức hoạt động!

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

• Nắm vững cấu trúc phân tách 2 nhánh thư mục chuẩn của một Template Joomla 5 độc lập (/templates/joomlalab và /media/templates/site/joomlalab).

• Hiểu rõ chức năng của từng file cốt lõi (index.php, component.php, error.php, offline.php, joomla.asset.json) và sự khác biệt giữa file ngôn ngữ .ini với .sys.ini.

• Viết thành thạo file templateDetails.xml với đầy đủ khai báo <inheritable>1</inheritable>, <positions>, <config> và cài đặt nhanh vào hệ thống bằng công cụ Discover.

Trong Bài học 24, chúng ta sẽ đi sâu vào lập trình tệp tin quan trọng nhất của giao diện: Xây dựng file index.php, sử dụng các thẻ <jdoc:include> và khai báo Module Positions.