Размещение и настройка компонентов

Структура компонента

Компоненты сгруппированы по пространствам имен в папках /bitrix/components/ и /local/components/. Для системных компонентов - пространство имен bitrix. Таким образом, полный путь для них будет: /bitrix/components/bitrix/[техническое название компонента]/.

Компонент состоит из следующих файлов и папок:

1. Главный файл class.php — “сердце” компонента, его логика или контроллер. Класс, который обрабатывает данные http-запроса и готовит данные для вывода с помощью шаблона. Основное средство коммуникации с шаблоном - массив $arResult.
2. Вместо (или вместе) с файлом class.php может существовать component.php — устаревший процедурный формат описания компонента.
3. Раздел templates — типовые шаблоны компонента. Если вам нужно повлиять на внешний вид или немного скорректировать компонент, то вам подойдет доработка шаблона компонента (также ее называют “кастомизацией”). Но трогать системные шаблоны нельзя — предварительно их нужно скопировать в свое пространство имен (например, в /local/templates/.default/component/…).
   • Главный файл для шаблона простого компонента: template.php. Используя данные из массива $arResult, выводит html-код компонента. В этом файле не следует делать запросы к БД, сессиям и т.п. Лучше всего ограничиться простыми конструкциями языка php: if’ы, циклы и echo для вывода данных.
   • result_modifier.php — файл шаблона, в котором разрешено делать дополнительные запросы к БД. Файл подключается в ходе работы компонента непосредственно перед вызовом template.php.
   • component_epilog.php — файл шаблона, где выполняются особые операции, которые нельзя делать в области кеширования. Подключается после template.php.
   • .parameters.php — файл с дополнительными настройками этого шаблона.
   • lang-файлы шаблона компонента (файлы локализации или языковые файлы).
   • Статические ресурсы шаблона компонента (файлы CSS, JS, изображения).
4. .parameters.php — файл с описанием настроек для интерфейса администратора. Чем больше настроек, тем сложнее будет логика и, следовательно, код компонента. Необязательный файл, но без него контент-редактор не сможет никак повлиять на работу компонента.
5. lang-файлы компонента (файлы локализации или языковые файлы).
6. Статические ресурсы компонента (файлы CSS, JS, изображения).

Пути, названия

Стандартные компоненты “приходят” на сайт в составе модулей (папка /bitrix/modules/install/components/), а после установки копируются в /bitrix/components/bitrix/.

Компоненты, установленные вместе с модулями из маркетплейса, будут размещены в других пространствах имен в папках /bitrix/components/ и /local/components/.

Компоненты собственной разработки следует располагать в /local/components/пространство имен собственного модуля/.

Шаблоны компонентов могут располагаться в папке templates текущего шаблона сайта, .default-шаблона сайта, в папке с шаблоном комплексного компонента, в папке с самим компонентом.

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

• catalog.section.list,
• form.result.new,
• main.profile.

При упоминании в документации или инструкциях принято указывать и пространство имен компонентов. У всех системных пространство имен bitrix. Таким образом, компонент профиля пользователя имеет полный код bitrix:main.profile.

Именование комплексных компонентов обычно содержит меньше сегментов в названии, иногда сегмент всего один:

• news,
• catalog.

Тут действует правило: чем конкретнее решаемая задача, тем точнее (и длиннее) должно быть название компонента. Речь именно про техническое название, присвоение имени для визуального редактора на русском языке может быть другим.

Неожиданный факт: разработчик под платформу «1С-Битрикс: Управление сайтом» с многолетним стажем скорее вспомнит техническое название bitrix:main.profile, чем понятное “Параметры пользователя”.

Устройство компонента

Код $APPLICATION->includeComponent вызывает метод executeComponent класса из файла class.php или подключает и выполняет файл component.php. Если компонент реализован по ООП-схеме, то файл class.php должен содержать объявление одного класса и этот класс должен быть наследником CBitrixComponent. Компонент может быть непрямым наследником базового класса.

Он должен переопределять метод executeComponent, обрабатывать параметры из $this->arParams и наполнять $this->arResult для передачи в шаблон сайта. При подключении шаблона сначала выполняется файл result_modifier.php, затем страница шаблона (для простых компонентов это template.php), затем component_epilog.php.

В файлах шаблона доступны переменные:

• $arResult — массив данных произвольной структуры, подготовленный компонентом.
• $arParams — массив параметров, заданных программистом или контент-редактором в веб-интерфейсе компонента при вызове.
• $templateFolder — путь к папке с шаблоном от корня сайта.
• $component — текущий компонент (объект CBitrixComponent).
• $this — текущий шаблон (объект CBitrixComponentTemplate).