Инфоблоки тема 14 из 27

Поля и форматеры элементов

Состав ответа по элементу инфоблока задаётся в Настройки -> Настройки модулей -> BIK.REST -> Инфоблоки: штатные поля, свойства, каталог, служебные блоки. Когда этого не хватает, модуль расширяется двумя способами без правки ядра:

в этой теме 5
  1. Куда класть файлы
  2. Обработчик поля
  3. Форматер свойства
  4. Событие OnAfterIblockElementBuild
  5. Проверка
ЧтоКлассЗадача
Обработчик поляAbstractElementFieldдобавить в ответ своё поле, которого нет среди полей и свойств (например, images)
Форматер свойстваAbstractPropertyFormatterизменить вид значения конкретного свойства (например, привязка - в {id, name, code})
Событиеbik.rest:OnAfterIblockElementBuildлёгкая правка собранного элемента перед отдачей

Куда класть файлы

Классы - в каталог /local/bik.rest/fields/ сайта.

  • namespace - BIK\Rest\Fields;
  • имя файла совпадает с именем класса (DocumentImagesField.php - class DocumentImagesField);
  • класс не абстрактный и наследует AbstractElementField или AbstractPropertyFormatter.

Реестр (FieldRegistry) находит классы сам и хранит их список в кеше «Справочники». После добавления или удаления файла сохраните любой набор инфоблока или нажмите «Сбросить кеш API» (Настройки модуля -> Кеширование), иначе класс появится по истечении срока кеша. Код, которого нет в реестре (класс удалён, опечатка), в профиле пропускается без ошибки: поле или форматер просто не работает.

Обработчик поля

Обработчик появляется чипом в группе «Обработчики» набора («Список», «Детальная», «Вложенный», «Корзина и заказ»). Выбранный чип добавляет в ответ ключ code().

php
abstract class AbstractElementField
{
    abstract public static function code(): string;   // ключ в ответе, camelCase
    abstract public static function title(): string;  // подпись чипа
    public static function supports(array $iblock): bool;  // для каких инфоблоков доступен (по умолчанию для всех)
    public static function requires(): array;         // что подгрузить, даже если не выведено в ответ
    abstract public function batch(array $elements, ResponseProfile $p): array;
    public static function schema(): array;           // схема значения для Swagger
}

batch() - пакетно

batch() вызывается один раз на страницу элементов, а не на каждый элемент. Получает [ID элемента => данные], возвращает [ID элемента => значение]. Запросы к БД внутри делайте по всем элементам сразу ('ID' => array_keys($elements)), а не в цикле: иначе вернётся N+1, от которого ушёл сборщик.

В данных элемента:

  • штатные поля набора и поля из requires()['fields'] по кодам (NAME, DETAIL_PICTURE - путь или ссылка на ресайз по размерам набора);
  • PROPERTIES - свойства набора и из requires()['properties'] в формате набора. Формат «Полный»: значение лежит в VALUE; «Компактный»: само значение. Привязки к элементам раскрыты по набору «Вложенный» связанного инфоблока (или это id, если у свойства выбран вид «Только ID»);
  • SECTION, PATH, SEO - если они есть в наборе.

Если значения нет, не возвращайте ключ (или верните null): поле у элемента не выводится.

Результат batch() хранится в кеше «Данные элементов» вместе с остальными данными элемента и сбрасывается теми же тегами: изменение элемента или элемента, выведенного в нём (документ, бренд), обновляет и значение поля. Поэтому batch() не должен зависеть от пользователя, сессии и времени. Пользовательские данные (избранное, цены со скидкой по группам) отдавайте через событие (ниже), а не через обработчик. Если batch() бросит исключение, ошибка пишется в журнал, поле у этой страницы не выводится, остальной ответ не ломается.

requires() - подгрузить, но не выводить

php
public static function requires(): array
{
    return ['fields' => ['DETAIL_PICTURE'], 'properties' => ['DOCUMENTS']];
}

Сборщик загружает перечисленные поля и свойства (и раскрывает привязки по набору «Вложенный»), но в ответ они не идут, если не выбраны в наборе. Так images выводится без вывода самих документов. Свойства указываются кодом.

supports() и schema()

supports(array $iblock) ограничивает чип инфоблоками, где обработчик имеет смысл: $iblock['code'], ['apiCode'], ['type'], ['id']. schema() возвращает схему значения (OpenAPI 3), её использует Swagger при описании ответа: ['type' => 'array', 'items' => ['type' => 'string']].

Пример в модуле: Fields\GalleryField

Поле images - детальная картинка и файлы свойства MORE_PHOTO. Размеры берутся из «Размеров картинок» набора для DETAIL_PICTURE и MORE_PHOTO.

Пример: DocumentImagesField - картинки из привязанных документов

Задача: у товара привязаны документы (инфоблок «Документы»), в них файлы-картинки и тип документа. Витрине нужен список images: первая - главная картинка из документа с типом main, остальные - файлы документов с типом gallery; самих документов в ответе быть не должно.

Подготовка в настройках:

  1. В инфоблоке «Документы» у свойств TYPE (список) и FILE (файл, множественное) включить флаг «Показывать во вложенном виде (BIK.REST)».
  2. В наборе «Вложенный» инфоблока «Документы» выбрать формат свойств «Компактный» (тогда файл - это путь, список - {xmlId, value}).
  3. В наборе «Детальная» (и «Список») товара выбрать чип «Картинки из документов». Свойство DOCUMENTS не выбирайте.
