Компонент в Битрикс: три способа подключить на страницу

Вы вставили вызов компонента в файл страницы, а на сайте пусто. Или блок появился, но после правки параметров выглядит по-старому. В Битриксе так выходит по одной из трёх причин: вызов стоит не там, шаблон лежит не в том каталоге или правки прячет кеш. Разберём это на задаче «три последние новости на главной» и сравним три способа подключения.

Задача и что нужно до начала

Блок «Последние новости» на главной: три записи из инфоблока¹, у каждой дата и ссылка на материал. Код написан для «1С-Битрикс: Управление сайтом» (главный модуль 23.x и новее) и PHP 8.x. Сам вызов IncludeComponent старый и стабильный, а вот имена параметров конкретного компонента сверяйте со своей версией: их полный список лежит в файле .parameters.php в папке компонента.

Понадобятся доступ к файлам сайта и ID инфоблока новостей. Его видно в списке инфоблоков в разделе «Контент → Инфоблоки» админки.

Базовый вызов в файле страницы

Вызов ставят между подключением шапки и подвала. Фрагмент файла /index.php:

<?php
require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php');
$APPLICATION->SetTitle('Главная');

$APPLICATION->IncludeComponent(
    'bitrix:news.list',
    'latest_news',
    array(
        'IBLOCK_TYPE' => 'news',
        'IBLOCK_ID' => '3', // подставьте ID своего инфоблока
        'NEWS_COUNT' => '3',
        'SORT_BY1' => 'ACTIVE_FROM',
        'SORT_ORDER1' => 'DESC',
        'SORT_BY2' => 'SORT',
        'SORT_ORDER2' => 'ASC',
        'ACTIVE_DATE_FORMAT' => 'd.m.Y',
        'DETAIL_URL' => '/news/#ELEMENT_CODE#/',
        'CHECK_DATES' => 'Y',
        'SET_TITLE' => 'N',
        'CACHE_TYPE' => 'A',
        'CACHE_TIME' => '3600',
    ),
    false
);

require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php');

Второй аргумент, latest_news, это имя шаблона; для стандартного пишут .default. Последний аргумент false говорит, что компонент не вложен в другой. SET_TITLE = N нужен, чтобы компонент не затёр заголовок из SetTitle: при значении Y он подставит название инфоблока. CACHE_TYPE = A включает кеш, если он разрешён в настройках сайта, а CACHE_TIME задаётся в секундах.

Шаблон: куда класть и как Битрикс его находит

Шаблон latest_news Битрикс ищет сначала в папке текущего шаблона сайта, затем в .default, затем среди шаблонов самого компонента. Каталог /local приоритетнее /bitrix. Положите файл сюда: /local/templates/.default/components/bitrix/news.list/latest_news/template.php. Проще всего скопировать стандартный шаблон: в контекстном меню компонента есть пункт копирования шаблона. Минимальная версия:

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) {
    die();
}
/** @var array $arResult */
?>
<ul class='latest-news'>
<?php foreach ($arResult['ITEMS'] as $arItem):
    // Кнопка быстрой правки элемента в режиме правки
    $this->AddEditAction(
        $arItem['ID'],
        $arItem['EDIT_LINK'],
        CIBlock::GetArrayByID($arItem['IBLOCK_ID'], 'ELEMENT_EDIT')
    );
?>
    <li id='<?= $this->GetEditAreaId($arItem['ID']) ?>'>
        <time><?= htmlspecialcharsbx($arItem['DISPLAY_ACTIVE_FROM']) ?></time>
        <a href='<?= htmlspecialcharsbx($arItem['DETAIL_PAGE_URL']) ?>'><?= htmlspecialcharsbx($arItem['NAME']) ?></a>
    </li>
<?php endforeach; ?>
</ul>

Три способа подключить компонент

Визуальный редактор

В разделе «Структура сайта» откройте страницу на редактирование. В редакторе есть панель компонентов: выбираете news.list, задаёте параметры в диалоге, и редактор записывает в файл тот же вызов IncludeComponent. Выигрыш: не нужно помнить имена параметров. Цена: правка идёт прямо на боевом сайте без истории изменений, а при сохранении редактор может поменять разметку вокруг вызова. PHP-страницы надёжнее править в режиме исходного кода.

Вручную в файле страницы

Вызов лежит в файле, который можно хранить в git, ревьюить и выкатывать. Цена: имена параметров придётся брать из .parameters.php или документации. Удобный ход: настройте блок в редакторе на тестовой странице, скопируйте готовый вызов в репозиторий.

В шаблоне сайта

Если блок нужен на каждой странице (меню, контакты в подвале), вызов ставят в header.php или footer.php шаблона сайта. Для условия «только на главной» подходит проверка $APPLICATION->GetCurPage(false) === '/'. Цена: ошибка здесь роняет все страницы сразу, а компонент отрабатывает на каждом запросе, так что без кеша вы получите лишнюю нагрузку на базу по всему сайту.

Вызов компонента отвечает на вопрос «что показать», шаблон на вопрос «как». Как только в шаблон попадает выбор инфоблока или числа записей, блок перестаёт переиспользоваться.

Когда что выбирать

• Блок нужен на одной странице и у файла есть история в git: вызов вручную в файле страницы.
• Репозитория нет, блок правит контент-менеджер: визуальный редактор, но сначала сохраните копию файла.
• Блок должен быть на каждой странице: шаблон сайта, обязательно с кешем и, если нужно, с условием по адресу.

Критерий простой: сколько страниц затронет ошибка и можно ли откатить файл за минуту.

Что ломается

• Пустое место. Проверьте ID и тип инфоблока, активность элементов, даты активности (при CHECK_DATES = Y запись с будущей датой скрыта) и права вашей группы на чтение инфоблока.
• Правки не видны. Это кеш: на время отладки поставьте CACHE_TYPE = N или сбросьте кеш в «Настройки → Производительность».
• Заголовок страницы стал названием инфоблока. Вы не отключили SET_TITLE.
• Ошибка «Call to a member function IncludeComponent() on null». Вызов стоит до подключения header.php, объект $APPLICATION ещё не создан.
• Шаблон не подхватился. Имя папки не совпало с третьим аргументом; на Linux регистр важен.
• Правки в /bitrix/components/bitrix/ пропали после обновления. Платформа перезаписывает эти файлы, держите свои изменения в /local.

Что делать дальше

1. Если шаблон лежит в /bitrix/templates, перенесите его в /local/templates, чтобы обновления его не трогали.
2. Включите кеш и проверьте в отладочной информации о запросах вашей версии, что страница больше не обращается к инфоблоку за новостями. Точное название раздела сверьте в документации.
3. Если нужен раздел новостей с детальными страницами и ЧПУ, это уже комплексный компонент bitrix:news и правила в urlrewrite.php. Это отдельная тема, здесь не разбираем.

¹ Инфоблок: хранилище однотипных элементов (новости, товары, вакансии) со своим набором полей и свойств. Компоненты читают данные именно оттуда.