Перейти к содержимому
BXWiki

Кнопка на панели управления - описание, иконка, меню

Редактору нужен короткий путь из витрины в свой инструмент: выгрузку, отчёт, пересчёт остатков. Ставим для этого свою кнопку на верхнюю панель управления и вешаем на неё выпадающее меню.

Решение

Панель на странице

Панель выводит вызов в шаблоне сайта:

<body>
<?$APPLICATION->ShowPanel();?>   <!-- сразу после открывающего body -->

Без этого вызова кнопки добавляются, но выводить их некуда. Гостю панель не показывается: у неавторизованного посетителя вызов ничего не печатает.

Описание кнопки

Кнопку добавляем массивом полей:

$APPLICATION->AddPanelButton([
    'ID'        => 'vendor_export',   // уникален среди всех кнопок панели
    'TEXT'      => 'Выгрузка',        // подпись под иконкой
    'TYPE'      => 'BIG',             // большая кнопка, а не строка меню
    'HREF'      => '/bitrix/admin/vendor_export.php',
    'MAIN_SORT' => 100,               // положение среди кнопок панели
    'SORT'      => 10,                // положение внутри своей группы
]);

Уникальность платформа держит по ключу ID: вторая кнопка с тем же идентификатором на панель не попадёт. Поэтому в идентификатор кладут префикс своего решения, а не общее слово вроде export. В HREF допустим и вызов javascript:.

Иконка и подсказка

Внешний вид и подсказки задают отдельные ключи:

'ICON' => 'vendor-export-icon',            // css-класс иконки
'SRC'  => '/local/images/export.svg',      // либо картинка вместо класса
'ALT'  => 'Выгрузка каталога',             // короткая подсказка браузера
'HINT' => [
    'TITLE' => 'Выгрузка каталога',
    'TEXT'  => 'Соберёт файл по текущему разделу',
],

Ключ HINT описывает подсказку самой кнопки, HINT_MENU - подсказку её выпадающего меню. Оба текста понимают HTML, поэтому значения из базы перед подстановкой экранируем.

Пункты меню

Меню перечисляем прямо в описании кнопки:

'MENU' => [
    [
        'TEXT'    => 'Выгрузить раздел',
        'TITLE'   => 'Только текущий раздел',
        'SORT'    => 10,
        'ACTION'  => 'BX.Vendor.exportSection()', // javascript-код пункта
        'DEFAULT' => true,                        // действие по клику на кнопку
    ],
    ['SEPARATOR' => true],
],

Пункт с ключом DEFAULT срабатывает при нажатии на саму кнопку, а не только внутри меню. Каждый пункт умеет нести собственный вложенный MENU, так что дерево получается любой нужной глубины.

Пункт к уже добавленной кнопке ставим отдельным вызовом:

$APPLICATION->AddPanelButtonMenu('vendor_export', [
    'TEXT'        => 'Выгрузить всё',
    'SORT'        => 20,
    'ACTION'      => 'BX.Vendor.exportAll()',
    'RESORT_MENU' => true,   // пересортировать пункты по индексу
]);

Первым аргументом идёт ID кнопки, а не её подпись. Без ключа RESORT_MENU новый пункт встанет в конец списка, каким бы маленьким ни было значение SORT.

Замена штатной кнопки

Штатную кнопку замещаем вторым аргументом:

// $bReplace: заменить кнопку с таким же ID вместо добавления новой
$APPLICATION->AddPanelButton($arButton, true);

Замена ищет кнопку по ключу ID, поэтому идентификатор штатной кнопки нужно знать точно. Порядок кнопок на панели задаёт MAIN_SORT, порядок внутри одной группы - SORT.

Права и место для кода

Показываем кнопку только тому, кому инструмент разрешён:

global $APPLICATION;
if ($APPLICATION->GetGroupRight('catalog') < 'W') { // права группы на модуль
    return;
}

Сама кнопка прав не выдаёт: страницу за HREF проверяем отдельно, иначе адрес останется доступным по прямой ссылке. Уровень права возвращается буквой, поэтому сравнение идёт со строкой, а не с числом.

Добавление вешаем на раннее событие страницы:

/local/php_interface/init.php
\Bitrix\Main\EventManager::getInstance()->addEventHandlerCompatible(
    'main', 'OnBeforeProlog', 'vendorAddPanelButton'
);

Событие OnBeforeProlog отрабатывает до сборки страницы, и кнопка успевает попасть на панель на любом разделе сайта. Вызов из шаблона или компонента тоже допустим, но такая кнопка теряется при смене шаблона сайта.

Типичные проблемы

Код с AddPanelButton запущен отдельным файлом в корне, кнопки нет.

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

Панель на витрине не показывается совсем.

В шаблоне сайта нет вызова ShowPanel после открывающего тега body. Кнопки при этом добавляются штатно, но выводить их некуда.

Панель уехала под шапку сайта и не нажимается.

Фиксированная шапка шаблона рисуется поверх панели и перехватывает клики. Панели задают позиционирование и слой выше шапки, а содержимое сдвигают вниз.

Вторая кнопка с тем же идентификатором не появилась.

Уникальность кнопки платформа держит по ключу ID. Повторное добавление без флага замены просто игнорируется.

Пункт меню встал в конец, хотя индекс сортировки меньше.

Метод AddPanelButtonMenu дописывает пункт в конец списка. Пересортировку по индексу включает ключ RESORT_MENU.

Частые вопросы

Как добавить кнопку в административную панель Bitrix?

Вызовом $APPLICATION->AddPanelButton с массивом описания. Обязательны ключи ID и TEXT, переход задаёт HREF. Вызов делают на хите публичной страницы: из шаблона, компонента или обработчика события.

Где применять метод AddPanelButton, в каком файле?

Надёжнее всего в обработчике OnBeforeProlog, зарегистрированном в файле /local/php_interface/init.php. Отдельный php-файл в корне сайта не годится: он выполняется без пролога, и панель там не строится.

Можно ли заменить штатную кнопку панели своей?

Да, вторым аргументом метода передают true. Кнопка для замены ищется по ключу ID, поэтому идентификатор штатной кнопки нужно знать точно, а не подбирать по подписи.

Как добавить пункт в меню уже существующей кнопки?

Методом $APPLICATION->AddPanelButtonMenu, первым аргументом идёт идентификатор кнопки. Чтобы пункт встал по своему индексу сортировки, в массиве пункта ставят RESORT_MENU => true.

Видит ли кнопку менеджер без прав администратора?

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

Смежное

Первоисточник