Кастомизация шаблона Битрикс: четыре приёма и их цена

Заказчик просит три правки в карточке новости: добавить метку, убрать дату, сменить класс обёртки. Вы открываете /bitrix/components/bitrix/news.list/templates/.default/template.php, правите, всё работает. Через пару месяцев платформа обновляется, и штатный файл возвращается к исходному виду. Каталог /bitrix/ принадлежит вендору, и любые правки в нём живут до первого обновления. Ниже: где хранить свои изменения и как выбрать глубину вмешательства. Материал написан для «1С-Битрикс: Управление сайтом» актуальных веток (23.x и новее), PHP 8.x.

Где лежит шаблон и кто его выбирает

Битрикс ищет шаблон компонента по цепочке путей, и /local/ в ней стоит раньше /bitrix/. Копия в /local/ перекрывает штатный шаблон, а оригинал остаётся нетронутым. Внутри /local/ приоритет такой: сначала папка текущего шаблона сайта, затем .default. Это даёт два места для копии:

• /local/templates/.default/components/bitrix/news.list/cards/ - шаблон виден из любого шаблона сайта;
• /local/templates/main/components/bitrix/news.list/cards/ - только внутри шаблона сайта main.

Имя папки (cards) вы передаёте вторым аргументом в IncludeComponent. Если назвать копию .default, она заменит штатный шаблон везде, где имя не указано явно. Для точечной правки это опасно: заденете страницы, о которых забыли.

Четыре подхода и цена каждого

Всё, что лежит в /bitrix/, принадлежит вендору. Всё, что лежит в /local/, принадлежит вам и вашему git.

Как это выглядит в коде

Копия шаблона

Копируйте папку шаблона целиком: вместе с lang/ и .parameters.php. Без них пропадут языковые строки и настройки шаблона в визуальном редакторе.

/local/templates/.default/components/bitrix/news.list/cards/
    template.php
    result_modifier.php
    style.css
    lang/ru/template.php

Файлы style.css и script.js в папке шаблона компонента подключаются автоматически, а template_styles.css в папке шаблона сайта подхватывается через ShowHead(). Вызов с новым шаблоном:

<?php
$APPLICATION->IncludeComponent(
    'bitrix:news.list',
    'cards', // имя папки вашего шаблона
    [
        'IBLOCK_ID' => 5, // подставьте свой ID инфоблока
        'NEWS_COUNT' => 12,
        'PROPERTY_CODE' => ['LABEL'],
        'CACHE_TYPE' => 'A',
        'CACHE_TIME' => 3600,
    ]
);
?>

Данные в result_modifier.php

Файл выполняется перед template.php и получает готовый $arResult. Задача: превратить значение свойства LABEL в CSS-модификатор, чтобы шаблон не содержал условий.

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

// Допустимые метки; всё остальное игнорируем
$allowedLabels = ['hit', 'new', 'sale'];

foreach ($arResult['ITEMS'] as &$item) {
    // LABEL: одиночное строковое свойство из PROPERTY_CODE
    $label = (string)($item['PROPERTIES']['LABEL']['VALUE'] ?? '');
    $item['CSS_MOD'] = in_array($label, $allowedLabels, true) ? 'card--' . $label : '';
}
unset($item);

Если значение нужно в component_epilog.php, его надо добавить в ключи кеша результата методом SetResultCacheKeys объекта компонента. Сигнатуру сверьте с документацией вашей версии.

Вёрстка без потери кнопок правки

Разработчики часто выбрасывают из шаблона вызовы AddEditAction и GetEditAreaId, потому что «они ничего не выводят». Выводят: из-за них у блока в режиме правки появляются кнопки редактирования элемента. Оставьте их при переработке разметки:

<?php
$this->AddEditAction($item['ID'], $item['EDIT_LINK'], CIBlock::GetArrayByID($item['IBLOCK_ID'], 'ELEMENT_EDIT'));
?>
<div class='card <?= htmlspecialcharsbx($item['CSS_MOD']) ?>' id='<?= $this->GetEditAreaId($item['ID']) ?>'>

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

• Нужно только поменять вид, а разметка устраивает - CSS поверх штатного шаблона.
• Нужна другая разметка на тех же данных - копия и template.php.
• Нужны данные, которых нет в $arResult, но выборка из инфоблока уже подходит - копия и result_modifier.php.
• Нужна другая выборка: свой запрос, сортировка, склейка нескольких инфоблоков - свой компонент.

Критерий один: на каком слое возникает потребность. Вид - CSS, разметка - шаблон, данные - модификатор, источник данных - компонент. Поднимайтесь выше только когда нижний слой не справляется.

Что ломается

• Правка не видна. Компонент закеширован. Сбросьте кеш в админке или откройте страницу под администратором с ?clear_cache=Y. Если включён композитный кеш, он может отдавать старую страницу. Его сброс - отдельная тема.
• Подключается не тот шаблон. Копия в папке шаблона сайта перекрывает копию в .default. Проверьте оба места.
• Запрос к базе в цикле внутри result_modifier.php. С кешем компонента это незаметно, при CACHE_TYPE равном N число запросов растёт вместе с числом элементов.
• Пропала проверка B_PROLOG_INCLUDED в начале файла. Без неё файл можно вызвать напрямую по URL.
• Тексты зашиты в разметку. Выносите их в lang/ru/template.php и читайте через GetMessage, иначе мультиязычный сайт придётся переписывать.
• Копия шаблона отстала от штатного. После обновления в оригинале могли появиться исправления, а в вашей копии их нет.

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

Положите /local/ под git, а /bitrix/ оставьте за пределами репозитория. После крупного обновления сравнивайте копию со штатным шаблоном, чтобы увидеть, что вы пропустили:

diff -ru bitrix/components/bitrix/news.list/templates/.default local/templates/.default/components/bitrix/news.list/cards

Затем замерьте время генерации страницы с выключенным и включённым кешем компонента: так видно, во что обходится ваш result_modifier.php.

Пояснение. Шаблон сайта - папка в /local/templates/ с header.php, footer.php и template_styles.css, каркас страницы. Шаблон компонента - папка внутри components/ с template.php, она отвечает за вывод одного блока, например списка новостей.