Custom sections for left side menu

Overview

Attention! This overview is provided for informational purposes only. The described features are continuously updated. In the future, API also can be updated without backward compatibility. Due to this, using the listed API isn't recommended.

Configured sections allows to dynamically create extra sections for a left-side menu with custom public pages:

A dynamically created section is located at the left side menu listing. It shows the set of added pages that you can switch between using the top menu. Here's an example showing location of the standard Calendar menu section:

Custom sections allows the following actions:

• create a custom name for newly created section;
• add pages to it from custom modules;
• configure names and counters for specific page in section;
• configure each page availability in section for any user.

Starting setup

To create your own section you need to add a new entry to the table b_intranet_custom_section (\Bitrix\Intranet\CustomSection\Entity\CustomSectionTable).

Table field values:

• CODE - section character code to be used for generating a URL;
• TITLE - displayed section name;
• MODULE_ID - module ID of the created section. Necessary for filtering, access permission checks and etc.

You need to perform two actions to add a page to a created section:

1. Add entry to the table b_intranet_custom_section_page (\Bitrix\Intranet\CustomSection\Entity\CustomSectionPageTable).
2. Make sure that provider was described.

Field values in table:

• CUSTOM_SECTION_ID - section ID, that к которому относится эта страница.
• CODE - page symbolic code to be used for generating a URL.
• TITLE - displayed section name.
• MODULE_ID - this page module ID, used for provider operation.
• SETTINGS - arbitrary string to be used used for provider operation. Length limit (255 characters).
• SORT - page sorting. Affects the section top menu layout and routing.

Provider

You can add pages from arbitrary modules to a custom section. Main conditions: this module must have a provider, descendant class \Bitrix\Intranet\CustomSection\Provider. Intranet will communicate with target module using this provider.

The file module's .settings.php file contains the provider description:

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

Intranet will query the provider and retrieve information after adding configurable sections to the left menu and opening such section in a browser.

Module to query this provider is defined using the page's MODULE_ID (b_intranet_custom_section_page.MODULE_ID). In case the provider is not found, page won't be displayed.

Main provider methods:

• isAvailable(string $pageSettings, int $userId): bool allows for user with such $userId to open the page;
• resolveComponent(string $pageSettings, Uri $url): ?\Bitrix\Intranet\CustomSection\Provider\Component - returns parameters for connecting a component to be displayed at the page;
• getCounterId(string $pageSettings): ?string - returns counter ID for the page, if counter is available;
• getCounterValue(string $pageSettings): ?int - returns a counter current value for the page, if such counter is available.

All the signatures above have the parameter string $pageSettings. This value is sourced from b_intranet_custom_section_page.SETTINGS. It's a string that is parsed by the provider and select parameters from. This specific string is used to define what kind of page it is, to whom it should be displayed and which component must be connected.

Because filtering is performed by this field, it's not recommended to write serialized arrays/objects/JSON here.

Example of processed $pageSettings inside the provider:

// $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);
}

Operation algorithm

Building left-side menu

You are adding newly created custom sections to the left-side menu. The sequence of this process is the following:

1. Getting list of sections.
2. Querying page providers that belong to the section. If at least a single page is available for current user, this section will be displayed at the left menu. When there are no pages or they are all unavailable, the section won't be displayed.

Using link to enter the section

The following algorithm is executed when opening a custom section:

1. Defining the section to query.
2. Getting a list of this section pages available for current user (filtering by Provider::isAvailable).
3. Determining a section page to be queried. If such page is not found or unavailable, selects the last opened page or the page with the lowest sorting.
4. Collecting counter data for available pages using providers.
5. Getting the component that must be connected at the page (Provider::resolveComponent). Pass to the method the opened page $pageSettings and URL used for forwarding (can be employed, for example, for getting required GET parameters).
6. Rendering of interface and connecting the component.

useful API

• \Bitrix\Intranet\CustomSection\Manager - service, retrieved using ServiceLocator.
  • \Bitrix\Intranet\CustomSection\Manager::getUrlForPage - generates link for custom section.

Examples

• The CRM module uses custom pages feature for showing smart processes outside the CRM section CRM;
• You can allow user to create "aliases" (for specific page to be available for both main section of target module and via custom section).