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

Компонент хранит все, что ему нужно для работы, в своей папке. Поэтому их можно легко переносить между проектами. Файлы компонента нельзя использовать по отдельности. Компонент — это единое целое, он обладает свойством неделимости. Папка компонента может содержать следующие папки и файлы:

Папка lang в которой расположены файлы языковых сообщений переводов компонента. С версии 11.0 в ней также могут размещаться папка помощи help
Папка templates в которой расположены шаблоны вывода (отображения) компонента. Эта подпапка может отсутствовать, если у компонента нет шаблонов вывода
- Папка .default
  - Файл template.php шаблон компонента, отвечает за показ элемента инфоблока
  - Файл component_epilog.php подключается после файла шаблона template.php и никогда не кешируется
  - Файл result_modifier.php позволяет внести изменения в результаты работы компонента, т.е. модифицировать массив $arResult
  - Файл script.js содержит скрипты необходимые для работы компонента, подключается автоматически
  - Файл style.css содержит стили необходимые для работы компонента, подключается автоматически
Файл class.php для поддержки ООП-компонентов
Файл component.php содержит код компонента. Задача этого файла, сформировать из полученных параметров $arParams массив $arResult, который впоследствии попадет в шаблон компонента. Этот файл должен всегда присутствовать в папке компонента
Файл .description.php содержит название, описание компонента и его положение в дереве логического размещения (для редактора). Этот файл должен всегда присутствовать в папке компонента. Его отсутствие не скажется на работе компонента, но размещение компонента через визуальный редактор станет невозможным
Файл .parameters.php который содержит описание входных параметров компонента для редактора. Если у компонента есть входные параметры, то этот файл должен присутствовать в папке компонента
Любые другие папки и файлы с ресурсами, необходимыми компоненту, например папка images

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

component.php или class.php
result_modifier.php
template.php
component_epilog.php

Общая структура компонента

if ( ! \Bitrix\Main\Loader::includeModule('iblock')) {
ShowError('Модуль «Информационные блоки» не установлен');
return;
}
/*
* Подготовка входных параметров компонента
*/
// время кеширования
if (!isset($arParams['CACHE_TIME'])) {
$arParams['CACHE_TIME'] = 3600;
} else {
$arParams['CACHE_TIME'] = intval($arParams['CACHE_TIME']);
}
// идентификатор элемента инфоблока
$arParams['ELEMENT_ID'] = empty($arParams['ELEMENT_ID']) ? 0 : intval($arParams['ELEMENT_ID']);
// типичный алгоритм кеширования
if ($this->StartResultCache()) {
// если нет валидного кеша — получаем данные из БД
if ($arParams['ELEMENT_ID']) {
// выполняем запрос к базе данных
$rsElement = CIBlockElement::GetList(/*...*/);
if ($arResult = $rsElement->GetNext()) {
// добавляем в массив arResult дополнительные элементы, которые могут потребоваться в шаблоне
}
}
// если данные получены успешно
if (isset($arResult['ID'])) { 
// ключи $arResult, перечисленные при вызове этого метода, будут доступны в component_epilog.php и ниже по коду. Обратите внимание, там уже будет другой $arResult
$this->SetResultCacheKeys(
array(
'ID',
'NAME'
)
);
// подключаем шаблон и сохраняем кеш
$this->IncludeComponentTemplate();
// что-то пошло не так
} else { 
$this->AbortResultCache();
\Bitrix\Iblock\Component\Tools::process404(
'Страница не найдена',
true,
true
);
}
}
// кэш не затронет весь код ниже, он будут выполняться на каждом хите, но здесь работаем уже с другим $arResult — будут доступны только те ключи массива, которые перечислены в вызове SetResultCacheKeys()
if (isset($arResult['ID'])) {
// счетчик просмотров элемента
CIBlockElement::CounterInc($arResult['ID']);
// устанавливаем заголовок страницы
$APPLICATION->SetTitle($arResult['NAME']);
}

Кеширование

bool CBitrixComponent::StartResultCache(
int cacheTime,
string additionalCacheID,
string cachePath
)

Метод поддержки внутреннего кеширования компонента. Возвращает true в случае, если кеш недействителен, или false в противном случае.

Если кеш действителен, метод отправляет на экран его содержимое, заполняет $arResult и возвращает false. Если кеш недействителен, метод возвращает true, кеширование завершается и кеш сохраняется при вызове методов сразу после подключения шаблона компонента:

CBitrixComponent::IncludeComponentTemplate()
CBitrixComponent::ShowComponentTemplate()

Параметры кеширования

cacheTime время кеширования в секундах. Если этот параметр равен false, то время кеширования берется из входного параметра $arParams['CACHE_TIME']. Необязательный.
additionalCacheID кеш зависит от текущего сайта (SITE_ID), имени компонента, имени шаблона, входных параметров $arParams. Если кеш должен зависеть от каких-либо дополнительных параметров, то их необходимо передать сюда в виде строки. По умолчанию параметр равен false, т.е. кеш зависит только от текущего сайта SITE_ID, имени компонента, имени шаблона и входных параметров $arParams. Необязательный.
cachePath путь к файлу кеша относительно папки кешей. Необязательный.

