Шаблон компонента: логика и вёрстка

Шаблон компонента отвечает за то, как данные превращаются в HTML. Грамотная структура файлов шаблона позволяет дорабатывать вывод без правки логики компонента и без потери изменений при обновлении.

Где лежат шаблоны компонента

У одного компонента может быть несколько шаблонов. Каждый — это папка внутри templates/. Битрикс ищет шаблон в порядке приоритета:

1. в шаблоне сайта: /local/templates/<site>/components/<namespace>/<component>/<template>/;
2. в каталоге самого компонента: /local/components/.../templates/<template>/;
3. в системном компоненте /bitrix/components/....

template.php — основная вёрстка

Файл template.php получает готовый массив $arResult и параметры $arParams. Его задача — только вывод:

<?php if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();?>
<ul class='widget'>
<?php foreach ($arResult['ITEMS'] as $item):?>
  <li><?=htmlspecialcharsbx($item['NAME'])?></li>
<?php endforeach;?>
</ul>

Первая строка с проверкой B_PROLOG_INCLUDED обязательна: она защищает шаблон от прямого вызова по URL в обход ядра. Внутри шаблона доступны служебные переменные: $component — объект компонента, $this — объект шаблона (CBitrixComponentTemplate), $templateFolder — путь к папке шаблона для формирования ссылок на картинки и ресурсы. Через $templateFolder удобно подключать изображения оформления, чтобы шаблон оставался переносимым между сайтами.

result_modifier.php — донастройка данных

Иногда нужно изменить $arResult под конкретный шаблон, не трогая компонент. Для этого служит result_modifier.php: он исполняется после компонента, но до template.php, и только если результат не взят из кэша.

foreach ($arResult['ITEMS'] as &$item) {
  $item['NAME_UPPER'] = ToUpper($item['NAME']);
}
unset($item);

Результат его работы попадает в кэш вместе с $arResult, поэтому тяжёлые преобразования тут выгодны — они выполняются один раз до следующего сброса кэша.

Ключевое преимущество result_modifier.php — он относится к шаблону, а не к компоненту. Это значит, что при кастомизации типового компонента вы можете дополнить его данные (посчитать скидку, подтянуть свойства, сгруппировать элементы), не копируя и не правя сам bitrix:catalog.section. Компонент обновляется вендором — ваш модификатор остаётся нетронутым. Это делает его основным инструментом безопасной доработки штатных компонентов.

component_epilog.php — код вне кэша

Эпилог шаблона исполняется всегда, даже при попадании в кэш. Это единственное место, где безопасно делать то, что должно работать при каждом запросе:

• установка заголовка страницы через $APPLICATION->SetTitle();
• добавление хлебных крошек $APPLICATION->AddChainItem();
• подключение внешних ресурсов, зависящих от текущего запроса.

Чтобы передать данные из компонента в эпилог, минуя кэш, их сохраняют в $this->arResultCacheKeys или через $arResult с явным исключением из кэша.

style.css и script.js шаблона

Если в папке шаблона есть style.css и script.js, Битрикс подключает их автоматически при выводе компонента. Это удобно: стили и скрипты живут рядом с вёрсткой.

Для более сложной работы с ресурсами применяют механизм расширений (\Bitrix\Main\UI\Extension::load()) и addExternalCss()/addExternalJs().

Языковые файлы и .parameters

Текстовые подписи в шаблоне выносят в языковые файлы lang/ru/template.php, чтобы поддерживать многоязычность и не хардкодить строки:

$MESS['WIDGET_MORE'] = 'Показать ещё';

В шаблоне их используют через функцию GetMessage('WIDGET_MORE'). Шаблон также может иметь собственный .parameters.php — дополнительные параметры, доступные только для этого шаблона, например число выводимых колонок или режим отображения.

Параметры шаблона отличаются от параметров компонента областью действия. Компонентные параметры влияют на выборку данных и объявляются в .parameters.php самого компонента. Параметры шаблона касаются только оформления и не должны менять состав $arResult. Такое разделение позволяет одному компоненту иметь несколько шаблонов с разным набором визуальных настроек: сетка, список, слайдер — при неизменной логике выборки. Значения параметров шаблона также участвуют в формировании ключа кэша, поэтому смена режима отображения корректно создаёт отдельную версию кэша.

Порядок исполнения файлов

Чтобы не путать, где что писать, полезно помнить последовательность:

1. component.php / класс — выборка данных;
2. result_modifier.php — правка $arResult под шаблон (кэшируется);
3. template.php — генерация HTML (кэшируется);
4. component_epilog.php — код вне кэша.

Итог

Шаблон компонента — это не только template.php, но и связка из result_modifier.php, component_epilog.php, автоматически подключаемых style.css и script.js, а также языковых файлов. Понимание порядка их исполнения и разницы между кэшируемой и некэшируемой частью — ключ к производительной и поддерживаемой кастомизации.

Если нужно аккуратно переработать вёрстку типовых компонентов или выстроить единую систему шаблонов на большом проекте, мы берёмся за это в рамках поддержки и развития сайтов на 1С-Битрикс.