Components explained

In this topic

General information
Structure
Example
Language files
Additional information

General information

To visually manage component and its parameters in the HTML editor, the component description file needs to be created.
The component description is a PHP file with the name .description.php which can reside in one of the following directories (or subdirectories):

/bitrix/templates/.default/module ID/ - directory with the default site template;
/bitrix/modules/module ID/install/templates/module ID/ - the module directory;

Structure of the file .description.php

This file can describe both a single component and a group of components. The following standard variables are available in it:

$sSectionName - the module title for the drop-down list of modules;
$iSort - sort weight of the module name in the drop-down list;
$arCurrentValues - an array of the current values of the component parameters;

$arTemplateDescription - an array describing the list of components and their parameters. The array has the following structure:

Array
(
  [the unique ID of separator 1] => an array describing separator 1:
    Array
      (
        ["SEPARATOR"] => "Y"
        ["NAME"] => separator name
        ["DESCRIPTION"] => separator description
      )
  [relative path to component 1] => an array describing component 1 and its parameters:
    Array
      (
        ["PARENT"] => ID of separator to whose group this component belongs
        ["NAME"] => component name (required)
        ["DESCRIPTION"] => component description
        ["ICON"] => path from the root to the component icon
        ["PARAMS"] => an array describing the set of the component parameters:
          Array
            (
              [parameter 1 ID] => an array describing parameter 1:
                Array
                  (
                    ["NAME"] => parameter name

                    ["TYPE"] => type of the input field for the parameter value, the following values are possible:
                      "STRING" - single line text field
                      "LIST" - list

                    ["SIZE"] => if TYPE is "LIST", the number of list strings visible without scrolling can be specified here

                    ["VALUES"] => if TYPE is "LIST", specify here an array of elements of this list in the form of:
                      Array
                        (
                          ["element 1 ID"] => element 1 value
                          ["element 2 ID"] => element 2 value
                          ["element 3 ID"] => element 3 value
                          ...
                        )
                    ["ADDITIONAL_VALUES"] => if TYPE is "LIST", setting this parameter to "N" 
                                             disables the additional field used to manually input 
                                             the value of the list
                    ["MULTIPLE"] => if "Y", the value of the parameter is
                      an array with the arbitrary number of elements
                    ["COLS"] => number of columns in the input fields
                    ["ROWS"] => number of strings in the input fields
                    ["DEFAULT"] => the default value of the parameter
                    ["CNT"] => number of fields to enter values of component parameters
                    ["REFRESH"] => if "Y", the button to reset the page containing the component parameters
                                   will be available beside the parameter input field
                      (usually, it is used when the values of component parameters
                      depend on each other: for example, choosing the type of information block
                      changes the list of available blocks)
                  )
              [parameter 2 ID] => an array describing parameter 2
              [parameter 3 ID] => an array describing parameter 3
              ...
            )
      )
  [relative path to component 2] => an array describing component 2 and its parameters
  [relative path to component 3] => an array describing component 3 and its parameters
  [the unique ID of separator 2] => an array describing separator 2
  ...
)

In the above structure:

the unique ID of separator is an arbitrary set of symbols which is unique within all components of the specific module;
relative path to component is the path to the main file of the component relative to the directory containing the file .description.php

Example of file .description.php

Sometimes, additional code is required to be added to the file .description.php. For example, when a list of information blocks or web forms is to be obtained. It is to emphasize that in this case no constrains and limitations are applied to this file. All the available modules and functions of the system can be used in it.

<?
// file 
// /bitrix/modules/iblock/install/templates/iblock/catalog/.description.php

IncludeTemplateLangFile(__FILE__);
if (!CModule::IncludeModule("iblock")) return;

/*************************************************************************
                    Initialise required arrays
**************************************************************************/

// obtain an array of the information blocks types $arIblockType
$rsType = CIBlockType::GetList(array("sort"=>"asc"), array("ACTIVE"=>"Y"));
while ($arr=$rsType->Fetch())
{
    if($ar=CIBlockType::GetByIDLang($arr["ID"], LANGUAGE_ID))
        $arIblockType[$arr["ID"]] = "[".$arr["ID"]."] ".$ar["NAME"];
}

// obtain an array of the information blocks $arIblock
$rsIblock = CIBlock::GetList(
    Array("sort" => "asc"), 
    Array("TYPE" => $arCurrentValues["IBLOCK_TYPE"], "ACTIVE"=>"Y")
    );
while($arr=$rsIblock->Fetch())
    $arIblock[$arr["ID"]] = "[".$arr["ID"]."] ".$arr["NAME"];

// obtain an array of the information blocks properties $arProperty
$rsProp = CIBlockProperty::GetList(
    Array("sort"=>"asc", "name"=>"asc"), 
    Array("ACTIVE"=>"Y", "IBLOCK_ID"=>$arCurrentValues["IBLOCK_ID"])
    );
