Предустановленный фильтр

Иногда список должен показывать не всё содержимое сущности, а заранее ограниченный набор строк: элементы одного инфоблока, заказы одного склада, записи одного пользователя.

За запрос к сущности отвечает prepareQuery() контроллера — он получает готовый объект Bitrix\Main\ORM\Query\Query и может добавить в него условия.

php · ElementList.php

<?php

namespace Vendor\Module\UI;

use Bitrix\Main;
use Bitrix\Main\ORM\Query\Query;
use DevBx\Core\UI\List\Controller;
use DevBx\Core\UI\List\FieldRules;

class ElementList extends Controller
{
    protected int $iblockId = 0;

    public function initialize(array $options): Main\Result
    {
        $this->iblockId = (int)Main\Context::getCurrent()->getRequest()->get('IBLOCK_ID');

        $this->setEntity(\Bitrix\Iblock\ElementTable::getEntity());

        // Колонки: только нужные, иначе список покажет все поля элемента
        $this->getHeaderFieldsRule()
            ->setRule(FieldRules::RULE_ALLOW)
            ->setColumns(['ID', 'TIMESTAMP_X', 'ACTIVE', 'SORT', 'CODE', 'NAME']);

        // Фильтр: набор полей, по которым его строить
        $this->getFilterFieldsRule()
            ->setRule(FieldRules::RULE_ALLOW)
            ->setColumns(['ID', 'ACTIVE', 'CODE', 'NAME']);

        return parent::initialize($options);
    }

    public function prepareQuery(Query $query)
    {
        parent::prepareQuery($query);

        $query->where('IBLOCK_ID', $this->iblockId);
    }
}

parent::prepareQuery() вызывают всегда: базовая реализация добавляет в запрос поля колонок и включает служебные поля, если это разрешено. Своё условие дописывают после неё.

Колонки и фильтр — разные правила

Правило	Что задаёт
`getHeaderFieldsRule()`	какие поля становятся колонками списка
`getFilterFieldsRule()`	какие поля попадают в фильтр
`getReadOnlyFieldsRule()`	какие поля нельзя править прямо в списке

У каждого правила два режима: RULE_EXCLUDE — перечисленные поля убрать, RULE_ALLOW — оставить только перечисленные. Для сущности с большим числом полей второй режим удобнее: список полей короче и не растёт вместе с сущностью.

Передача параметра на форму редактирования

Если список ограничен параметром адреса, форма редактирования должна получить тот же параметр. Он передаётся в initialize():

php

$controller->initialize([
    'editUrl' => '/bitrix/admin/vendor_module_element_edit.php?IBLOCK_ID=' . $iblockId,
]);

Без этого правка строки откроет форму без нужного параметра, и сущность не найдёт, к чему относится запись.