Customization of 1C-Bitrix standard component templates

Customizing Templates of Standard 1C-Bitrix Components

Standard 1C-Bitrix components work out of the box, but their appearance almost never matches the design mockup. The first instinct — editing files in /bitrix/components/bitrix/ — leads to losing changes when the core updates. The correct approach: custom component templates in /local/ or in the site template folder.

Customizing Templates of Standard 1C-Bitrix Components

Component template structure

Every component has a templates/ folder containing templates. The .default template is used by default. 1C-Bitrix searches for a component template in the following order:

1. /local/templates/<site_template>/components/<namespace>/<component>/<template>/
2. /local/components/<namespace>/<component>/templates/<template>/
3. /bitrix/templates/<site_template>/components/...
4. /bitrix/components/<namespace>/<component>/templates/<template>/

This means: creating the required folder structure in /local/ and placing an overriding file there is sufficient. The original in /bitrix/ remains untouched.

Creating a custom template

A walkthrough using bitrix:catalog.element — the product card component.

Inspect the original:

/bitrix/components/bitrix/catalog.element/templates/.default/template.php

Create a custom template:

/local/templates/my_site/components/bitrix/catalog.element/.default/template.php
/local/templates/my_site/components/bitrix/catalog.element/.default/style.css
/local/templates/my_site/components/bitrix/catalog.element/.default/script.js

In template.php all variables prepared by the component are available: $arResult, $arParams, $arCurrentValues. Inspect their contents via \Bitrix\Main\Diag\Debug::dump($arResult) or the bitrix:diag.phpinfo component.

Including the template in the component call

<?$APPLICATION->IncludeComponent(
    "bitrix:catalog.element",
    ".default", // template name
    [
        "IBLOCK_TYPE" => "catalog",
        "IBLOCK_ID"   => 12,
    ],
    false
);?>

If a separate template is needed for a specific page or section, create a template with an arbitrary name, for example card_v2, and specify it in the call.

Customizing complex component templates

Complex components (bitrix:catalog, bitrix:news) consist of several included sub-components. The complex component template contains component_epilog.php and subfolders for sub-components.

/local/templates/my_site/components/bitrix/catalog/.default/
    template.php
    component_epilog.php
    bitrix/
        catalog.section/
            .default/
                template.php
        catalog.element/
            .default/
                template.php

This allows overriding the markup for both the section list and the product card within a single catalog template.

result_modifier.php and component_epilog.php

Two files that provide access to component data without overriding its logic:

result_modifier.php — executes after the main component code, before the template. $arResult can be modified here:

// result_modifier.php
if (!empty($arResult['ITEMS'])) {
    foreach ($arResult['ITEMS'] as &$item) {
        $item['PRICE_FORMATTED'] = number_format($item['CATALOG_PRICE_1'], 0, '.', ' ') . ' ₽';
    }
}

component_epilog.php — executes after the template. Used for final operations: setting the page title, adding breadcrumbs, including scripts.

Including CSS and JS in the component template

// In template.php
$this->addCSS($this->GetFolder() . '/style.css');
$this->addJS($this->GetFolder() . '/script.js');

// Or via Asset Manager for file merging
\Bitrix\Main\Page\Asset::getInstance()->addCss($this->GetFolder() . '/style.css');

Timelines