Функция CBitrixComponent::IncludeComponentTemplate

Введение

Сегодня мы рассмотрим очередную часто используемую функцию в Битриксе - CBitrixComponent::IncludeComponentTemplate (И это тоже метод, а не функция, но вы уже знаете, почему написано именно так).

Как всегда, ссылочка на документацию приложена, перейдем к исследованию.

Чтобы разобраться в работе этой функции, нужно зайти с трех сторон:

1. Что делает функция?
2. Какие параметры она принимает?
3. Что она возвращает?

Приступим-с, код этого метода можно посмотреть на сайте bxapi.ru

1. Что делает функция?

Что делает этот метод написано в названии, то же самое и в документации: метод инициализирует и подключает шаблон компонента.

Если шаблон подключить не удастся, то будет выведена ошибка: "не удалось найти такую-то страницу в таком-то шаблоне". Обратите внимание на это слово, я не зря его выделил.

Основной набор дел на этом заканчивается. Однако если копнуть глубже, то мы увидим, что только подключением и выводом шаблона область действия этого метода не ограничивается. Это очень "деловой" метод. Он и result_modifier подключает, и шаблон выводит, и кеширование завершает, и про component_epilog не забывает. И все он. Прям палочка-подключалочка.

Кстати, этот метод объявлен с ключевым словом final, так что вы не сможете его переопределить в компоненте, даже если очень захочется.

2. Какие параметры функция принимает?

Описание параметров этого метода  в документации произведено с успехом 50 / 50 (ну т.е. "как получилось").

final public function IncludeComponentTemplate(
    $templatePage = "",
    $customTemplatePath = ""
);

• Первый параметр $templatePage: имя страницы шаблона компонента. И снова обращаем внимание на это слово. А еще написано, что этот параметр устанавливается только для шаблонов комплексных компонентов, а для обычных шаблонов он должен быть равен пустой строке, но не верьте этому.
• Второй параметр $customTemplatePath: путь к шаблону. Очень специфичный параметр, не видел, чтобы он хоть когда-нибудь применялся.

3. Что функция возвращает?

Барабанная дробь... Ничего. Этот метод ничего не возвращает. Идем дальше.

Загадочное слово "страница"

Слово "страница" в описании - это тот случай, когда одно слово в предложении полностью переворачивает весь его смысл. Если бы не этот параметр, то в методе не было бы никаких сложностей.  В этом случае метод просто бы подключал шаблон компонента, который вы указали при подключении компонента.

Но этот параметр есть, и он на что-то влияет. И очень часто это слово у тех, кто первый раз знакомится с этим методом просто превращается в туман. "Если его не видеть - то его нет", - наверное думают они.

И если это слово опустить, то параметр превращается в "Имя шаблона компонента". И отсюда следует напрашивающийся очевидный вывод: если здесь указать что-то, то будет подключен шаблон компонента с указанным названием шаблона.

Неприятная история одного магазинчика

Но представим такую реальную ситуацию. Интегрируете вы очень красивую верстку интернет-магазина. У вас будет лучший магазин, продающий... что-нибудь особенное... не знаю... костюмчики для маленьких летающих дракончиков с укрепленными дырочками для их крылышек. Многие же любят наряжать своих питомцев, думаю, это будет очень популярный магазин.

Так вот.

Сидели вы - корпели над интеграцией этого шаблона. А у вас там все: и акции, и подарки, и купоны на скидки, и ленточки на товарах, даже доставка в день заказа колесницей, запряженной единорогами. И интегрировали вы 33 дня и 33 ночи. И вот, наконец, выложили в интернет свой магазин и любуетесь красотой. Но вдруг темной ночью код компонента битрикса считал что-то, считал и насчитал: "передам-ка я первым параметром в метод IncludeComponentTemplate что-нибудь эдакое". И подключает битрикс другой шаблон каталога, а там стили 80-ых: кислотные цвета, рамки 18 пикселей шириной и скругления картинками (кто помнит - тот поймет). В итоге вся верстка на вашем сайте... да как развалилась и забилась в конвульсиях (читать с интонацией).

Согласитесь, что-то явно не так. Вы же указывали шаблон еще при подключении компонента, а тут такое.

Разгадка слова "страница"

Тут вы снова вчитываетесь в описание параметра, и теперь слово страница выплывает из тумана, становясь явным как солнце в безоблачный денек.

Так что же может быть этой самой страницей шаблона? Откройте любой шаблон и что вы там увидите:

lang/
template.php
...

Языковые файлы - это страницы?... Нет. result_modifier или component_epilog - тоже нет, это специальные файлы, но не страницы. А остается-то кто, только господин template.php. 

Так значит, что "это вы таскали мои плюшки...", т.е. это он и является страницей шаблона компонента.

А значит, если мы укажем, к примеру, такой первый параметр:

$this->IncludeComponentTemplate('marvel');

все что произойдет - битрикс попробует подключить файл marvel.php из выбранного шаблона компонента. И все, никаких чудес.

Вот она сладкая разгадка, как все просто оказалось на самом деле.

Имеем в остатке

Теперь, если вы захотите подключить разные виды страницы - вы можете это сделать, и никто вас не остановит. И ерунда, что в документации написано: "только для комплексных компонентов".

Представим, что вы выводите список элементов, а если он пуст, то вам нужно просто написать сообщение. Так можно условие сделать не в шаблоне, а в компоненте и подключить разные страницы шаблона: template.php (если элементы есть) или empty.php (если элементов нет). Не вижу никаких явных причин так не делать: получится меньше условий в шаблонах. Все зависит от ваших предпочтений.

Резюме

Как всегда вкратце.

Метод CBitrixComponent::IncludeComponentTemplate()

• подключает и отображает шаблон компонента;
• в качестве параметра ему можно передать имя страницы этого шаблона и путь к шаблону;
• ничего не возвращает.