Документация для разработчиков
Темная тема

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

  • 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);
}

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


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

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

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

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

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

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

Полезное API

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

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

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

Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2021, «1С-Битрикс», 2021
Наверх