php
<?php
namespace BIK\Rest\Fields;

use BIK\Rest\Services\Element\ResponseProfile;

class DocumentImagesField extends AbstractElementField
{
    const LIMIT = 5;

    public static function code(): string
    {
        return 'images';
    }

    public static function title(): string
    {
        return 'Картинки из документов';
    }

    public static function supports(array $iblock): bool
    {
        return $iblock['apiCode'] === 'catalog';
    }

    public static function requires(): array
    {
        return ['fields' => [], 'properties' => ['DOCUMENTS']];
    }

    public function batch(array $elements, ResponseProfile $p): array
    {
        $result = [];
        foreach ($elements as $id => $element) {
            $documents = $element['PROPERTIES']['DOCUMENTS'] ?? [];
            if (isset($documents['VALUE'])) {      // формат «Полный»: значения - в VALUE
                $documents = $documents['VALUE'];
            }
            $main = null;
            $gallery = [];
            foreach ((array)$documents as $document) {
                if (!is_array($document)) {         // привязка «только ID»: документа нет
                    continue;
                }
                $properties = $document['PROPERTIES'] ?? [];
                $type = $properties['TYPE']['xmlId'] ?? ($properties['TYPE']['XML_ID'] ?? '');
                $files = (array)($properties['FILE'] ?? []);
                if ($type === 'main' && $main === null && $files) {
                    $main = reset($files);
                } elseif ($type === 'gallery') {
                    $gallery = array_merge($gallery, $files);
                }
            }
            $images = array_values(array_unique(array_filter(array_merge([$main], $gallery))));
            if ($images) {
                $result[$id] = array_slice($images, 0, static::LIMIT);
            }
        }

        return $result;
    }

    public static function schema(): array
    {
        return ['type' => 'array', 'items' => ['type' => 'string'], 'maxItems' => static::LIMIT];
    }
}

Ключ xmlId и вид значений зависят от формата набора «Вложенный»: сверяйтесь с реальным ответом.

Форматер свойства

Форматер выбирается для конкретного свойства на его чипе в наборе инфоблока: стрелка ▾ у чипа открывает меню «Вид значения» - там базовый вид, у привязок «Только ID» и форматеры, подходящие свойству (supports($property)). Стрелка есть только у свойств, для которых есть выбор. Выбранный форматер виден в чипе короткой подписью shortTitle(): «Производитель · кратко».

php
abstract class AbstractPropertyFormatter
{
    abstract public static function code(): string;
    abstract public static function title(): string;
    public static function shortTitle(): string;                         // подпись в чипе, по умолчанию title()
    abstract public static function supports(array $property): bool;   // $property - строка b_iblock_property
    abstract public function format(array $values, array $property, ResponseProfile $p): mixed;
    public static function schema(array $property): array;
}

format() получает значения свойства списком (и у одиночного свойства - список из одного) уже в базовом виде набора и возвращает то, что окажется в ответе как значение: у «Полного» формата - в VALUE, у «Компактного» - вместо значения. У множественного свойства верните обычно массив, у одиночного - одно значение. Пустой результат - свойство не выводится. Форматер применяется после базового формата, его результат кешируется вместе с данными элемента.

Пример в модуле: Fields\LinkBriefFormatter - привязка к элементу превращается в {id, name, code} вместо собранного элемента. Вид «Только ID» и форматер у одного свойства в одном наборе не сочетаются: выбирается один вид значения.

Событие OnAfterIblockElementBuild

Для разовой правки без своего класса. Вызывается после сборки, перед отдачей, на каждый ответ, вне кеша данных элемента: можно использовать пользователя и текущее время. Платите за это сами: код выполняется для каждого элемента ответа, тяжёлые запросы в нём не делайте (для них - обработчик поля с batch()).

php
\Bitrix\Main\EventManager::getInstance()->addEventHandler('bik.rest', 'OnAfterIblockElementBuild', function (\BIK\Rest\Events\ApiBuildEvent $event) {
    $item = $event->getItem();
    if ($event->getContext() === 'list' && isset($item['NAME'])) {
        $item['NAME'] = trim($item['NAME']);
        $event->setItem($item);
    }
});

Обработчик получает объект ApiBuildEvent: getItem() - собранный элемент (ключи полей, PROPERTIES, PRODUCT и т.д., как в ответе; изменённый возвращается через setItem()), getContext() - list, detail, nested, basket, getIblockId() - ID инфоблока. Регистрируется в /local/php_interface/init.php.

Событие вызывается для элементов, которые отдаются самостоятельно: элементы списка и карточки, позиции корзины, предложения. Привязки, раскрытые внутри PROPERTIES (документы, бренд), собираются внутри кеша родителя и событие для них не вызывается: для них используйте набор «Вложенный» и форматеры.

Проверка

  1. Положить файл в /local/bik.rest/fields/, нажать «Сбросить кеш API».
  2. В Настройки -> BIK.REST -> Инфоблоки открыть инфоблок, в нужном наборе появится чип в группе «Обработчики» (или список форматеров у свойства). Сохранить набор.
  3. Запросить элементы: в ответе появится ключ code() обработчика.

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным