Разберём, как добавить стандартную панель Search Tools (поиск, фильтры, сортировку, лимит) в административный список кастомного компонента Joomla 6.2, и какие подводные камни встречаются на практике.


Что было в начале

Есть кастомный компонент com_example с представлением items, которое выводит таблицу записей из #__example_items:

  • id, title, connection_id, status, created_at.
  • connection_id — ссылка на #__example_connections.id.
  • В колонке отображался «сырой» ID соединения, а не его название.

Задача:

  1. Показывать в колонке название соединения (title из #__example_connections), а не ID.
  2. Добавить стандартную панель поиска и фильтров Joomla, включая фильтр по connection_id.

Шаг 1. Модель: JOIN и фильтры

В ItemsModel (наследник Joomla\CMS\MVC\Model\ListModel) добавляем JOIN с таблицей соединений и обработку фильтров.

protected function getListQuery()
{
    $db = $this->getDatabase();
    $query = $db->getQuery(true);

    $query->select([
            $db->quoteName('i') . '.*',
            $db->quoteName('c.title', 'connection_title'),
        ])
        ->from($db->quoteName('#__example_items', 'i'))
        ->join('LEFT', $db->quoteName('#__example_connections', 'c')
            . ' ON ' . $db->quoteName('c.id') . ' = ' . $db->quoteName('i.connection_id'));

    // Поиск
    $search = $this->getState('filter.search');
    if (!empty($search)) {
        $search = $db->quote('%' . $db->escape($search, true) . '%');
        $query->where('('
            . $db->quoteName('i.title') . ' LIKE ' . $search
            . ' OR ' . $db->quoteName('i.connection_id') . ' LIKE ' . $search
            . ' OR ' . $db->quoteName('c.title') . ' LIKE ' . $search
            . ')');
    }

    // Фильтр по статусу
    $status = $this->getState('filter.status');
    if (!empty($status)) {
        $query->where($db->quoteName('i.status') . ' = ' . $db->quote($status));
    }

    // Фильтр по connection_id
    $connId = $this->getState('filter.connection_id');
    if (!empty($connId)) {
        $query->where($db->quoteName('i.connection_id') . ' = ' . $db->quote($connId));
    }

    // Сортировка
    $orderCol = $this->getState('list.ordering', 'i.created_at');
    $orderDirn = strtolower($this->getState('list.direction', 'desc')) === 'asc' ? 'ASC' : 'DESC';
    $orderMap = [
        'id'               => 'i.id',
        'title'            => 'i.title',
        'connection_id'    => 'c.title',
        'connection_title' => 'c.title',
        'status'           => 'i.status',
        'created_at'       => 'i.created_at',
    ];
    $orderColSql = $orderMap[$orderCol] ?? 'i.created_at';
    $query->order($db->escape($orderColSql) . ' ' . $orderDirn);

    return $query;
}

В конструкторе модели:

public function __construct($config = [])
{
    $config['filter_fields'] = [
        'id', 'title', 'connection_id', 'status', 'created_at', 'connection_title',
    ];
    parent::__construct($config);
}

Шаг 2. populateState: чтение фильтров и fullordering

protected function populateState($ordering = 'i.created_at', $direction = 'DESC')
{
    $this->context = 'com_example.items';
    parent::populateState($ordering, $direction);

    $fullordering = $this->getUserStateFromRequest($this->context . '.list.fullordering', 'fullordering', '');
    if (!empty($fullordering)) {
        $parts = explode(' ', trim($fullordering));
        if (count($parts) === 2) {
            $this->setState('list.ordering', $parts[0]);
            $this->setState('list.direction', strtoupper($parts[1]) === 'ASC' ? 'ASC' : 'DESC');
        }
    }

    $this->setState('filter.search',
        $this->getUserStateFromRequest($this->context . '.filter.search', 'filter_search', '', 'string'));
    $this->setState('filter.status',
        $this->getUserStateFromRequest($this->context . '.filter.status', 'filter_status', '', 'string'));
    $this->setState('filter.connection_id',
        $this->getUserStateFromRequest($this->context . '.filter.connection_id', 'filter_connection_id', '', 'string'));
}

Шаг 3. getFilterForm и getActiveFilters

ListModel не реализует getFilterForm() / getActiveFilters(), поэтому layout Search Tools упадёт с Call to a member function getGroup() on null. Добавляем методы.

В Joomla 6.2 (как и в 5.x) Form::getInstance() в кастомном компоненте может не находить файл. Рабочий путь — FormFactory + loadFile():

use Joomla\CMS\Factory;
use Joomla\CMS\Form\Form;
use Joomla\CMS\Form\FormFactoryInterface;

public function getFilterForm($data = [], $loadData = true)
{
    $form = Factory::getContainer()->get(FormFactoryInterface::class)->createForm(
        $this->context . '.filter',
        ['load_data' => $loadData]
    );

    $form->loadFile(JPATH_ROOT . '/administrator/components/com_example/forms/filter_items.xml');

    $prev = error_reporting();
    error_reporting($prev & ~E_DEPRECATED);
    $form->control = 'filter';
    error_reporting($prev);

    if ($loadData) {
        $form->bind(['filter' => [
            'search'        => $this->getState('filter.search', ''),
            'status'        => $this->getState('filter.status', ''),
            'connection_id' => $this->getState('filter.connection_id', ''),
        ]]);
    }

    return $form;
}

public function getActiveFilters()
{
    $filters = [];
    foreach (['search', 'status', 'connection_id'] as $name) {
        $value = $this->getState('filter.' . $name);
        if ($value !== null && $value !== '') {
            $filters[$name] = $value;
        }
    }
    return $filters;
}

Примечания:

  • $form->control = 'filter' задаёт префикс имён (filter[search]). Свойство динамическое, в PHP 8.2+ даёт Deprecated, подавляем локально.
  • bind() нужен, чтобы после сабмита выбранное значение оставалось в списке.
  • loadFile() с абсолютным путём обходит проблему поиска файла.

Шаг 4. Форма фильтра forms/filter_items.xml

<?xml version="1.0" encoding="UTF-8"?>
<form>
    <fields name="filter">
        <field
            name="search"
            type="text"
            inputmode="search"
            label="COM_EXAMPLE_FILTER_SEARCH"
            hint="JSEARCH_FILTER"
            class="js-stools-search-string"
        />
        <field
            name="status"
            type="list"
            label="COM_EXAMPLE_FIELD_STATUS"
            class="js-stools-field-filter"
            onchange="this.form.submit();"
        >
            <option value="">COM_EXAMPLE_FILTER_SELECT_STATUS</option>
            <option value="published">COM_EXAMPLE_STATUS_PUBLISHED</option>
            <option value="unpublished">COM_EXAMPLE_STATUS_UNPUBLISHED</option>
        </field>
        <field
            name="connection_id"
            type="sql"
            query="SELECT id, title FROM #__example_connections WHERE title IS NOT NULL AND title != '' ORDER BY title"
            key_field="id"
            value_field="title"
            label="COM_EXAMPLE_FIELD_CONNECTION_ID"
            class="js-stools-field-filter"
            onchange="this.form.submit();"
        >
            <option value="">COM_EXAMPLE_FILTER_SELECT_CONNECTION</option>
        </field>
    </fields>

    <fields name="list">
        <field name="fullordering" type="list" label="JGLOBAL_SORT_BY" onchange="this.form.submit();" default="i.created_at DESC">
            <option value="">JGLOBAL_SORT_BY</option>
            <option value="i.created_at DESC">COM_EXAMPLE_FIELD_CREATED_DESC</option>
            <option value="i.created_at ASC">COM_EXAMPLE_FIELD_CREATED_ASC</option>
            <option value="c.title ASC">COM_EXAMPLE_FIELD_CONNECTION_ASC</option>
            <option value="c.title DESC">COM_EXAMPLE_FIELD_CONNECTION_DESC</option>
        </field>
        <field name="limit" type="limitbox" label="COM_USERS_LIST_LIMIT" class="input-mini" default="25" onchange="this.form.submit();" />
    </fields>
</form>

Ключевой элемент — type="sql": Joomla сама выполнит запрос и построит выпадающий список.


Шаг 5. HtmlView: filterForm и activeFilters

public function display($tpl = null)
{
    $this->state         = $this->get('State');
    $this->filterForm    = $this->get('FilterForm');
    $this->activeFilters = $this->get('ActiveFilters');

    if (empty($this->activeFilters)) {
        $this->activeFilters = ['search' => ''];
    }

    $this->items      = $this->get('Items');
    $this->pagination = $this->get('Pagination');

    // ToolbarHelper::title(...); и кнопки

    parent::display($tpl);
}

Два важных момента:

  1. Порядок: State → FilterForm → Items. Если Items раньше, populateState может не успеть прочитать фильтры.
  2. Обход бага: при пустом activeFilters layout joomla.searchtools.default скрывает панель. Принудительно заполняем массив.

Шаг 6. Шаблон: Search Tools + вывод названия

<?php echo LayoutHelper::render('joomla.searchtools.default', ['view' => $this]); ?>

<table class="table table-striped" id="itemsList">
    <thead>
        <tr>
            <th width="1%"><?php echo HTMLHelper::_('grid.checkall'); ?></th>
            <th><?php echo HTMLHelper::_('searchtools.sort', 'JGLOBAL_FIELD_ID_LABEL', 'i.id', $listDirn, $listOrder); ?></th>
            <th><?php echo HTMLHelper::_('searchtools.sort', 'COM_EXAMPLE_FIELD_TITLE', 'i.title', $listDirn, $listOrder); ?></th>
            <th><?php echo HTMLHelper::_('searchtools.sort', 'COM_EXAMPLE_FIELD_CONNECTION_ID', 'connection_title', $listDirn, $listOrder); ?></th>
            <th><?php echo HTMLHelper::_('searchtools.sort', 'COM_EXAMPLE_FIELD_STATUS', 'i.status', $listDirn, $listOrder); ?></th>
            <th><?php echo HTMLHelper::_('searchtools.sort', 'JDATE', 'i.created_at', $listDirn, $listOrder); ?></th>
        </tr>
    </thead>
    <tbody>
    <?php foreach ($this->items as $i => $item) : ?>
        <tr>
            <td><?php echo HTMLHelper::_('grid.id', $i, $item->id); ?></td>
            <td><?php echo $this->escape($item->id); ?></td>
            <td><?php echo $this->escape($item->title); ?></td>
            <td>
                <?php if (!empty($item->connection_title)) : ?>
                    <?php echo $this->escape($item->connection_title); ?>
                <?php else : ?>
                    <span class="text-muted"><?php echo $this->escape($item->connection_id); ?></span>
                <?php endif; ?>
            </td>
            <td><?php echo $this->escape($item->status); ?></td>
            <td><?php echo $this->escape($item->created_at); ?></td>
        </tr>
    <?php endforeach; ?>
    </tbody>
</table>

Шаг 7. Языковые строки

В language/en-GB/com_example.ini и language/ru-RU/com_example.ini добавьте:

COM_EXAMPLE_FILTER_SEARCH="Search"
COM_EXAMPLE_FILTER_SELECT_STATUS="— Select Status —"
COM_EXAMPLE_FILTER_SELECT_CONNECTION="— Select Connection —"
COM_EXAMPLE_FIELD_CONNECTION_ID="Connection"
COM_EXAMPLE_FIELD_CREATED_DESC="Created At (newest first)"
COM_EXAMPLE_FIELD_CREATED_ASC="Created At (oldest first)"
COM_EXAMPLE_FIELD_CONNECTION_ASC="Connection (A→Z)"
COM_EXAMPLE_FIELD_CONNECTION_DESC="Connection (Z→A)"

Грабли (актуальны для Joomla 6.2)

1. getGroup() on null

Layout Search Tools падает, если во view не установлены filterForm / activeFilters. Лечится шагом 5.

2. Form::getInstance() could not load file

Form::getInstance() в кастомном компоненте Joomla 6.2 может не находить XML-файл. Решение: FormFactory::createForm() + $form->loadFile(абсолютный_путь).

3. Двойной префикс filter_filter_search

Если createForm() вызвать с ['control' => 'filter'] и XML содержит <fields name="filter">, Joomla склеивает префиксы. Решение: не передавать control в createForm(), а установить после loadFile(): $form->control = 'filter'. Свойство динамическое — в PHP 8.2+ нужен локальный error_reporting($prev & ~E_DEPRECATED).

4. setControl() не существует

В Joomla 6.2 у Form нет метода setControl(). Есть только свойство $form->control.

5. Панель фильтров скрыта при пустом activeFilters

Layout скрывает панель, если activeFilters пуст, игнорируя filtersHidden => false. Лечится принудительным заполнением activeFilters во view.

6. Выбранное значение «слетает» после сабмита

createForm(['load_data' => true]) не подставляет значения из $this->getState('filter.*') автоматически. Нужен $form->bind([...]) с текущими значениями.


Чек-лист «Search Tools в кастомном списке Joomla 6.2»

  • В модели есть getFilterForm() и getActiveFilters()
  • populateState() читает filter.* и fullordering
  • getListQuery() применяет фильтры и JOIN
  • filter_fields содержит все сортируемые колонки
  • Во view установлены filterForm и activeFilters (не пустой)
  • Порядок: State → FilterForm → Items
  • В шаблоне подключён LayoutHelper::render('joomla.searchtools.default', ['view' => $this])
  • Заголовки через searchtools.sort
  • Форма фильтра содержит <fields name="filter"> и <fields name="list">
  • FormFactory + loadFile (а не getInstance)
  • control ставится после loadFile, через свойство, с подавлением E_DEPRECATED
  • bind() с текущими значениями фильтров
  • Языковые строки добавлены в оба .ini
  • Кэш очищен (php joomla.php cache:clean)

Заключение

В Joomla 6.2 механизм Search Tools остался прежним: модель должна реализовать методы фильтра, view — передать форму и активные фильтры, шаблон — подключить layout, а XML — содержать правильные группы полей. Главные камни — загрузка формы (FormFactory + loadFile вместо getInstance) и двойной префикс control (ставить после loadFile, через свойство). Если пройти по чек-листу — панель заработает как в com_content: с поиском, фильтрами, сортировкой и лимитом.


Автор статьи — ИИ, в партнёрстве с Геннадием Едиг. Сайт: http://jedig.ru