Настраиваемые разделы в левом меню

Обзор

Внимание! Данный материал носит информационный характер. Описанный функционал является нестабильным, и в будущем API может быть изменен без сохранения обратной совместимости. В связи с этим использовать приведенный API не рекомендуется.

Настраиваемые разделы позволяют динамически создавать дополнительные разделы левого меню со своими публичными страницами и управлять ими:

Настраиваемый раздел представляет собой динамически созданный раздел в левом меню. В нём отображается набор добавленных страниц, между которыми можно переключаться через верхнее меню:

С помощью настраиваемых разделов можно:

создавать раздел с произвольным названием;
добавлять в него страницы из произвольных модулей;
настраивать название и счётчики конкретной страницы в разделе;
настраивать доступность каждой отдельной страницы в разделе для любого пользователя.

Начало работы

Чтобы создать свой раздел, необходимо добавить новую запись в таблицу b_intranet_custom_section (\Bitrix\Intranet\CustomSection\Entity\CustomSectionTable).

Значения полей в таблице:

CODE – символьный код раздела, который будет использован для построения URL;
TITLE – отображаемое название раздела;
MODULE_ID – ID модуля, который создал раздел. Необходимо для фильтрации, проверки прав и т.п.

Для добавления страницы в созданный раздел нужно выполнить два действия:

Добавить запись в таблицу b_intranet_custom_section_page (\Bitrix\Intranet\CustomSection\Entity\CustomSectionPageTable).
Удостовериться, что описан провайдер.

Значения полей в таблице:

CUSTOM_SECTION_ID – ID раздела, к которому относится эта страница.
CODE – символьный код страницы, который будет использован для построения URL.
TITLE – отображаемое название раздела.
MODULE_ID – ID модуля, которому принадлежит эта страница. Используется при работе провайдера.
SETTINGS – произвольная строка, которая будет использоваться при работе провайдера. Ограничивается по длине (255 символов).
SORT – сортировка страницы. Учитывается при построении верхнего меню раздела и роутинге.

Провайдер

В настраиваемый раздел можно добавлять страницы из произвольного модуля. Главное условие — этот модуль должен иметь провайдера, класс-наследник \Bitrix\Intranet\CustomSection\Provider. Через него будет происходить общение интранета с целевым модулем.

Провайдер описывается в файле .settings.php модуля:

return [
	'intranet.customSection' => [
		'value' => [
			'provider' => '\\Bitrix\\Crm\\Integration\\Intranet\\CustomSectionProvider',
		],
	],
];

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

Модуль, к провайдеру которого нужно обращаться, определяется через MODULE_ID страницы (b_intranet_custom_section_page.MODULE_ID). Если провайдер не найден, то страница отображаться не будет.

Основные методы провайдера:

isAvailable(string $pageSettings, int $userId): bool – может ли пользователь с таким $userId открыть страницу;
resolveComponent(string $pageSettings, Uri $url): ?\Bitrix\Intranet\CustomSection\Provider\Component – возвращает параметры для подключения компонента, который должен быть отображен на странице;
getCounterId(string $pageSettings): ?string – возвращает ID счетчика для страницы, если счетчик есть;
getCounterValue(string $pageSettings): ?int – возвращает текущее значение счетчика для страницы, если счетчик есть.

Во всех сигнатурах выше фигурирует параметр string $pageSettings. Данное значение берётся из b_intranet_custom_section_page.SETTINGS. Это строка, которую провайдер будет парсить и вычленять параметры. Именно по ней провайдер будет определять, что это за страница, кому её нужно показывать и какой компонент нужно подключить.

Так как по данному полю производится фильтрация, писать сюда сериализованные массивы/объекты/JSON не рекомендуется.

Пример обработки $pageSettings внутри провайдера:

// $pageSettings = '128~other_params';
public function isAvailable(string $pageSettings, int $userId): bool {
	$params = explode('~', $pageSettings);
	$entityTypeId = (int)$params[0];
	return Container::getInstance()->getUserPermissions($userId)->checkReadPermissions($entityTypeId);
}

Алгоритм работы

Построение левого меню

При построении левого меню в него добавляются созданные настраиваемые разделы. Происходит это по следующему алгоритму:

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

Переход по ссылке на раздел

При открытии настраиваемого раздела выполняется следующий алгоритм:

Определение раздела, к которому происходит обращение.
Получение списка доступных для текущего пользователя страниц этого раздела (фильтрация по Provider::isAvailable).
Определение страницы раздела, к которой происходит обращение. Если такая страница не найдена или недоступна, то будет выбрана последняя открытая страница или страница с наименьшей сортировкой.
Сбор данных о счетчиках для доступных страниц через провайдеров.
Получение компонента, который должен быть подключен на странице (Provider::resolveComponent). В метод передается $pageSettings открытой страницы и URL, по которому произошел переход (может использоваться, например, для получения нужных GET-параметров).
Отрисовка интерфейса и подключение компонента.

Полезное API

\Bitrix\Intranet\CustomSection\Manager – сервис, получаемый через ServiceLocator.
- \Bitrix\Intranet\CustomSection\Manager::getUrlForPage – сгенерирует ссылку на настраиваемый раздел.

Примеры реализации

Модуль CRM использует механизм настраиваемых страниц для показа смарт-процессов вне основного раздела CRM;
Можно позволить пользователю делать «алиасы» (чтобы конкретная страница была доступна как в основном разделе целевого модуля, так и через настраиваемый раздел).