Component Parameters

The file .parameters.php contains the description of the input parameters of the component. The file data are needed exclusively to create the form to enter the properties of the component in Bitrix Framework environment (e.g., in a visual editor). This description is used for work with the component and also during work in the website editing mode. The description is not used and the said file is not connected during the operation of the component itself (when the page with the component is requested).

The fil .parameters.php must be located in the component folder. The language file is connected automatically (it must be located in the folder /lang/<language>/.parameters.php, of the component folder).

The file determines the array $arComponentParameters, which describes the input parameters of the component. If necessary, any additional data are selected. E.g., all active types must be selected in order to establish a drop-down list of information block types (input parameter IBLOCK_TYPE_ID).

The structure of the typical file .parameters.php (based on the example of the components that operate with the module Information Block):

<?
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")
         ),
      ),
   )
);
?>

Let us have a closer look at the keys of the array $arComponentParameters.

GROUPS

The value of this key is an array of component parameter groups. In the visual means of the Bitrix Framework (e.g., in a visual editor), the parameters are grouped. The groups in the Bitrix Framework environment are located according to the order set in the file. The array of the component parameter groups consists of the following types of elements:

"group code" => array(
    "NAME" => "name of the group in the current language"
    "SORT" => "sorting",
    )

List of standard groups:

ADDITIONAL_SETTINGS (sorting - 700). This group appears, for example, when indicating the parameter SET_TITLE.
CACHE_SETTINGS (sorting - 600). It appears when indicating the parameter CACHE_TIME.
SEF_MODE (sorting 500). The group for all parameters connected with the use of SEF.
URL_TEMPLATES (sorting 400). Link templates
VISUAL (sorting 300). This group is rarely used. These are parameters responsible for physical appearance.
DATA_SOURCE (sorting 200). Infoblock type and ID.
BASE (sorting 100). Main parameters.
AJAX_SETTINGS (sorting 550). Everything associated with AJAX.

PARAMETERS

The value of this key is an array of component parameters. In each parameter group, the parameters are located in the order set in the file. The array of regular parameters of the component consists of the following types of elements:

"parameter code" => array(
    "PARENT" => "group code",  // if not - ADDITIONAL_SETTINGS shall be established
    "NAME" => "parameter name in the current language",
    "TYPE" => "type of the control element in which the parameter will be established",
    "REFRESH" => "refresh settings or not after selection (N/Y)",
    "MULTIPLE" => "single/multiple value (N/Y)",
    "VALUES" => "array of values for the list (TYPE = LIST)",
    "ADDITIONAL_VALUES" => "show the field for the values to be entered manually (Y/N)",
    "SIZE" => "number of lines for the list (if a list which is not a drop-down list is needed)",
    "DEFAULT" => "default value",
    "COLS" => "field width in characters",
),

The following values are available for the TYPE control element type:

LIST - selection from the list of values. For the type LIST the key VALUES contains an array of values of the following type:
```
VALUES => array(
   "ID or code to be saved in the component settings" => "language dependent description",
),
```
STRING - text entry field.
CHECKBOX - yes/no.
CUSTOM - permits creating customized control elements.

The physical appearance of the list changes depending on whether the MULTIPLE and ADDITIONAL_VALUES keys are available/absent:

If there are no MULTIPLE and ADDITIONAL_VALUES or they are equal to “N”, a simple list is displayed, and no values are added to the list:
If ADDITIONAL_VALUES = "Y", MULTIPLE = "N", the value Other is added to the list with an additional field allowing manual entry of a value:
If ADDITIONAL_VALUES = "N", MULTIPLE = "Y", nothing will be added to the list, but it becomes possible to select several elements:
If ADDITIONAL_VALUES = "Y", MULTIPLE = "Y", the value Not selected is added to the list with a multiple additional field allowing manual entry of a value.

The REFRESH parameter permits to refresh the entire form with parameters following value selection. This is done, for example, to select an infoblock of a specific type. I.e., we have two parameters: infoblock type and infoblock code. The starting point is as follows: the first parameter contains all types of infoblocks, the second parameter contains a list of all infoblocks of this website; after the selection of a certain type of infoblock, component parameters are refreshed, and we can only see the infoblocks of the selected type.

Externally, for the LIST - type parameters, this key is represented as the OK button located close to the relevant parameter (see screenshots above).

If a certain parameter must appear or remain hidden depending on another parameter, the procedure is as follows. For example, we need to display the list of properties of an infoblock. Assuming that the infoblock ID is contained in the IBLOCK_ID component parameter, let us name the parameter containing property list PROP_LIST. The parameter IBLOCK_ID must have the key REFRESH = 'Y' established. The code:

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' => 'parameter title',
      'TYPE' => 'LIST'
      'VALUES' => $arPropList,
   );
}

There are special parameters that are standardized so that there is no need to describe them in detail. It is sufficient just to indicate that they exist. For example,

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

The first of the indicated parameters shows whether the component should set a page header and the second one shows all cache-related settings.

Only composite components can work in a SEF mode or redefine the variables coming from an HTTP request. In this case, two special parameters must be indicated among the parameters:

VARIABLE_ALIASES - an array describing variables that the component may receive from an HTTP request. Each element of the array looks like the following:
```
"internal name of the variable" => array(
  "NAME" => "name of the variable in the current language",
)
```

SEF_MODE - an array describing path templates in a SEF mode. Each element of the array looks like the following:

"path template code" => array(
    "NAME" => "name of the path template in the current language",
    "DEFAULT" => "default path template",
    "VARIABLES" => "an array of internal names of variables that may be used in the template"
)

From product version 12 on (new core D7) there is an option to add a control element into the component parameters that permits to indicate color (COLORPICKER).

To do so, the following must be indicated in the component parameter file .parameters.php:

$arParams["COLOR"] = Array(
    "PARENT" => "BASE",
    "NAME" => 'Colour selection',
    "TYPE" => "COLORPICKER",
    "DEFAULT" => 'FFFF00'
);