template.php в Битрикс: структура шаблона компонента

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

Что доступно внутри файла

К моменту подключения template.php компонент уже выполнил всю работу по получению данных, и они лежат в массиве $arResult. Кроме него доступны ещё несколько переменных:

Переменная	Содержит
`$arResult`	Данные, подготовленные компонентом
`$arParams`	Параметры, с которыми компонент был вызван
`$this`	Объект самого компонента — доступ к его методам
`$templateFolder`	Путь к папке текущего шаблона
`$componentPath`	Путь к самому компоненту

Типичная структура

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

<div class="catalog-list">
    <?php foreach ($arResult['ITEMS'] as $item): ?>
        <article class="catalog-item">
            <a href="<?= $item['DETAIL_PAGE_URL'] ?>">
                <img src="<?= $item['PREVIEW_PICTURE']['SRC'] ?>" alt="<?= $item['NAME'] ?>">
                <h3><?= $item['NAME'] ?></h3>
                <span class="price"><?= $item['PRICE']['PRINT_PRICE'] ?></span>
            </a>
        </article>
    <?php endforeach; ?>
</div>

<?php if ($arResult['NAV_RESULT']): ?>
    <?php $this->__component->setResultCacheKeys(['NAV_RESULT']); ?>
    <?php echo $arResult['NAV_STRING']; ?>
<?php endif; ?>

Проверка B_PROLOG_INCLUDED в начале — та же защита от прямого обращения к файлу по адресу, что используется в header.php и footer.php шаблона сайта.

Нужна помощь с Битрикс?

Разница между кешируемыми и некешируемыми данными

Особенность именно template.php, которую легко упустить: если компонент кеширует свой результат, всё, что попадает в $arResult обычным образом, кешируется вместе с ним. Данные, которые не должны кешироваться — например, текущее время или персональные данные пользователя, — регистрируются через setResultCacheKeys() или выводятся в некешируемой части через $this->__component->setFrameMode() и AJAX-догрузку.

Не место для сложной логики

Если внутри template.php появляются запросы к базе или сложные вычисления — это сигнал, что логика оказалась не там. Правильные места для неё: сам класс компонента, если это ваш компонент, или result_modifier.php, если дорабатывается стандартный. Шаблон должен оставаться максимально простым — циклы вывода и условия форматирования, не более.

Подключение своих стилей и скриптов

Файлы style.css и script.js в той же папке, что и template.php, подключаются автоматически — дополнительно ничего прописывать не нужно. Если требуется подключить что-то ещё, это делается методами $APPLICATION, доступными внутри шаблона так же, как в обычном файле страницы.

Несколько шаблонов у одного компонента

У компонента может быть несколько шаблонов — например, для вывода списком и плиткой. Выбор нужного делается вторым параметром при вызове IncludeComponent, а сами варианты хранятся в разных папках внутри структуры шаблонов компонента.

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

Запросы к базе прямо в шаблоне. Логика должна жить в компоненте, а не в файле вывода.
Персональные данные попадают в общий кеш. Без выделения некешируемой части все посетители видят данные первого закешированного запроса.
Отсутствует проверка B_PROLOG_INCLUDED. Файл шаблона можно открыть напрямую по URL.
Не используется $templateFolder. Пути к ресурсам шаблона прописываются жёстко, что ломается при переносе шаблона в другое место.

Итог

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