Массивы $arParams и $arResult

Массив $arParams — это предопределенная для компонента переменная, представляющая собой массив входных параметров компонента. Ключами в этом массиве являются названия параметров, а значениями — их значения.

Перед подключением компонента ко всем значениям параметров применяется функция htmlspecialcharsEx(). Исходные значения параметров сохраняются в этом же массиве с теми же ключами, но с префиксом ~. Например, $arParams["NAME"] — входной параметр, к которому применена функция htmlspecialcharsEx(), а $arParams["~NAME"] — исходный входной параметр.

Переменная $arParams является псевдонимом для члена класса компонента, поэтому все изменения этой переменной отражаются и на этом члене класса. В начале кода компонента должна быть произведена проверка входных параметров, инициализация не установленных параметров, приведение к нужному типу. Все эти изменения входных параметров будут доступны и в шаблоне. То есть параметры будут там уже проверенными и максимально безопасными. Дублирование подготовки параметров в шаблоне компонента не требуется.

Массив $arResult — это предопределенная для компонента переменная, в которую собирается результат работы компонента для передачи в шаблон. Перед подключением файла компонента эта переменная инициализируется пустым массивом array().

Переменная $arResult является псевдонимом для члена класса компонента, поэтому все изменения этой переменной отражаются и на этом члене класса. Значит явно передавать в шаблон эту переменную не нужно, это сделают внутренние механизмы класса компонента.

Файл component_epilog.php

Файл component_epilog.php подключается после файла шаблона template.php и никогда не кешируется, т.е. он отработает независимо от того, был показан только что созданный html-код или вывод из кеша. Соответственно, можно использовать этот файл для выполнения каких-то действий на каждом хите — например, выводить html-код выше на странице, используя отложенные функции.

Но в нативных компонентах данные, доступные в component_epilog.php, как правило, весьма ограничены — доступны лишь ключи $arResult, перечисленные при вызове SetResultCacheKeys(). Однако, можно расширить перечень этих ключей, не затрагивая код компонента. Для этого копируем шаблон компонента, создаем файл result_modifier.php и добавляем в него код:

if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED!==true) die();
// добавляем ключ SECTION в массив $arResult
$this->__component->SetResultCacheKeys(array('SECTION'));

Файл result_modifier.php

Файл result_modifier.php позволяет внести изменения в результаты работы компонента, т.е. модифицировать массив $arResult. Файл необходимо разместить в директории, куда был скопирован шаблон компонента. Типичные решаемые задачи:

Удалить лишние данные из массива результата
Преобразовать данные перед выводом в шаблоне
Получить дополнительные данные из инфоблока
Добавить ключи в кеш, для использования в component_epilog.php

Файл component.php

Самый главный файл, присутствующий в компоненте - это component.php. Без него работать компонент не будет. В нем идет обработка входящих параметров, используя АПИ Битрикс, производится выборка из базы данных, формируется основной массив $arResult, и затем, при помощи метода includeComponentTemplate(), результат работы передается в шаблон компонента.

То есть, в данном файле описана вся логика работы компонента, поэтому он обязательный и должен присутствовать в любом из компонентов.

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

Файл .parameters.php

Следующий файл - это .parameters.php, в нем описаны параметры компонента, которые задаются в форме его настроек. В данном файле содержится основной массив $arComponentParameters, в массиве PARAMETERS собираются все настройки, которые отображаются в настройках компонента.

Все эти параметры передаются в файл component.php в массиве $arParams, который на основе их в дальнейшем обрабатывает и формирует массив $arResult.

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

Файл .description.php

Файл description.php, в нем содержится описание компонента и порядок его отображения в виртуальном дереве редактора.

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

Папка lang

Обратите внимание на часто повторяющуюся функцию GetMessage(). Она выводит текстовое содержание по ключу из файлов, расположенных в папке lang.

В ней содержатся языковые файлы с переводом компонента на различные языки. Под каждый языковой файл создана своя отдельная директория. В каждой директории размещаются файлы с теми же названиями, в которых находятся языковые сообщения, переведенные на различные языки.

В файлах находятся простые массивы, их ключами являются идентификаторы констант, а значениями – сами константы, переведенные на соответствующий язык.

В папке help, располагается файл с такими же массивами, только для них дополнительно прописывается приставка _TIP, для вывода подсказок в настройках компонента.

Папки images

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

Папке templates

В папке templates содержатся шаблоны компонентов, определяющие формат вывода данных на странице сайта.

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

Логика работы компонента

Компонент - логически завершенный код - состоит из ряда папок и файлов. Часть из них обязательна, без которых он работать не будет, часть может отсутствовать.

Компонент получает входящие параметры из массива $arParams, затем обрабатывает полученную информацию и формирует итог работы в массив $arResult. Если у компонента имеется визуальное представление, то подключается шаблон, и в него передается данные из массива $arParams и $arResult, на основании которых строится вывод всей информации на странице сайта.