Розробка кастомних адміністративних сторінок 1С-Бітрікс

Розроблення кастомних адміністративних сторінок в 1С-Бітрікс

Стандартний адміністративний розділ охоплює типові завдання — управління каталогом, замовленнями, користувачами. Але як тільки з'являється специфіка бізнесу — ручна синхронізація остатків зі зовнішної системи, масове оновлення цін за формулою, управління налаштуваннями інтеграцій — потрібні власні адміністративні сторінки. Розробляти їх в /bitrix/admin/ напряму не можна (оновлення сотруть зміни), правильний шлях — /local/.

Де розміщувати кастомні адміністративні сторінки

Файли кастомних сторінок розміщуються в /local/admin/. Бітрікс автоматично включає цей шлях в пошук адміністративних сторінок. Сторінка стає доступна по адресі /bitrix/admin/my_page.php якщо файл лежить в /local/admin/my_page.php.

Альтернатива — створити сторінку як компонент в /local/components/ та підключити через обгортку. Це переважний підхід для складних інтерфейсів.

Структура мінімальної адміністративної сторінки

<?php
// /local/admin/my_custom_page.php

require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_admin_before.php');

// Перевірка прав
$APPLICATION->SetTitle('Моя сторінка');
if (!$USER->IsAdmin() && !$USER->CanDoOperation('edit_php')) {
    $APPLICATION->AuthForm('Немає доступу');
}

require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_admin_after.php');

// Контент сторінки
?>
<div class="adm-content-wrap">
    <!-- HTML інтерфейсу -->
</div>
<?php
require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/epilog_admin.php');

Три обов'язкові інклюди формують правильну обгортку: шапка, навігація, підвал адміністративного розділу. Без них сторінка відкриється без оформлення.

Використання адміністративних хелперів Бітрікс

Бітрікс надає набір класів для побудови стандартних адміністративних UI-елементів. Використання цих класів дає нативний вигляд та рятує від верстки.

CAdminList — таблиця з сортуванням, пагінацією та фільтром:

use Bitrix\Main\UI\Filter\Options as FilterOptions;

$oList = new CAdminList('my_list_id');

// Додати колонки
$lAdmin->AddHeaders([
    ['id' => 'ID', 'content' => 'ID', 'sort' => 'ID'],
    ['id' => 'NAME', 'content' => 'Назва', 'sort' => 'NAME'],
    ['id' => 'DATE', 'content' => 'Дата'],
]);

// Заповнити рядками
while ($row = $rsData->Fetch()) {
    $oRow = &$oList->AddRow('ID_' . $row['ID'], $row);
    $oRow->AddActions([
        ['TEXT' => 'Змінити', 'ONCLICK' => "jsUtils.Redirect([], 'my_edit.php?ID=" . $row['ID'] . "')"],
        ['TEXT' => 'Видалити', 'ACTION' => $oList->ActionDoGroup($row['ID'], 'delete')],
    ]);
}

$oList->DisplayList();

CAdminForm — форма редагування з вкладками:

$oTabControl = new CAdminTabControl('tabControl', [
    ['DIV' => 'tab1', 'TAB' => 'Основне', 'ICON' => 'main_user_edit'],
    ['DIV' => 'tab2', 'TAB' => 'Додатково'],
]);

$oTabControl->Begin();
$oTabControl->BeginNextTab();
// поля першої вкладки
$oTabControl->BeginNextTab();
// поля другої вкладки
$oTabControl->Buttons(['btnSave' => true, 'btnApply' => true, 'btnCancel' => true]);
$oTabControl->End();

Додавання сторінки в меню адміністративного розділу

Сторінка повинна бути доступна з меню, а не тільки по прямому URL. Реєстрація через обробник події в /local/php_interface/init.php:

AddEventHandler('main', 'OnBuildGlobalMenu', function(&$globalMenu, &$moduleMenu) {
    $moduleMenu[] = [
        'parent_menu' => 'global_menu_services', // розділ меню
        'sort'        => 500,
        'text'        => 'Синхронізація',
        'title'       => 'Управління синхронізацією із зовнішною системою',
        'url'         => 'my_custom_page.php',
        'icon'        => 'main_menu_tasks',      // CSS-клас іконки
        'page_icon'   => 'main_page_icon',
        'more_url'    => ['my_custom_page.php', 'my_custom_edit.php'],
    ];
});

Параметр more_url потрібний, щоб пункт меню залишався активним при переході на пов'язані сторінки (наприклад, форму редагування).

Робота з даними: D7 vs старе API

Для кастомних сторінок рекомендується використовувати D7 ORM (\Bitrix\Main\ORM). Якщо дані зберігаються в власних таблицях — створюється клас сутності:

namespace Local\MyModule;

use Bitrix\Main\ORM\Data\DataManager;
use Bitrix\Main\ORM\Fields;

class MyEntityTable extends DataManager
{
    public static function getTableName(): string
    {
        return 'my_custom_table';
    }

    public static function getMap(): array
    {
        return [
            new Fields\IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new Fields\StringField('NAME', ['required' => true]),
            new Fields\DatetimeField('CREATED_AT'),
        ];
    }
}

Після цього MyEntityTable::getList(), ::add(), ::update(), ::delete() працюють через стандартний Бітрікс ORM.

Обробка форм та AJAX

Адміністративні сторінки Бітрікс традиційно використовують POST-форми з токеном CSRF (bitrix_sessid_post()). Для AJAX-запитів:

// Перевірка сесійного токена
if (!check_bitrix_sessid()) {
    die(json_encode(['error' => 'Invalid session']));
}

// У JavaScript (при використанні BX.ajax)
BX.ajax.runAction('local:my.action', {
    data: { param: value },
    sessid: BX.bitrix_sessid()
});

Для сучасних AJAX-інтерфейсів можна використовувати \Bitrix\Main\Engine\Controller з маршрутизацією через /.action.php — D7-підхід, рекомендований для нових розробок.

Права доступу до кастомних сторінок

Кастомна сторінка повинна перевіряти права самостійно. Варіанти:

• Перевірка $USER->IsAdmin() — тільки для сторінок, доступних виключно адміністраторам
• Перевірка $USER->CanDoOperation('назва_операції') — для гранулярного контролю
• Перевірка права на модуль: CModule::IncludeModule('main') && $USER->GetRights('mymodule') >= 'W'

Якщо сторінка повинна бути доступна певній групі — краще створити власний модуль з реєстрацією прав через RegisterModuleDependences.

Типові завдання, для яких створюються кастомні сторінки

• Панель управління синхронізацією з 1С або зовнішніми API (ручний запуск, журнал останніх операцій)
• Масове редагування товарів за нестандартними критеріями
• Дашборд з аналітикою на основі даних з кількох модулів
• Управління налаштуваннями інтеграцій (ключі API, вебхуки, маппінг полів)
• Інструменти міграції контенту між оточеннями

Часові рамки виконання

Проста кастомна сторінка з формою та CRUD-таблицею — 1–2 дні. Багатосторінковий розділ з фільтрами, AJAX, правами доступу та власною таблицею в БД — 3–5 днів. Повнофункціональний кастомний модуль з інтеграцією в меню, правами та подіями — 1–2 тижні.