Joomla Bài học 39: Tích hợp hệ thống Tags (Thẻ) và Custom Fields (Trường mở rộng) vào Custom Component

Khi xây dựng một Custom Component chuyên nghiệp, người quản trị thường yêu cầu hai tính năng quen thuộc có sẵn trên các bài viết cốt lõi (com_content): Tags (Hệ thống thẻ phân loại) và Custom Fields (Các trường dữ liệu mở rộng động). Thay vì phải tự lập trình bảng quản lý tags và các trường nhập liệu từ đầu, Joomla 5 cung cấp sẵn các thư viện lõi tích hợp sẵn (ContentHelper và FieldsHelper) giúp bạn gắn chúng vào Custom Component của mình chỉ với vài bước cấu hình gọn gàng.

Trong Joomla Bài học 39, chúng ta sẽ học cách tích hợp hệ thống Tags và Custom Fields vào bảng dữ liệu #__custom_items của component com_custom.

1. Tích hợp hệ thống Tags (Thẻ phân loại) vào Component

Để một bảng dữ liệu trong component hỗ trợ tính năng Tags (cho phép người dùng gán nhiều thẻ, click vào thẻ để lọc danh sách liên quan), chúng ta cần thực hiện 3 bước: đăng ký bảng trong hệ thống Tags, hiển thị ô chọn Tags trong Form quản trị và render danh sách Tags ngoài giao diện Frontend.

Bước 1: Khai báo hỗ trợ Tags trong file content.xml (hoặc định nghĩa trong bảng cấu hình mở rộng)

Joomla quản lý các bảng hỗ trợ Tags thông qua bảng #__content_types. Khi component của bạn được cài đặt, bạn có thể tự động đăng ký hoặc cấu hình sẵn trong model.

Bước 2: Thêm trường chọn Tags vào Form XML (forms/item.xml)

Mở file src/administrator/components/com_custom/forms/item.xml (đã tạo ở Bài 34) và bổ sung trường chọn thẻ tags:

XML

<field
    name="tags"
    type="tag"
    label="JTAG"
    description="JTAG_DESC"
    class="form-select"
    multiple="true"
/>

Bước 3: Lưu trữ liên kết Tags trong Model (Model/ItemModel.php)

Lớp AdminModel của Joomla hỗ trợ sẵn phương thức xử lý bảng trung gian #__contentitem_tag_map. Bạn chỉ cần gọi hàm xử lý tags sau khi lưu thành công bản ghi trong phương thức save() của ItemModel:

PHP

protected function save($data)
{
    // 1. Lưu bản ghi chính vào #__custom_items
    $result = parent::save($data);

    if ($result) {
        $pk = $this->getState($this->getName() . '.id');
        
        // 2. Tự động đồng bộ hóa các Tags được chọn vào bảng map của Joomla Core
        if (isset($data['tags']) && \Joomla\CMS\Plugin\PluginHelper::isEnabled('system', 'tag')) {
            $table = $this->getTable();
            $table->load($pk);
            // Gọi hàm lưu trữ tags của hệ thống
            $table->newTags = $data['tags'];
            // Hoặc sử dụng Helper tương ứng của com_tags
            \Joomla\Component\Tags\Administrator\Helper\TagsHelper::tagItem($pk, 'com_custom.item', $data['tags']);
        }
    }

    return $result;
}

Bước 4: Hiển thị Tags ngoài giao diện Frontend (site/tmpl/item/default.php)

Tại giao diện chi tiết bài viết, bạn có thể gọi Layout hiển thị Tags có sẵn của Joomla Core bằng LayoutHelper:

PHP

use Joomla\CMS\Layout\LayoutHelper;

// Hiển thị danh sách các thẻ Tags đã gán cho bản ghi hiện tại
echo LayoutHelper::render('joomla.content.tags', $this->item->tags);

2. Tích hợp Custom Fields (Trường mở rộng động) vào Component

Hệ thống Custom Fields của Joomla (quản lý tại Content $\rightarrow$ Field Groups / Fields) cho phép quản trị viên tự thêm các trường tùy chỉnh (như số điện thoại, giá tiền, địa điểm, file đính kèm) mà không cần lập trình viên sửa code XML.

Bước 1: Đăng ký Context cho Component trong CSDL

Để Joomla biết component của bạn (com_custom) được phép sử dụng hệ thống Fields, context được quy định theo định dạng: com_custom.item. Quản trị viên khi vào trang quản lý Fields sẽ thấy tùy chọn xuất hiện component của bạn trong bộ lọc Category/Context.

Bước 2: Nạp và hiển thị Custom Fields trong Front-end Model (site/src/Model/ItemModel.php)

Joomla cung cấp thư viện FieldsHelper để tự động lấy toàn bộ giá trị các trường tùy chỉnh đã gán cho bản ghi:

PHP

<?php
namespace MyCompany\Component\Custom\Site\Model;

\defined('_JEXEC') or die;

use Joomla\CMS\MVC\Model\ItemModel as BaseItemModel;
use Joomla\Component\Fields\Administrator\Helper\FieldsHelper;

class ItemModel extends BaseItemModel
{
    public function getItem($pk = null)
    {
        $item = parent::getItem($pk);

        if ($item) {
            // Tự động nạp toàn bộ Custom Fields và giá trị tương ứng của bản ghi
            $item->jcfields = FieldsHelper::getFields('com_custom.item', $item, true);
        }

        return $item;
    }
}

Bước 3: Render Custom Fields ra giao diện (site/tmpl/item/default.php)

Trong file giao diện chi tiết (default.php), bạn dễ dàng lặp qua mảng $this->item->jcfields để hiển thị:

PHP

<?php if (!empty($this->item->jcfields)) : ?>
    <div class="custom-fields-wrapper mt-4 pt-3 border-top">
        <h4 class="fw-bold mb-3">Thông tin mở rộng</h4>
        <ul class="list-unstyled">
            <?php foreach ($this->item->jcfields as $field) : ?>
                <?php if (!empty($field->value)) : ?>
                    <li class="mb-2">
                        <strong><?php echo htmlspecialchars($field->label, ENT_COMPAT, 'UTF-8'); ?>:</strong> 
                        <span><?php echo $field->value; ?></span>
                    </li>
                <?php endif; ?>
            <?php endforeach; ?>
        </ul>
    </div>
<?php endif; ?>

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

• Hiểu rõ cách tích hợp hệ thống Tags chuẩn Core vào Form quản lý và cách lưu trữ qua bảng map trung gian.

• Thành thạo việc sử dụng FieldsHelper::getFields() để khai thác sức mạnh của hệ thống Custom Fields động vào Custom Component mà không cần thiết kế bảng thuộc tính thủ công.

Trong Bài học 40 — bài học cuối cùng khép lại Phần 4 (Lập trình Component) và toàn bộ chuỗi 40 bài học, chúng ta sẽ đi đến chặng đường hoàn thiện: Kiểm thử tự động, tối ưu hóa truy vấn SQL và đóng gói phân phối Component chuẩn (.zip).