Разработка кастомных административных страниц 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']));
}

// В JS (при использовании 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 недели.