vi
new
0
Avatar
Nguyen Hoang @Hieumn
26 3 97
Đã đăng vào khoảng 2 giờ trước 4 phút đọc
9

Joomla Bài học 28: Tạo các tham số cấu hình động cho Template (Template Parameters) trong trang quản trị

Ở Bài học 23, chúng ta đã phác thảo qua thẻ <config> trong file templateDetails.xml. Trong Joomla Bài học 28, chúng ta sẽ đi sâu vào kỹ thuật thiết kế, lập trình và khai thác Template Parameters (Các tham số cấu hình động) trong trang quản trị Joomla 5.

Tính năng này cho phép bạn biến một Template tĩnh thành một sản phẩm thương mại linh hoạt (giống như các theme chuyên nghiệp trên ThemeForest), nơi quản trị viên có thể thay đổi màu sắc chủ đạo, bật/tắt các hiệu ứng, chọn bố cục sidebar hay cấu hình thông số API trực tiếp từ giao diện Admin mà không cần can thiệp vào mã nguồn PHP.

1. Kiến trúc hệ thống Form Fields trong Joomla 5

Joomla sở hữu một hệ thống quản lý form dữ liệu dựa trên XML Standard Form Fields cực kỳ mạnh mẽ. Hệ thống này không chỉ dùng cho Template mà còn dùng chung cho toàn bộ Articles, Modules và Components.

  • Nơi lưu trữ giá trị cấu hình: Khi người dùng thay đổi thông số trong trang quản trị template và bấm Save, Joomla sẽ tự động serialize mảng cấu hình đó thành một chuỗi JSON và lưu vào cột params của bảng #__template_styles trong cơ sở dữ liệu.

  • Cách đọc giá trị trong PHP: Tại file index.php của template, bạn dễ dàng gọi giá trị thông qua đối tượng $this->params->get('ten_tham_so', 'gia_tri_mac_dinh').

2. Các kiểu Field Types phổ biến nhất trong Template XML

Joomla cung cấp sẵn hơn 30 kiểu trường nhập liệu (type="...") chuẩn mực. Dưới đây là các loại thường dùng nhất khi thiết lập bảng điều khiển cho Template:

