Главная > Блог > Web-разработка > CMS Битрикс >

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

01.07.2018

Теги: $arParams • $arResult • CMS • component_epilog.php • result_modifier.php • Web-разработка • Битрикс • Кеширование • Компонент • ШаблонКомпонента

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

Папка компонента может содержать следующие папки и файлы:

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

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

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 и добавляем в него код:

<?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

Поиск: $arParams • $arResult • CMS • Web-разработка • Битрикс • Компонент • Шаблон компонента