Bitrix Framework

Component templates are subdivided into system and user:

• System templates come together with the component and are located in the subfolder templates of the component folder.
• User templates of the component are the templates that have been changed according to the requirements of a specific website. They must be located in the folders of website templates (i.e. in /bitrix/templates/website_template/). When the component template is copied using the system it means that they will be located at the following path: /bitrix/templates/website_template/components/namespace/component_name/template_name.

Component templates are defined by names. Default template is named .default. If no template name is indicated in the component parameter settings, the default template is retrieved. Other templates can have arbitrary names.

Component templates can be folders or files. If the template does not require translation into other languages, own styles, and other resources, such template may be located in a file. Otherwise, the template should be located in a folder.

Each component template is indivisible. If the system template of a component must be changed to fit for a specific website, such a component template must be copied to the website template folder in its integrity.

For example, the component bitrix:catalog.site.selector has the system template dropdown located in the subfolder templates of the component folder. If this component template is to be changed to fit a specific website, the dropdown template folder should be copied into the folder /bitrix/templates/website_template/components/bitrix/catalog.site.selector/ and changed as one deems necessary.

When including a component into a web page, the administrator shall establish which display template, exactly, will be used in this specific case.

Variables Available in the Component Template

The following variables are used in the template:

• $templateFile – a path to the template from the website root, e.g.: /bitrix/components/bitrix/iblock.list/templates/.default/template.php).
• $arResult – an array of component operation results.
• $arParams – an array of input parameters of a component; it may be used to keep track of the set parameters of the template (e.g., displaying full pictures or links).
• $arLangMessages – an array of language messages of the template (not required for php templates).
• $templateFolder - a path to the folder with the template from DOCUMENT_ROOT (e.g., /bitrix/components/bitrix/iblock.list/templates/.default).
• $parentTemplateFolder – a parent template folder. This variable is very convenient to connect additional images or scripts (resources). It should be introduced to form a full path from the template folder.
• $component — a link to the currently invoked component (CBitrixComponent type).
• $this - a link to the current template (object describing the template, CBitrixComponentTemplate type)
• $templateName — the name of the component template (e.g., .default)
• $componentPath - a path to the component from DOCUMENT_ROOT (e.g., /bitrix/components/bitrix/iblock.list)
• $templateData — an array for entry; please note that here the data from template.php can be transferred to the file component_epilog.php, and these data will be sent to cache because the file component_epilog.php is executed with each hit.

Also, within the PHP template, the variables $APPLICATION, $USER and $DB are declared global.

Simple Component Template

The file of a simple component template may contain the following subfolders and files:

• Subfolder /lang where the files of language messages (translations) of the component template are located;
• The file result_modifier.php that is to be connected directly before connecting the component template. This file receives as input the array of component operation results $arResult and the array of component invocation parameters $arParams. This way, it is possible, for example, to change the array of the component operation results to fit a specific template.
• The file style.css determines the styles required for this template.
• The file script.js determines and connects java scripts required for this template. This file may be absent.
• The file .description.php containing the name and description of the template for the visual editor.

Example of file .description.php
<? if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die(); $arTemplateDescription = array( "NAME" => GetMessage("ADV_BANNER_NAME"), "DESCRIPTION" => GetMessage("ADV_BANNER_DESC"), ); ?>

• The file .parameters.php containing a description of additional input parameters of the template for the visual editor.

Example of file .parameters.php

<? if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die(); if (!CModule::IncludeModule("advertising")) return; $arTypeFields = Array("-" =>GetMessage("ADV_SELECT_DEFAULT")); $res = CAdvType::GetList($by, $order, Array("ACTIVE" => "Y"),$is_filtered, "Y"); while (is_object($res) && $ar = $res->GetNext()) { $arTypeFields[$ar["SID"]] = "[".$ar["SID"]."] ".$ar["NAME"]; } $arTemplateParameters = [ "TYPE" => [ "NAME" => GetMessage("ADV_TYPE"), "PARENT" => "BASE", "TYPE" => "LIST", "DEFAULT" => "", "VALUES" => $arTypeFields, "ADDITIONAL_VALUES" => "N", ], "NOINDEX" => [ "NAME" => GetMessage("adv_banner_params_noindex"), "PARENT" => "BASE", "TYPE" => "CHECKBOX", "DEFAULT" => "N", ], "QUANTITY" => [ "NAME" => GetMessage("ADV_QUANTITY"), "PARENT" => "BASE", "TYPE" => "STRING", "DEFAULT" => "1", ], "CACHE_TIME" => ["DEFAULT"=>"0"], ]; if ($templateProperties['NEED_TEMPLATE'] == 'Y') { $templates = array('-' => GetMessage("ADV_NOT_SELECTED")); $arTemplates = CComponentUtil::GetTemplatesList('bitrix:advertising.banner.view'); if (is_array($arTemplates) && !empty($arTemplates)) { foreach ($arTemplates as $template) { $templates[$template['NAME']] = $template['NAME']; } } $arTemplateParameters['DEFAULT_TEMPLATE'] = [ "NAME" => GetMessage("ADV_DEFAULT_TEMPLATE"), "PARENT" => "BASE", "TYPE" => "LIST", "VALUES" => $templates, "DEFAULT" => '', "ADDITIONAL_VALUES" => "N", ]; unset($templateProperties['NEED_TEMPLATE']); }

• The file template.ext is the template proper. The extension ext depends on the type of the templating motor to be connected. The default extension is php. This file is mandatory.
• Any other folders and files containing the resources required for the component template. For example, the image folder containing the images required by the template.

Composite Component Template

A composite component template contains the same folders as a simple component template, plus:

• Templates of simple components that form part of the composite template. These templates are located in the folders of the type /namespace/simple_component_name/ in the composite component template folder.
• Simple components that form part of the composite template are connected in the templates of pages of the composite component.

How the System Searches for the Template

The following search algorithm is used to find a suitable template for a component:

• Everything begins with the folder /bitrix/templates/current_site_template/components/. In this folder, the file or folder with the template name is searched for along the path /component_namespace/component_name/. If there are none, then the availability of the file template_name.ext is searched for, where the ext extension includes all the available extensions of all templating motors established on the website that are checked one by one. If the template is found, the algorithm is ended.
• If no template is found on step 1, the search is performed in the folder /bitrix/templates/.default/components/. The algorithm described in step 1 applies. If the template is found, the algorithm is ended.
• If no template is found in step 2, the search among the system templates (i.e. those supplied with the component) is performed.

Specifics of the search:

• If no template name is set, the template with the .default name is searched for.
• If the template is set as a folder name, then in case of a simple component in this folder the file template.extis searched for, and in case of a composite template - page_name.ext. The ext extension is assumed equal to php first, and then to extensions of other templating motors available on the website.

For example, the component bitrix:catalog.list must be shown using the template table. Let us assume that on the website, in addition to the standard templating motor (php files), the Smarty motor (tpl files) is also available. The system will first check the folder /bitrix/templates/current_site_template/components/bitrix/catalog.list/ to find a file or a folder named table. If there are none, the system will check the aforementioned folder to find the files table.php and table.tpl. If nothing is found, the system will review the folders /bitrix/templates/.default/components/bitrix/catalog.list/ and /bitrix/components/bitrix/catalog.list/templates/.

f the component folder is found, the file template.php is searched for first and if no such file is found, the file template.tpl. is searched for. If the template is set as table/template.php, the indicated file is retrieved at once.

If a simple component is retrieved as a part of a composite component, the simple component template is first searched for within the composite component template, and after that (if not found) in own templates. To make sure this rule works, when calling for simple components within composite components do not forget to indicate the variable $component as the fourth parameter indicating the parent component. I.e. the code for invoking a simple component must look as follows:

$APPLICATION->IncludeComponent("custom:catalog.element", "", array(...), $component);

Template Connection

Only <namespace>, component name, and template name (and parameters of the component itself) must be indicated in the connection code. When processing the code, the core first checks the availability of the component template in the current website template: /bitrix/templates/<site template name>/components/<namespace>/<component name>/<template name>/template.php.

If <namespace> is bitrix it is the folder for templates of standard components. If <namespace> is selected by you <name> for your components is located in /bitrix/components/<name>, it is the folder for the templates of your components.

If no template file is available, the default website template is checked: /bitrix/templates/.default/components/<namespace>/<component name>/<template name>/template.php.

Only after that will the component template be connected from the component folder.

The template is connected by the command:

$this->IncludeComponentTemplate($templatePage = "");

Where $templatePage is the name of the current page for a composite component, and an empty line for a simple component.

Component template connection examples:

1. Let us connect the template of the current composite component for the Section page:

   $this->IncludeComponentTemplate("section");

2. Connect the template of the current simple component:

   $this->IncludeComponentTemplate();

Template Edit

Template editing is one of the ways to get a required component result suitable for site requirements. It's not recommended to edit the system template because , что при первом же обновлении он восстановит свое прежнее состояние. Редактировать и применять можно только пользовательский шаблон.

Copying is done using the command Copy component template with Edit mode enabled.

When copying the template you can specify its application to the component and start its editing.

If you enable the option Edit template you будет осуществлен переход на страницу редактирования шаблона компонента.

Editing can include an action logic, but it's better to move such update to files result_modifier.php and component_epilog.php (located in the template folder) for more complex result.

AJAX handling specifics

Using AJAX mode has its own specifics. For a breadcrumb bar at the page opened via AJAX to have its own name, the component template must have an element with id="navigation". This may not be div, but span, h1, p and etc.

Similarly, title must have an element with id="pagetitle".

Template Example