Kiểu Field (type) Mô tả chi tiết & Giao diện trên Admin
text Ô nhập văn bản một dòng (Dùng cho Tiêu đề, Mã Google Analytics, Link Fanpage).
textarea Ô nhập văn bản nhiều dòng (Dùng cho mã CSS tùy chỉnh hoặc đoạn mã nhúng Custom JS).
list Hộp chọn danh sách thả xuống (<option value="...">). Dùng để chọn kiểu bố cục (ví dụ: left, right, full).
radio Nhóm nút bấm lựa chọn ngang (Dùng cho các lựa chọn Bật/Tắt).
color Bảng chọn màu trực quan (Color Picker) trả về mã HEX (ví dụ: #2563eb).
media Hộp chọn tệp tin từ Media Manager (Dùng để chọn Logo, Ảnh nền Banner).
editor Trình soạn thảo WYSIWYG tích hợp (Dùng cho các khối nội dung tĩnh trong Footer).

3. Thực hành: Xây dựng bộ tham số cấu hình nâng cao trong templateDetails.xml

Hãy mở file src/templates/joomlalab/templateDetails.xml của chúng ta và nâng cấp thẻ <config> để tổ chức các tham số thành các Fieldsets (Nhóm tab) khoa học:

XML

<config>
    <fields name="params">
        <!-- TAB 1: Cấu hình chung & Thương hiệu -->
        <fieldset name="general" label="TPL_JOOMLALAB_FIELDSET_GENERAL_LABEL">
            <field
                name="siteTitle"
                type="text"
                label="TPL_JOOMLALAB_SITETITLE_LABEL"
                description="TPL_JOOMLALAB_SITETITLE_DESC"
                default="Joomla 5 Enterprise Lab"
                filter="string"
                required="true"
            />
            <field
                name="logoFile"
                type="media"
                label="TPL_JOOMLALAB_LOGO_LABEL"
                description="TPL_JOOMLALAB_LOGO_DESC"
                default=""
            />
            <field
                name="favicon"
                type="media"
                label="TPL_JOOMLALAB_FAVICON_LABEL"
                default=""
            />
        </fieldset>

        <!-- TAB 2: Giao diện & Màu sắc -->
        <fieldset name="appearance" label="TPL_JOOMLALAB_FIELDSET_APPEARANCE_LABEL">
            <field
                name="primaryColor"
                type="color"
                label="TPL_JOOMLALAB_PRIMARY_COLOR_LABEL"
                default="#2563eb"
            />
            <field
                name="secondaryColor"
                type="color"
                label="TPL_JOOMLALAB_SECONDARY_COLOR_LABEL"
                default="#0f172a"
            />
            <field
                name="layoutMode"
                type="list"
                label="TPL_JOOMLALAB_LAYOUT_MODE_LABEL"
                default="container"
            >
                <option value="container">TPL_JOOMLALAB_LAYOUT_CONTAINER</option>
                <option value="container-fluid">TPL_JOOMLALAB_LAYOUT_FLUID</option>
            </field>
            <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>

        <!-- TAB 3: Tùy chỉnh nâng cao & SEO -->
        <fieldset name="advanced" label="TPL_JOOMLALAB_FIELDSET_ADVANCED_LABEL">
            <field
                name="enableBackToTop"
                type="radio"
                label="TPL_JOOMLALAB_BACKTOTOP_LABEL"
                layout="joomla.form.field.radio.switcher"
                default="1"
                filter="integer"
            >
                <option value="0">JNO</option>
                <option value="1">JYES</option>
            </field>
            <field
                name="googleAnalyticsId"
                type="text"
                label="TPL_JOOMLALAB_GA_ID_LABEL"
                description="TPL_JOOMLALAB_GA_ID_DESC"
                default=""
                filter="safehtml"
            />
            <field
                name="customCss"
                type="textarea"
                label="TPL_JOOMLALAB_CUSTOM_CSS_LABEL"
                rows="6"
                filter="raw"
            />
        </fieldset>
    </fields>
</config>

4. Hoàn thiện file Ngôn ngữ (*.ini) để hiển thị Tiêu đề đẹp mắt

Để các dòng nhãn (label="...") không bị hiển thị thô dạng mã TPL_JOOMLALAB_PRIMARY_COLOR_LABEL, bạn cần định nghĩa chúng trong file ngôn ngữ của Template:

Tạo file tại: src/templates/joomlalab/language/vi-VN/vi-VN.tpl_joomlalab.sys.ini và vi-VN.tpl_joomlalab.ini:

Ini, TOML

; File: vi-VN.tpl_joomlalab.sys.ini
TPL_JOOMLALAB_XML_DESCRIPTION="Giao diện độc lập chuẩn mực tối ưu cho Joomla 5 được phát triển bởi JoomlaLab."
TPL_JOOMLALAB_FIELDSET_GENERAL_LABEL="1. Chung & Thương hiệu"
TPL_JOOMLALAB_FIELDSET_APPEARANCE_LABEL="2. Giao diện & Màu sắc"
TPL_JOOMLALAB_FIELDSET_ADVANCED_LABEL="3. Nâng cao & Tùy chỉnh"

; File: vi-VN.tpl_joomlalab.ini
TPL_JOOMLALAB_SITETITLE_LABEL="Tiêu đề Website"
TPL_JOOMLALAB_SITETITLE_DESC="Nhập tên thương hiệu hiển thị trên thanh Header."
TPL_JOOMLALAB_LOGO_LABEL="Logo Website"
TPL_JOOMLALAB_LOGO_DESC="Chọn file ảnh logo từ thư mục Media."
TPL_JOOMLALAB_PRIMARY_COLOR_LABEL="Màu chủ đạo (Primary Color)"
TPL_JOOMLALAB_SECONDARY_COLOR_LABEL="Màu phụ (Secondary Color)"
TPL_JOOMLALAB_LAYOUT_MODE_LABEL="Kiểu khung hiển thị (Layout Container)"
TPL_JOOMLALAB_LAYOUT_CONTAINER="Thu gọn (Container chuẩn)"
TPL_JOOMLALAB_LAYOUT_FLUID="Tràn viền (Container Fluid)"
TPL_JOOMLALAB_STICKY_HEADER_LABEL="Cố định Header khi cuộn trang"
TPL_JOOMLALAB_BACKTOTOP_LABEL="Hiển thị nút Lên đầu trang"
TPL_JOOMLALAB_GA_ID_LABEL="Google Analytics ID"
TPL_JOOMLALAB_CUSTOM_CSS_LABEL="Mã CSS tùy chỉnh bổ sung"

5. Khai thác Template Parameters trong file index.php

Bây giờ, mọi tham số do quản trị viên cấu hình trong trang Admin đều có thể được gọi và sử dụng trực tiếp trong khung code PHP của template (index.php):

PHP

<?php
// 1. Đọc toàn bộ nhóm tham số
$params = $this->params;

// 2. Trích xuất từng biến cấu hình cụ thể
$siteTitle         = $params->get('siteTitle', 'JoomlaLab');
$logoFile          = $params->get('logoFile', '');
$primaryColor      = $params->get('primaryColor', '#2563eb');
$secondaryColor    = $params->get('secondaryColor', '#0f172a');
$layoutMode        = $params->get('layoutMode', 'container'); // 'container' hoặc 'container-fluid'
$stickyHeader      = (bool) $params->get('stickyHeader', 1);
$enableBackToTop   = (bool) $params->get('enableBackToTop', 1);
$googleAnalyticsId = $params->get('googleAnalyticsId', '');
$customCss         = $params->get('customCss', '');

// 3. Tiêm màu sắc tùy chỉnh động vào thẻ <style> thông qua Web Asset Manager
$wa = $this->getWebAssetManager();
$dynamicStyles = sprintf(
    ':root { --joomlalab-primary: %s; --joomlalab-secondary: %s; }',
    htmlspecialchars($primaryColor, ENT_QUOTES, 'UTF-8'),
    htmlspecialchars($secondaryColor, ENT_QUOTES, 'UTF-8')
);

if (!empty($customCss)) {
    $dynamicStyles .= "\n" . $customCss;
}

$wa->addInlineStyle($dynamicStyles);
?>

Và tại file index.php, bạn áp dụng biến $layoutMode vào khung bao bọc trang web:

HTML

<div class="<?php echo htmlspecialchars($layoutMode, ENT_QUOTES, 'UTF-8'); ?> my-4">
    <!-- Nội dung trang web tự động co giãn theo lựa chọn của Admin -->
</div>

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

  • Hiểu rõ cơ chế lưu trữ thông số cấu hình dưới dạng chuỗi JSON trong cột params của bảng #__template_styles.

  • Thành thạo việc thiết kế các trường nhập liệu bằng XML Standard Field Types (text, color, list, radio, media, textarea) bên trong thẻ <config> của templateDetails.xml.

  • Biết cách tổ chức giao diện Admin thành các tab khoa học qua fieldset và dịch nhãn trực quan bằng file hệ thống .sys.ini / .ini.

  • Thành thạo việc gọi hàm $this->params->get() trong PHP để điều khiển trực tiếp cấu trúc và màu sắc giao diện từ backend.

Trong Bài học 29, chúng ta sẽ tiếp tục hoàn thiện các trang hệ thống đặc thù: Tùy biến trang báo lỗi (error.php), trang bảo trì (offline.php) và giao diện in ấn (component.php).

joomla

All rights reserved

Mục lục


Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí