156  /  328

Параметры компонента

Просмотров: 8810 (Статистика ведётся с 06.02.2017)
Дата последнего изменения: 20.02.2017

В файле .parameters.php содержится описание входных параметров компонента. Данные файла нужны исключительно для создания формы ввода свойств компонента в среде Bitrix Framework (например, в визуальном редакторе). Это описание применяется для работы с компонентом, а также при работе в режиме редактирования сайта. При работе самого компонента (при обращении к странице, на которой расположен компонент) описание не используется и указанный файл не подключается. Для комплексного компонента в этом файле задаются параметры простых компонентов, входящих в состав комплексного. Также здесь будут задаваться и настройки ЧПУ.

Файл .parameters.php должен находиться в папке компонента. Языковой файл подключается автоматически (должен лежать в папке /lang/<язык>/.parameters.php, относительно папки компонента).

В файле определяется массив $arComponentParameters, который описывает входные параметры компонента. Если необходимо, производится выборка каких-либо дополнительных данных. Например, для формирования выпадающего списка типов информационных блоков (входной параметр IBLOCK_TYPE_ID) выбираются все активные типы.

Структура типичного файла .parameters.php (на примере компонентов, работающих с модулем Информационные блоки):

<?
CModule::IncludeModule("iblock");

$dbIBlockType = CIBlockType::GetList(
   array("sort" => "asc"),
   array("ACTIVE" => "Y")
);
while ($arIBlockType = $dbIBlockType->Fetch())
{
   if ($arIBlockTypeLang = CIBlockType::GetByIDLang($arIBlockType["ID"], LANGUAGE_ID))
      $arIblockType[$arIBlockType["ID"]] = "[".$arIBlockType["ID"]."] ".$arIBlockTypeLang["NAME"];
}

$arComponentParameters = array(
   "GROUPS" => array(
      "SETTINGS" => array(
         "NAME" => GetMessage("SETTINGS_PHR")
      ),
      "PARAMS" => array(
         "NAME" => GetMessage("PARAMS_PHR")
      ),
   ),
   "PARAMETERS" => array(
      "IBLOCK_TYPE_ID" => array(
         "PARENT" => "SETTINGS",
         "NAME" => GetMessage("INFOBLOCK_TYPE_PHR"),
         "TYPE" => "LIST",
         "ADDITIONAL_VALUES" => "Y",
         "VALUES" => $arIblockType,
         "REFRESH" => "Y"
      ),
      "BASKET_PAGE_TEMPLATE" => array(
         "PARENT" => "PARAMS",
         "NAME" => GetMessage("BASKET_LINK_PHR"),
         "TYPE" => "STRING",
         "MULTIPLE" => "N",
         "DEFAULT" => "/personal/basket.php",
         "COLS" => 25
      ),
      "SET_TITLE" => array(),
      "CACHE_TIME" => array(),
      "VARIABLE_ALIASES" => array(
         "IBLOCK_ID" => array(
            "NAME" => GetMessage("CATALOG_ID_VARIABLE_PHR"),
         ),
         "SECTION_ID" => array(
            "NAME" => GetMessage("SECTION_ID_VARIABLE_PHR"),
         ),
      ),
      "SEF_MODE" => array(
         "list" => array(
            "NAME" => GetMessage("CATALOG_LIST_PATH_TEMPLATE_PHR"),
            "DEFAULT" => "index.php",
            "VARIABLES" => array()
         ),
         "section1" => array(
            "NAME" => GetMessage("SECTION_LIST_PATH_TEMPLATE_PHR"),
            "DEFAULT" => "#IBLOCK_ID#",
            "VARIABLES" => array("IBLOCK_ID")
         ),
         "section2" => array(
            "NAME" => GetMessage("SUB_SECTION_LIST_PATH_TEMPLATE_PHR"),
            "DEFAULT" => "#IBLOCK_ID#/#SECTION_ID#",
            "VARIABLES" => array("IBLOCK_ID", "SECTION_ID")
         ),
      ),
   )
);
?>

Опишем ключи массива $arComponentParameters подробнее.

GROUPS

Значением этого ключа является массив групп параметров компонента. Параметры в визуальных средствах среды Bitrix Framework (например, в визуальном редакторе) группируются. Группы в среде Bitrix Framework располагаются в том порядке, в котором заданы в файле. Массив групп параметров компонента состоит из элементов следующего вида:

"код группы" => array(
    "NAME" => "название группы на текущем языке",
    "SORT" => "сортировка",
    )

Перечень стандартных групп:

  • ADDITIONAL_SETTINGS (сортировка - 700). Эта группа появляется, например, при указании параметра SET_TITLE.
  • CACHE_SETTINGS (сортировка - 600). Появляется при указании параметра CACHE_TIME.
  • SEF_MODE (сортировка 500). Группа для всех параметров, связанных с использованием ЧПУ.
  • URL_TEMPLATES (сортировка 400). Шаблоны ссылок
  • VISUAL (сортировка 300). Редко используемая группа. Сюда предполагается загонять параметры, отвечающие за внешний вид.
  • DATA_SOURCE (сортировка 200). Тип и ID инфоблока.
  • BASE (сортировка 100). Основные параметры.
  • AJAX_SETTINGS (сортировка 550). Все, что касается ajax.

