Функция CMain::IncludeComponent

Введение

Давайте разберемся, что за функция CMain::IncludeComponent(), и как ей пользоваться, чтобы потом не было стыдно (кстати, это не функция, а метод *но я специально использую слово функция для лучшего ранжирования).

Документация, конечно же, есть (ссылочка на нее), и могу сказать, что она на 90% правильная, но кое-что в ней все-таки не так. Давайте разбираться по порядку.

Чтобы правильно препарировать любую функцию нужно знать ответ на три вопроса мироздания об этой функции:

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

Зная ответ на каждый из этих вопросов, вы сможете правильно пользоваться данной функцией.

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

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

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

Здесь тоже, в целом, все написано верно в документации, повторим все параметры.

public function IncludeComponent(
    $componentName,
    $componentTemplate,
    $arParams = array(),
    $parentComponent = null,
    $arFunctionParams = array(),
    $returnResult = false
)   

• Первый параметр $componentName: имя компонента. Здесь указываем полное имя компонента в виде: "Пространство имен:Имя компонента".
• Второй параметр $componentTemplate: имя шаблона этого компонента. Если ничего не указать, то подключается шаблон с именем .default
• Третий параметр $arParams: параметры компонента. В виде массива указываются все параметры, передаваемые в компонент. Если вы не указали какие-то параметры, то их не будет в вашем компоненте вообще (сектор null на барабане). А если решили дописать несуществующие. то они будут, но редактирование компонента в режиме правки не обещает сохранение таких безбилетных параметров.
• Четвертый параметр $parentComponent: ссылка на объект родительского компонента, либо null. Используется в комплексных компонентах для указания ссылки на родителя. В этом случае вы сможете из дочернего компонента обратиться к методам и свойствам родительского через свойство __parent:

/** Например, глядим на параметр в родительском компоненте */
$this->__parent->arParams['SOMETHING_INTERESTING'];

• Пятый параметр $arFunctionParams: массив доп. параметров для компонента. Иногда полезная вещь, может содержать два ключа.
  • "HIDE_ICONS"=>"Y" - блокируем возможность менять параметры компонента в режиме редактирования;
  • "ACTIVE_COMPONENT"=>"N" - отключаем компонент (код компонента не подключается).
• Шестой параметр $returnResult: в случае если установлен в true, то компонент функция вернет массив $arResult компонента, в качестве результата своей работы.

Что ж, нашинковали, думаю, теперь понятно как компонентом можно управлять, а теперь перейдем к самому интересному.

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

В документации написано: "Возвращает код компонента", - вы серьезно?

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

Если документации верить нельзя, а спросить не у кого (представим что я не знаю, что там происходит на самом деле), то нужно идти в исходный код, его можно посмотреть на специальном сайте bxapi.ru, или в вашем любимом редакторе, открыв файл: bitrix/modules/main/classes/general/main.php.

Ищем, что же возвращает этот метод..., ага, в конце некий $result

return $result;

А откуда он берется

/** Тут он объявляется */
$result = null;
...

/** Ага, нашелся, еще один IncludeComponent у переменной $component */
$result = $component->IncludeComponent($componentTemplate, $arParams, $parentComponent);
...

/** А вот и "оно", чуть выше,
это как можно было догадаться из названия переменной - компонент */
$component = new CBitrixComponent();

Теперь мы знаем, что метод IncludeComponent() класса CMain возвращает то, что возвращает метод IncludeComponent() класса CBitrixComponent. Теперь докопаемся до него по той же схеме.

Заходим в этот класс и ищем метод с тем же названием, ссылка на bxapi.ru, сам файл: bitrix/modules/main/classes/general/component.php

Тут мы видим два источника все той же переменной $result, работает либо один либо другой:

/** первый */
$result = $component->executeComponent();
/** второй */
$result = $this->__IncludeComponent();

Первая от ядра D7, если вы создали class.php, ,кстати, если вы не переопределяли метод executeComponent(), то его код выглядит так:

public function executeComponent()
{
    return $this->__includeComponent();
}

Отсюда делаем еще один вывод: class.php в обычном режиме (без переопределения, или сделав parent::executeComponent()) подключает внутри себя файл component.php.

Внутри метода __includeComponent() мы увидим такую строку кода:

return include($_SERVER["DOCUMENT_ROOT"].$this->__path."/component.php");

Итого

Таким образом, мы докопались до истины: если компонент - это класс D7, то исходный метод CMain::IncludeComponent() возвращает то, что будет возвращено методом executeComponent(). Если же компонент - это не класс D7, то будет возвращено то, что возвращается в файле component.php.

Если обобщить, то метод CMain::IncludeComponent() (вы его часто видите в виде $APPLICATION->IncludeComponent()) возвращает то, что возвращает сам компонент. Т.е. вы полностью управляете тем, что будет возвращено этим методом при подключении вашего собственного компонента. Например, такой механизм можно использовать в паре компонентов "Фильтр" + "Список": фильтр возвращает массив для фильтрации, а список его принимает в качестве параметра.

Исключение, когда шестой параметр установлен в true, тогда будет возвращен массив arResult, который компонент собрал в процессе своей работы.

И это прям совсем не "код компонента", как нам обещали в документации. Доверяй, но проверяй.

Резюме

Кратко резюмируем полученную информацию:

Функция IncludeComponent()

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