Bitrix Framework

A component stores everything it needs for operation in its folder. That is why they can be easily moved from one project to another.

The component folder may contain the following subfolders and files:

• The help subfolder (outdated from version 11.0) containing component help files. This folder contains subfolders named by the language abbreviation. Each language folder must have a file index.php, which is the main help file for the corresponding language. For example, the path name of the english help file can be /help/en/index.php. The help files should describe the structure of an array in which the component returns data to the template. The subfolder help is optional.
• subfolder install that contains installation and uninstallation scripts. The installation script name is install.php, and the uninstallation script is uninstall.php. The subfolder install is optional.
• subfolder lang containing component messages. From version 11.0 and later it may also contain help folder files.
• subfolder templates in which the component view templates are stored. The subfolder templates is optional if the component has no view templates.
• The file component.php containing logics (code) of the component. This file is responsible for generating an array $arResult from the obtained parameters ($arParams) that will subsequently get to the component template. This file must always be located in the component folder.
• The file .description.php containing the component name, description, and its position in the deduction tree (for WYSIWYG editor). This file must always be located in the component folder. Its absence will not affect the work of the component, but will make it impossible to place the component through a visual editor.
• file .parameters.php, which contains the description of the component input parameters for the visual editor. This file must exist if the component uses input parameters.
• The file .class.php to support OOP components.
• any other folders and files containing the resources required by the component, for example: the folder images.

General Structure of the Component

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?> 
<? 
 //Check and initialize the incoming parameters of a component
 if(component retrieval is in a valid cache) 
 { 
 //Retrieval of the data from the cache
 } 
 else 
 { 
 //Data request and generation of $arResult array according to
 //the structure described in the component help file
 $this->IncludeComponentTemplate(); 
 //Cached retrieval
 } 
?>

Localization Folders

Components and their templates support the option of displaying a user’s messages in multiple languages. Therefore, if a component displays the contents of an infoblock, for example, these contents may be preceded by a string constant. E.g.: “Here you can see the contents of the infoblock.” If the user chooses to go to, for example, the English version of the website, this constant may be automatically displayed in English.

In order to implement this function when displaying string constants, a special function shall be retrieved instead of the constant itself and the identifier of this constant shall be allocated to the special function.

<?echo “Commercial catalog”?>

<?echo GetMessage(“CATALOG”)?>

<?$MESS[“CATALOG”] = “Commercial catalog”;?>

For each language version, a folder with the name of the language shall be created in the lang folder (e.g., de, en, etc.) to host the language message files. A language message file for a component file should have the same name as the file itself. These files contain arrays with constant identifiers as keys and the constants themselves translated into a relevant language as values.

The files should be located according to the same hierarchy with respect to the /lang/anguage_code/ folder where the file is located with respect to a component folder. For example, a language file with English phrases for the /install/uninstall.php file should be located on the path /lang/en/install/uninstall.php. There may be no lang subfolder at all if the component has no language-dependent phrases.

Localization folders are created separately for components and for each template.

Connection of a Component Language File (Translation File)

Language files in a component and all its standard files (component.php, .description.php, .parameters.php) are connected automatically. In other component files language files can be connected using the following command:

$this->IncludeComponentLang($relativePath = "", $lang = False)

where:
$relativePath - is a path to the file from the component folder,
$lang - is the language. If False is submitted, the current language is used.

Example: $this->IncludeComponentLang("myfile.php");

Prompts to Components

Bitrix Framework permits creating prompts to component parameters:

There are two ways to add prompts. The first one you can see in the projects created on the versions earlier than 11.0, and the second one – in subsequent versions. In both cases a file named .tooltips.php must be created.

Before version 11.0

In this case, the file shall be created in the help folder located in the root of the component. In the file, the array $arTooltips shall be created where the component parameters are the keys, and GetMessage() calls are values. For example:

$arTooltips = array(
   'IBLOCK_TYPE' => GetMessage('VWS_COMP_DVL_TIP_IBLOCK_TYPE'),
   'IBLOCK_ID' => GetMessage('VWS_COMP_DVL_TIP_IBLOCK_ID'),
   'SORT_BY1' => GetMessage('VWS_COMP_DVL_TIP_SORT_BY1'),
   'SORT_ORDER1' => GetMessage('VWS_COMP_DVL_TIP_SORT_ORDER1'),
);

Language files for the file .tooltips.php are located, accordingly, in the folder (from the root folder of the component) /lang/language_ID/help/.tooltips.php.

From version 11.0 on

This time, the file shall be created in the language folder named lang. In the file, the array $MESS shall be created, where the component parameters with _TIP suffix are the keys, and the prompts are values. For example:

$MESS["IBLOCK_TYPE_TIP"] = "Select one of the existing information block types in the list";
$MESS["IBLOCK_ID_TIP"] = "Select an information block of the selected type";
$MESS["SORT_BY1_TIP"] = "Defines the sorting field";
$MESS["SORT_ORDER1_TIP"] = "Defines the sorting order";

In this version, there is no need to create a separate lang file with prompts. It is sufficient to save them in the language file .parameters.php (both for the component and for the component template). The prompt format remains the same.

In both case

The prompts for parameters of the component IBLOCK_TYPE, IBLOCK_ID, SORT_BY1 and SORT_ORDER1.

A number of standard parameters (CACHE_TIME, AJAX_MODE, and others) have several prompts. For CACHE_TIME:

• CACHE_TIME - caching time;
• CACHE_TYPE - caching type.

For pager:

• DISPLAY_TOP_PAGER - show pager above the list;
• DISPLAY_BOTTOM_PAGER - show pager below the list;
• PAGER_TITLE - pager element title;
• PAGER_SHOW_ALWAYS - always show pager;
• PAGER_TEMPLATE - pager template name;
• PAGER_DESC_NUMBERING - reverse addressing;
• PAGER_DESC_NUMBERING_CACHE_TIME - caching time of reverse addressing.