Провайдеры данных

Провайдер данных

Провайдер данных — это PHP-класс, который позволяет динамически загружать данные сущности с бэкенда.

Достаточно в опции entities определить идентификаторы сущностей, наличие которых заставит диалог во время открытия выполнить запрос на бэкенд и получить данные от соответствующих провайдеров. Провайдеры могут добавить в диалог новые элементы, вкладки, а также футер.

const button = document.getElementById('button');
const dialog = new Dialog({
	targetNode: button,
	enableSearch: true,
	context: 'MY_MODULE_CONTEXT',
	entities: [
		{
			id: 'user', // пользователи
		},
		{
			id: 'department', // структура компании: выбор только пользователей
		},
	],
});

dialog.show();

Кроме первичной загрузки данных, провайдер может:

• Выполнять поиск элементов, когда набрана поисковая фраза.
• Определять глобальные настройки сущности (внешний вид по умолчанию, настройки поиска и др.).
• Динамически загружать дочерние элементы древовидных сущностей.

Регистрация

Для регистрации провайдера данных необходимо в файле настроек модуля (файл .settings.php в корне папки вашего модуля) в ключе ui.entity-selector определить следующую структуру.

<?php

// файл /my-module/.settings.php

return [
	'ui.entity-selector' => [
		'value' => [
			'entities' => [
				[
					'entityId' => 'my-module-entity',
					'provider' => [
						'moduleId' => 'my-module',
						'className' => '\\Vendor\\MyModule\\Integration\\UI\\EntitySelector\\MyProvider'
					],
				],
			],
			'extensions' => ['my-module.entity-selector'],
		],
		'readonly' => true,
	]
];

Каждый модуль может иметь несколько провайдеров данных, поэтому ключ entities определяет массив с данными сущностей. Опция entityId определяет уникальный идентификатор сущности, а provider задает полный путь к PHP-классу.

Дополнительно в опции extensions можно указать расширение, в котором могут быть определены глобальные настройки сущности, а также JavaScript-классы для дополнительной функциональности диалога (например, для создания своего футера или заглушки вкладки).

Глобальные настройки сущности

Для определения настроек сущности на глобальном уровне используется конфигурация экстеншена. Формат такой конфигурации позволяет гибко настраивать опции для сущностей: можно использовать произвольный PHP-код, языковые фразы и др.

В опции entities, которая определяется в ключе settings, задается массив с настройками сущностей.

<?php

// Файл /js/my-module/entity-selector/config.php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true)
{
	die();
}

if (!\Bitrix\Main\Loader::includeModule('my-module'))
{
	return [];
}

return [
	'settings' => [
		'entities' => [
			[
				'id' => 'my-module-entity',
				'options' => [
					'dynamicLoad' => true, // определяет динамическую загрузку данных с бэкенда
					'dynamicSearch' => true, // определяет динамический поиск
          
					// Задает дополнительные поля для поиска
					'searchFields' => [
						[ 'name' => 'position', 'type' => 'string' ],
						[ 'name' =>  'email', 'type' => 'email' ]
					],
					// Внешний вид элементов
					'itemOptions' => [
						'default' => [
							'supertitle' => 'Мой надзаголовок',
							'avatar' => '/path/to/image.svg', // аватар элементов по умолчанию
							'link' =>  '/service/entity/#id#/',
							'linkTitle' => 'узнать подробнее',
						],
						'inactive' => [ // для эл-тов, у которых entityType='inactive' будет выводиться бейдж 'Неактивный'
							'badges' => [
								[
									'title' => 'Неактивный',
									'textColor' => '#828b95',
									'bgColor' => '#eaebec',
								]
							],
						],
					],
					// Внешний вид элементов в виджете TagSelector
					'tagOptions' => [
						'default' => [
							'textColor' => '#1066bb',
							'bgColor' => '#bcedfc',
							'avatar' => '/path/to/image.svg', // аватар элементов в виджете TagSelector по умолчанию
						],
						'inactive' => [
							'textColor' => '#5f6670',
							'bgColor' => '#ecedef',
						],
					],

					// Дополнительные настройки бейджей
					'badgeOptions' => [
						[
							'title' => 'В отпуске',
							'bgColor' => '#b4f4e6',
							'textColor' => '#27a68a',
							'conditions' => [
								'isOnVacation' =>  true
							],
						],
					],
				],
			],
		]
	]
];

Формат настроек сущности (опция options) аналогичен структуре EntityOptions JavaScript-класса Entity.

export type EntityOptions = {
	dynamicLoad?: boolean,
	dynamicSearch?: boolean,
	itemOptions?: { [key: string]: any },
	tagOptions?: { [key: string]: any },
	badgeOptions?: ItemBadgeOptions[],
	searchable?: boolean,
	searchFields?: SearchField[],
	searchCacheLimits?: [],
};

Класс провайдера

Класс провайдера должен быть наследником абстрактного класса BaseProvider.

class MyProvider extends Bitrix\UI\EntitySelector\BaseProvider
{
	public function __construct(array $options = [])
	{
		parent::__construct();
	}

	public function isAvailable(): bool
	{
		// TODO: Implement getItems() method.
	}

	/**
	* @param array $ids
	*
	* @return Item[]
	*/
	public function getItems(array $ids) : array
	{
		// TODO: Implement getItems() method.
	}

	/**
	* @param array $ids
	*
	* @return Item[]
	*/
	public function getSelectedItems(array $ids) : array
	{
		// TODO: Implement getSelectedItems() method.
	}
}

В классе-наследнике обязательна реализация следующих методов:

• isAvailable — определяет доступность провайдера для использования.
• getItems — возвращает элементы по заданным идентификаторам.
• getSelectedItems - возвращает данные по заданным идентификаторам предвыбранных элементов.

Переопределение остальных методов опционально.

• fillDialog — заполняет диалог данными (элементы, вкладки, футер).
• getChildren — загружает в диалог дочерние элементы древовидных сущностей.
• doSearch — выполняет поиск элементов.
• handleBeforeItemSave — вызывается перед сохранением элемента в списке "Последних". Позволяет отменить сохранение.