PARAMETERS

Значением этого ключа является массив параметров компонента. В каждой группе параметров параметры располагаются в том порядке, в котором заданы в файле. Массив обычных параметров компонента состоит из элементов следующего вида:

"код параметра" => array(
    "PARENT" => "код группы",  // если нет - ставится ADDITIONAL_SETTINGS
    "NAME" => "название параметра на текущем языке",
    "TYPE" => "тип элемента управления, в котором будет устанавливаться параметр",
    "REFRESH" => "перегружать настройки или нет после выбора (N/Y)",
    "MULTIPLE" => "одиночное/множественное значение (N/Y)",
    "VALUES" => "массив значений для списка (TYPE = LIST)",
    "ADDITIONAL_VALUES" => "показывать поле для значений, вводимых вручную (Y/N)",
    "SIZE" => "число строк для списка (если нужен не выпадающий список)",
    "DEFAULT" => "значение по умолчанию",
    "COLS" => "ширина поля в символах",
),

Для типа элемента управления TYPE есть значения:

  • LIST - выбор из списка значений. Для типа LIST ключ VALUES содержит массив значений следующего вида:
    VALUES => array(
       "ID или код, сохраняемый в настройках компонента" => "языкозависимое описание",
    ),
  • STRING - текстовое поле ввода.
  • CHECKBOX - да/нет.
  • CUSTOM - позволяет создавать кастомные элементы управления.
  • FILE - выбор файла.

    Пример реализации

Внешний вид списка меняется в зависимости от наличия/отсутствия ключей MULTIPLE и ADDITIONAL_VALUES:

  • Если MULTIPLE и ADDITIONAL_VALUES отсутствуют или равны "N", то выводится просто список, никаких значений в список не добавляется.
  • Если ADDITIONAL_VALUES = "Y", MULTIPLE = "N", то в список добавляется значение "другое" и рядом доп.поле для ввода значения вручную:

  • Если ADDITIONAL_VALUES = "N", MULTIPLE = "Y", то в список ничего не добавляется, просто появляется возможность выбрать несколько элементов:

  • Если ADDITIONAL_VALUES = "Y", MULTIPLE = "Y", то в список добавляется значение не выбрано и рядом множественное дополнительное поле для ввода значения вручную.
  • Примечание: Скриншоты делались для значения SIZE = 9. Если этот ключ не указывать, список будет выпадающим.


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

Внешне для параметров типа LIST этот ключ проявляется как кнопка с надписью ОК возле параметра (см. скриншоты выше).

Если нужно, чтобы некий параметр появлялся или нет в зависимости от другого, делается это так. Пусть нам необходимо показать список свойств инфоблока. Предположим, что ID инфоблока содержится в параметре компонента IBLOCK_ID, а параметр, где будет список свойств назовем PROP_LIST. У параметра IBLOCK_ID должен быть выставлен ключ REFRESH = 'Y'. Код:

if (0 < intval($arCurrentValues['IBLOCK_ID']))
{
   $arPropList = array();
   $rsProps = CIBlockProperty::GetList(array(),array('IBLOCK_ID' => $arCurrentValues['IBLOCK_ID']));
   while ($arProp = $rsProps->Fetch())
   {
      $arPropList[$arProp['ID']] = $arProp['NAME'];
   }
   $arComponentParameters['PARAMETERS']['PROP_LIST'] => array(
      'NAME' => 'название параметра',
      'TYPE' => 'LIST',
      'VALUES' => $arPropList,
   );
}

Существуют особые параметры, которые стандартизованы и которые нет необходимости описывать полностью. Достаточно указать, что они есть. Например,

"SET_TITLE" => array(),
"CACHE_TIME" => array(),

Первый из указанных параметров указывает, следует ли компоненту установить заголовок страницы, а второй - все настройки, связанные с кешированием.


Только комплексные компоненты могут работать в режиме ЧПУ или переопределять переменные, которые приходят из HTTP запроса. В этом случае необходимо среди параметров указать ещё два особых параметра:

  • "VARIABLE_ALIASES" - массив, описывающий переменные, которые компонент может получать из HTTP запроса. Каждый элемент массива имеет вид:
    "внутреннее название переменной" => array(
      "NAME" => "название переменной на текущем языке",
    )
  • "SEF_MODE" - массив, описывающий шаблоны путей в режиме ЧПУ. Каждый элемент массива имеет вид:
    "код шаблона пути" => array(
        "NAME" => "название шаблона пути на текущем языке",
        "DEFAULT" => "шаблон пути по-умолчанию",
        "VARIABLES" => "массив внутренних названий переменных, которые могут использоваться в шаблоне"
    )

Начиная с 12 версии продукта (новое ядро D7) появилась возможность добавления в параметры компонента элемента управления, позволяющего указывать цвет (COLORPICKER).

Для этого необходимо указать следующее в файле параметров компонента .parameters.php:

$arComponentParameters["PARAMETERS"]["COLOR"]  = Array(
    "PARENT" => "BASE",
    "NAME" => 'Выбор цвета',
    "TYPE" => "COLORPICKER",
    "DEFAULT" => 'FFFF00'
);

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


41
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии