Розробка комплексного компонента 1С-Бітрікс

Розробка комплексного компонента 1С-Бітрікс

Комплексний компонент — це компонент, який управляє набором дочірніх компонентів, визначаючи їхній склад залежно від URL та точки монтування на сторінці. Саме комплексні компоненти реалізують розділи каталогу, блоги, особистий кабінет — коли на одній URL-адресі може бути список, на іншій — детальна сторінка, на третій — форма оформлення. Без розуміння механіки комплексних компонентів неможливо правильно реалізувати багатосторінковий функціонал на Бітрікс.

Чим комплексний компонент відрізняється від звичайного

Звичайний компонент (bitrix:news.detail) виводить один конкретний блок. Комплексний (bitrix:news) — точка монтування розділу. Він сам вирішує, який дочірній компонент викликати: якщо URL /news/ — список новин, якщо /news/title-news/ — детальна сторінка.

Комплексний компонент зв'язує URL з дочірніми компонентами через механізм SEF-URL (Search Engine Friendly) та файл page_templates.php.

Структура комплексного компонента

/local/components/custom/my.section/
├── .description.php
├── .parameters.php
├── component.php              # диспетчер: визначає тип сторінки
├── page_templates.php         # маппінг URL-шаблонів на дочірні компоненти
├── templates/
│   └── .default/
│       ├── template.php       # шаблон обгортки (заголовок, навігація)
│       └── page_templates/    # шаблони дочірніх компонентів
│           ├── list.php
│           └── detail.php

page_templates.php: маппінг URL

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();

$arSefTemplates = [
    // список
    'list'   => '',
    // детальна сторінка
    'detail' => '#ELEMENT_CODE#/',
    // розділ
    'section' => '#SECTION_CODE#/',
    // пошук
    'search' => 'search/',
];

Бітрікс порівнює поточну URL-адресу з цими шаблонами та визначає тип сторінки ($arCurrentValues['PAGE_ELEMENT_TYPE']).

component.php комплексного компонента: диспетчер

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();

/** @var CBitrixComponent $this */

// Ініціалізація SEF
$this->setFrameMode(true);

if ($arParams['SEF_MODE'] === 'Y') {
    $arSEFUrlTemplates = [];
    $arDefaultSEFUrlTemplates = [
        'list'   => '',
        'detail' => '#ELEMENT_CODE#/',
        'section' => '#SECTION_CODE#/',
    ];
    // ... парсинг поточної URL

    // Визначаємо тип сторінки
    $page = 'list'; // за замовчуванням

    if (isset($arVariables['ELEMENT_CODE']) && $arVariables['ELEMENT_CODE']) {
        $page = 'detail';
    } elseif (isset($arVariables['SECTION_CODE']) && $arVariables['SECTION_CODE']) {
        $page = 'section';
    }
} else {
    // Параметричний режим (не SEF)
    $page = $arParams['PAGE_ELEMENT_TYPE'];
}

// Підключаємо потрібний шаблон сторінки
$this->includePageTemplate($page);

Дочірні компоненти в шаблоні

Файл templates/.default/page_templates/list.php викликає дочірній компонент списку:

<?php
// templates/.default/page_templates/list.php
$APPLICATION->IncludeComponent('custom:my.section.list', '', [
    'IBLOCK_ID'     => $arParams['IBLOCK_ID'],
    'SECTION_ID'    => $arResult['VARIABLES']['SECTION_ID'] ?? 0,
    'SECTION_CODE'  => $arResult['VARIABLES']['SECTION_CODE'] ?? '',
    'PAGE_SIZE'     => $arParams['PAGE_SIZE'],
    'CACHE_TIME'    => $arParams['CACHE_TIME'],
    'SET_TITLE'     => 'Y',
    'SET_BROWSER_TITLE' => 'Y',
], $component);

Параметр $component (посилання на батьківський компонент) — критичний. Без нього кеш дочірнього компонента буде незалежним від батьківського, що порушує інвалідацію.

Параметри комплексного компонента

Комплексний компонент об'єднує параметри всіх дочірніх — налаштування пагінації, кеширування, SEF-шаблонів:

// .parameters.php
$arComponentParameters = [
    'GROUPS' => [...],
    'PARAMETERS' => [
        'SEF_MODE' => [
            'NAME'    => 'Режим ЧПУ',
            'TYPE'    => 'CHECKBOX',
            'DEFAULT' => 'Y',
        ],
        'SEF_FOLDER' => [
            'NAME'    => 'Папка для ЧПУ',
            'TYPE'    => 'STRING',
            'DEFAULT' => '/news/',
        ],
        'IBLOCK_ID' => ['...'],
        'PAGE_SIZE' => [
            'NAME'    => 'Елементів на сторінці',
            'TYPE'    => 'STRING',
            'DEFAULT' => '12',
        ],
        'DETAIL_URL'  => ['DEFAULT' => '#SITE_DIR##SECTION_CODE#/#ELEMENT_CODE#/'],
        'SECTION_URL' => ['DEFAULT' => '#SITE_DIR##SECTION_CODE#/'],
        'INDEX_URL'   => ['DEFAULT' => '#SITE_DIR#'],
        // ... SEF-шаблони URL
    ],
];

Обробка помилок і 404

Якщо елемент або розділ не знайдено, комплексний компонент повинен повернути коректну помилку 404:

// У дочернему компоненті detail
if (!$element) {
    LocalRedirect(SITE_DIR . '404.php');
    // або:
    \Bitrix\Main\Response\HttpResponse::create()->setStatus('404 Not Found')->send();
    require(Application::getDocumentRoot() . '/404.php');
    die();
}

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

Якщо розділ вимагає авторизації (особистий кабінет, B2B), комплексний компонент перевіряє права до виклику дочірніх:

// У component.php
global $USER;
if (!$USER->IsAuthorized()) {
    LocalRedirect(SITE_DIR . 'login/?backurl=' . urlencode($APPLICATION->GetCurPage()));
    die();
}
// Перевірка групи користувача
if (!$USER->IsInGroup($arParams['ALLOWED_GROUP_ID'])) {
    $APPLICATION->SetStatus('403 Forbidden');
    $APPLICATION->RestartBuffer();
    require($_SERVER['DOCUMENT_ROOT'] . '/403.php');
    die();
}

Кеширування в комплексних компонентах

Комплексний компонент сам по собі кешується рідко (логіка диспетчера дешева). Кешуються дочірні. Важливо, що ключ кеша дочірнього компонента включає змінні з URL (ELEMENT_CODE, SECTION_CODE), інакше всі сторінки показуватимуть один і той же кешований результат.

У класі дочірнього компонента:

$cacheId = serialize([
    $arParams['IBLOCK_ID'],
    $arParams['ELEMENT_CODE'],
    $USER->GetGroups(), // різні групи бачать різний контент
    LANGUAGE_ID,
]);
if ($this->StartResultCache($arParams['CACHE_TIME'], $cacheId)) {
    // ...
}

Тестування комплексного компонента

Перед здачею — перевірювальний список:

• Усі сторінки (список, деталь, розділ) працюють у режимах SEF та параметрів
• 404 повертається при неіснуючому елементі/розділі
• Кеш інвалідується при оновленні елемента в адміністративній панелі
• Компонент працює на всіх сайтах в багатосайтовій установці
• Хлібні крошки коректно відображаються на всіх типах сторінок

Строки

Комплексний компонент — правильна архітектура для будь-якого розділу сайту з кількома типами сторінок. Це не перестраховка, а необхідна умова для сайтів, які планують підтримку та розвиток.