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

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

Кастомна сторінка в адміністративній частині Бітрікс — це не просто HTML-файл, кинутий у /bitrix/admin/. Це контролер, який перевіряє права, приймає параметри, виконує бізнес-логіку та рендерить результат через шаблон. D7 надає для цього механізм \Bitrix\Main\Engine\Controller з маршрутизацією, перевіркою CSRF та сесіями — без необхідності писати власний велосипед.

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

Класичний admin-файл (/bitrix/admin/my_page.php) — найпростіший варіант, придатний для допоміжних інструментів:

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

use Bitrix\Main\Loader;
use Bitrix\Main\Localization\Loc;

Loader::includeModule('my.module');

// Перевірка прав
if (!$APPLICATION->IsAdminPage() || !\CMain::GetUserRight("main") >= "S") {
    $APPLICATION->AuthForm("Доступ заборонено");
}

$APPLICATION->SetTitle("Мій інструмент");

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

// Виведення вмісту сторінки
?>
<form method="post" action="<?= $APPLICATION->GetCurPage() ?>">
    <?= bitrix_sessid_post() ?>
    <!-- поля форми -->
    <input type="submit" value="Виконати">
</form>
<?php
require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/modules/main/include/epilog_admin.php");

MVC через Controller — правильний шлях для сторінок з логікою:

namespace MyProject\Controllers;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;

class ReportController extends Controller
{
    public function configureActions(): array
    {
        return [
            'getReport' => [
                'prefilters' => [
                    new ActionFilter\Authentication(),
                    new ActionFilter\HttpMethod(['GET', 'POST']),
                    new ActionFilter\Csrf(),
                ],
            ],
        ];
    }

    public function getReportAction(int $periodDays = 30): array
    {
        // права перевіряються у prefilters
        $data = \MyProject\Services\ReportService::build($periodDays);
        return ['data' => $data, 'total' => count($data)];
    }
}

Маршрутизація в Бітрікс

Для контролерів потрібна реєстрація маршрутів. У /local/php_interface/init.php або в методі модуля:

\Bitrix\Main\Routing\Router::getInstance()->add(
    '/local/my-tool/report/',
    ['controller' => '\MyProject\Controllers\ReportController', 'action' => 'getReport'],
    'GET'
);

Альтернатива — UrlManager у конфізі модуля або файл /local/routes.php (Бітрікс 22+, потрібно увімкнути в налаштуваннях ядра).

Кастомна сторінка публічної частини

Для публічних сторінок — стандартний механізм компонентів. Але іноді потрібна сторінка поза компонентною системою: утиліта, колбек від платіжного шлюзу, вебхук. Тоді створюється файл сторінки з підключенням ядра:

<?php
define('STOP_STATISTICS', true);   // не пишемо в статистику
define('NO_AGENT_STATISTIC', true); // не запускаємо агентів
define('NOT_CHECK_PERMISSIONS', true); // вимикаємо перевірку прав Бітрікс
define('NO_LANG_FILES', false);

require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php');
// тепер доступні всі класи Бітрікс

// Вся логіка через D7
$request = \Bitrix\Main\Application::getInstance()->getContext()->getRequest();
if (!$request->isPost()) {
    http_response_code(405);
    exit;
}

// ... обробка

Посторінкова навігація D7

Для сторінок зі списками даних:

use Bitrix\Main\UI\PageNavigation;

$nav = new PageNavigation('page');
$nav->allowAllRecords(false)
    ->setPageSize(20)
    ->initFromUri();

$result = \MyProject\Storage\OrderLogTable::getList([
    'select'     => ['*'],
    'order'      => ['ID' => 'DESC'],
    'count_total' => true,
    'offset'     => $nav->getOffset(),
    'limit'      => $nav->getLimit(),
]);

$nav->setRecordCount($result->getCount());
// Рендер постранички через $nav->getPageNavString(...)

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

Перевірка прав на основі груп користувачів:

global $USER;

if (!$USER->IsAdmin() && !$USER->IsInGroup([MANAGER_GROUP_ID])) {
    LocalRedirect('/access-denied/');
}

Для модульних сторінок — через API прав доступу Бітрікс:

if (\CModule::IncludeModule('my.module')) {
    $rights = \CMyModule::GetCurrentUserPermissions();
    if ($rights < MY_MODULE_PERMISSION_WRITE) {
        ShowError('Недостатньо прав');
        exit;
    }
}

Інтеграція з UI Бітрікс: гриди та фільтри

Для адміністративних сторінок зі списками — готовий UI: CAdminList, CAdminFilter. Це забезпечує консистентний з ядром вигляд:

$adminList = new CAdminList('my_list', $by, $order);
$adminList->AddColumn(['id' => 'ID', 'content' => 'ID', 'sort' => 'ID']);
$adminList->AddColumn(['id' => 'NAME', 'content' => 'Назва', 'sort' => 'NAME']);

while ($row = $result->fetch()) {
    $adminRow = $adminList->AddRow($row['ID'], $row);
    $adminRow->AddActions([
        ['text' => 'Змінити', 'href' => '/bitrix/admin/my_edit.php?ID=' . $row['ID']],
        ['text' => 'Видалити', 'action' => "if(confirm('Видалити?')) window.location='...';"],
    ]);
}
$adminList->DisplayList();

Терміни

Кастомна сторінка на D7 — це не заміна компонентній системі. Це інструмент для задач, які не вкладаються в стандартну модель: інструменти адміністратора, інтерфейси імпорту, дашборди з агрегованими даними. Написані правильно, вони не конфліктують з ядром при оновленнях.