while ($arr=$rsProp->Fetch())
{
    $arProperty[$arr["CODE"]] = "[".$arr["CODE"]."] ".$arr["NAME"];
}

/***************************************************************************
                    "Product catalog" separator
****************************************************************************/

$arTemplateDescription = Array(
    ".separator" =>
        Array(
            "NAME"        => GetMessage("T_IBLOCK_DESC_CAT"),
            "DESCRIPTION" => "",
            "SEPARATOR"   => "Y",
        )
    );

/***************************************************************************
                    Detail view of catalog element
****************************************************************************/

$arTemplateDescription["element.php"] = array(
    "PARENT"       => ".separator",
    "NAME"         => GetMessage("IBLOCK_ELEMENT_TEMPLATE_NAME"),
    "DESCRIPTION"  => GetMessage("IBLOCK_ELEMENT_TEMPLATE_DESCRIPTION"),
    "ICON"         => "/bitrix/images/iblock/components/cat_detail.gif",
    "PARAMS" => array(
        "IBLOCK_TYPE" => array(
            "NAME"              => GetMessage("IBLOCK_TYPE"),
            "TYPE"              => "LIST",
            "ADDITIONAL_VALUES" => "Y",
            "VALUES"            => $arIblockType,
            "REFRESH"           => "Y"
            ),
        "IBLOCK_ID" => array(
            "NAME"              => GetMessage("IBLOCK_IBLOCK"),
            "TYPE"              => "LIST",
            "ADDITIONAL_VALUES" => "Y",
            "VALUES"            => $arIblock,
            "REFRESH"           => "Y"
            ),
        "ELEMENT_ID" => array(
            "NAME"              => GetMessage("IBLOCK_ELEMENT_ID"),
            "TYPE"              => "STRING",
            "DEFAULT"           => '={$_REQUEST["ID"]}'
            ),
        "SECTION_URL" => array(
            "NAME"              => GetMessage("IBLOCK_SECTION_URL"),
            "TYPE"              => "STRING",
            "DEFAULT"           => "section.php"
            ),
        "LINK_IBLOCK_TYPE" => array(
            "NAME"              => GetMessage("IBLOCK_LINK_IBLOCK_TYPE"),
            "TYPE"              => "LIST",
            "ADDITIONAL_VALUES" => "Y",
            "VALUES"            => $arIblockType,
            "REFRESH"           => "Y"
            ),
        "arrFIELD_CODE" => array(
            "NAME"              => GetMessage("IBLOCK_FIELD"),
            "TYPE"              => "LIST",
            "MULTIPLE"          => "Y",
            "ADDITIONAL_VALUES" => "N",
            "VALUES" => array(
                "NAME"           => GetMessage("IBLOCK_NAME"),
                "PREVIEW_TEXT"   => GetMessage("IBLOCK_PREVIEW_TEXT"),
                "DETAIL_TEXT"    => GetMessage("IBLOCK_DETAIL_TEXT"),
                "DETAIL_PICTURE" => GetMessage("IBLOCK_DETAIL_PICTURE"),
                )
            ),
        "arrPROPERTY_CODE" => array(
            "NAME"              => GetMessage("IBLOCK_PROPERTY"),
            "TYPE"              => "LIST",
            "MULTIPLE"          => "Y",
            "ADDITIONAL_VALUES" => "N",
            "VALUES"            => $arProperty
            ),
        "CACHE_TIME" => array(
            "NAME"              => GetMessage("IBLOCK_CACHE_TIME"),
            "TYPE"              => "STRING",
            "DEFAULT"           => "3600"
            ),
        )
    );
?>

Language files

To include the language files within the file .description.php, the function IncludeTemplateLangFile is used. In the above example, the description file has the following path:

/bitrix/modules/iblock/install/templates/iblock/catalog/.description.php.

The language file is included in it using the instruction:

IncludeTemplateLangFile(__FILE__);

The language file should be one of the following (in priority descending order):

/bitrix/templates/current site template ID/lang/language ID/iblock/catalog/.description.php
/bitrix/templates/.default/lang/language ID/iblock/catalog/.description.php
/bitrix/modules/iblock/install/templates/lang/language ID/iblock/catalog/.description.php

Additional information

Note
The component description requires the following files:

/bitrix/templates/.default/module ID/.description.php

/bitrix/modules/module ID/install/templates/module ID/.description.php

which initialise the variable $sSectionName containing the module name for the drop-down list of modules in the the HTML editor. If this file cannot be found, the corresponding item is not shown in the drop-down list of modules.

If an additional PHP code is required to be added when modifying parameters, the following syntax can be used:
"={...}".

For example:

={$_REQUEST["BID"]}

={(isset($_REQUEST["BID"]) ? $_REQUEST["BID"] : "15")}