Кастомизация шаблона компонента: копирование в шаблон сайта

Стандартный шаблон компонента редко устраивает без изменений: чужая вёрстка, другие классы, отсутствие нужных блоков разметки. Правка файлов прямо в /bitrix/components/ — самый быстрый способ испортить сайт: правки исчезнут при первом же обновлении модуля.

Правильный путь — копирование шаблона компонента в свой шаблон сайта. Разберём механизм, порядок поиска файлов ядром и типичные ошибки при переносе.

Где искать оригинал

Штатные шаблоны компонентов лежат в структуре ядра:

/bitrix/components/bitrix/news.list/templates/.default/
    template.php
    style.css
    script.js

Имя .default — это код шаблона по умолчанию. У некоторых компонентов есть и другие готовые шаблоны, каждый в своей папке.

Куда копировать

Структура папки назначения повторяет путь компонента, только относительно шаблона сайта:

/local/templates/main/components/bitrix/news.list/main/
    template.php
    style.css
    script.js

Здесь main — уже имя вашего нового шаблона компонента, а не оригинального. Именно оно указывается вторым параметром при вызове:

<$APPLICATION->IncludeComponent(
    'bitrix:news.list',
    'main',   // ваш шаблон, а не .default
    [
        'IBLOCK_TYPE' => 'content',
        'IBLOCK_ID'   => 5,
    ]
);?>

Порядок поиска шаблонов

Битрикс ищет шаблон компонента по цепочке приоритетов:

1. /local/templates/{ваш_шаблон}/components/{namespace}/{компонент}/{имя}/
2. /bitrix/templates/{ваш_шаблон}/components/{namespace}/{компонент}/{имя}/
3. /bitrix/components/{namespace}/{компонент}/templates/{имя}/

Если файл найден на первом уровне — используется он, дальше поиск не идёт. Это позволяет переопределить только нужные файлы: например, оставить script.js оригинальным, а template.php скопировать и изменить — Битрикс возьмёт первый файл из своего шаблона, а второй унаследует из ядра, если он не был скопирован.

Что не стоит менять

При копировании шаблона логику компонента трогать не нужно — она находится не здесь. template.php отвечает только за вывод уже готовых данных из $arResult:

<?php
// template.php — только вывод, без логики выборки
foreach ($arResult['ITEMS'] as $item) {
    ?>
    <article class="news-card">
        <h3><?= $item['NAME'] ?></h3>
        <p><?= $item['PREVIEW_TEXT'] ?></p>
    </article>
    <?php
}

Если стандартной структуры $arResult не хватает — например, нужно досчитать поле, которого нет в выдаче компонента, — для этого существует отдельный файл result_modifier.php, выполняющийся до вывода шаблона и предназначенный именно для таких доработок.

Стили и скрипты шаблона

Файлы style.css и script.js внутри папки шаблона компонента подключаются автоматически — так же, как аналогичные файлы в корне шаблона сайта. Отдельно прописывать их подключение не требуется: они попадают на страницу сами, по факту вывода компонента.

Частые ошибки

• Правки вносятся в оригинал в /bitrix/components/. Исчезают при обновлении.
• Скопирован не тот файл. Например, скопировали только template.php, забыв про style.css, — стили остаются от оригинального шаблона.
• В скопированный шаблон вписана логика выборки данных. Такой код правильнее выносить в result_modifier.php.
• Имя шаблона не совпадает между вызовом компонента и названием папки — компонент тихо возвращается к оригинальному внешнему виду.

Итог

Кастомизация шаблона компонента — это копирование нужных файлов из /bitrix/components/ в структуру своего шаблона сайта с сохранением того же относительного пути. Логика самого компонента при этом не трогается, а вывод данных полностью переходит под контроль вёрстки проекта — и переживает любое обновление ядра.