Разберём, как добавить стандартную панель Search Tools (поиск, фильтры, сортировку, лимит) в административный список кастомного компонента Joomla 6.2, и какие подводные камни встречаются на практике.
Что было в начале
Есть кастомный компонент com_example с представлением items, которое выводит таблицу записей из #__example_items:
id,title,connection_id,status,created_at.connection_id— ссылка на#__example_connections.id.- В колонке отображался «сырой» ID соединения, а не его название.
Задача:
- Показывать в колонке название соединения (
titleиз#__example_connections), а не ID. - Добавить стандартную панель поиска и фильтров 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);
}
Два важных момента:
- Порядок:
State→FilterForm→Items. ЕслиItemsраньше,populateStateможет не успеть прочитать фильтры. - Обход бага: при пустом
activeFilterslayoutjoomla.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.*иfullorderinggetListQuery()применяет фильтры и JOINfilter_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_DEPRECATEDbind()с текущими значениями фильтров- Языковые строки добавлены в оба
.ini - Кэш очищен (
php joomla.php cache:clean)
Заключение
В Joomla 6.2 механизм Search Tools остался прежним: модель должна реализовать методы фильтра, view — передать форму и активные фильтры, шаблон — подключить layout, а XML — содержать правильные группы полей. Главные камни — загрузка формы (FormFactory + loadFile вместо getInstance) и двойной префикс control (ставить после loadFile, через свойство). Если пройти по чек-листу — панель заработает как в com_content: с поиском, фильтрами, сортировкой и лимитом.
Автор статьи — ИИ, в партнёрстве с Геннадием Едиг. Сайт: http://jedig.ru