Custom Parameters for 1C-Bitrix Components

A typical scenario: a manager asks to change the number of items in a slider or add a filter by date. Without custom parameters, you have to edit the page template, spend an hour, and then another two on testing. On one project, we faced a task: a product slider had to change the number of items depending on the season. The developer spent 4 hours editing the template. After implementing custom parameters, the manager changes the setting themselves in 2 minutes. Result: time for making changes was reduced by 3 times, and template edits ceased to be a bottleneck. On another project, we needed to dynamically change the sorting order of products in a section — after adding the 'Sort type' custom parameter, the manager could choose 'by price', 'by popularity' without involving a developer. Outcome: a 4-fold reduction in time for making changes. More details about component parameters in the Bitrix documentation.

Why .parameters.php is needed

Standard component call with hardcoded parameters:

$APPLICATION->IncludeComponent('custom:product.slider', '', [ 'IBLOCK_ID' => 5, 'COUNT' => 8, 'SHOW_PRICE' => 'Y', ]); 

This works, but when requirements change, the developer must edit the code. With .parameters.php, the manager changes settings themselves through the interface. Custom parameters reduce time for making changes by 3 times compared to editing templates. Time savings on repeated revisions reaches 70%. Experience shows: well-designed parameters are documentation in code that lives with the project.

Parameter types and when to use which

Bitrix supports the following types (TYPE in the parameter array):

For the LIST parameter, you can specify REFRESH => 'Y' so that when a value is selected, the form reloads and new parameters appear — for example, dependent fields. In 90% of cases, standard types are enough; CUSTOM widgets are required in 5% of projects.

Step-by-step creation of a custom parameter

1. Create .parameters.php file in the component folder.
2. Define parameter groups (GROUPS) for logical structure.
3. Describe each parameter: type, name, default value.
4. For dependent parameters, specify REFRESH => 'Y'.
5. Perform normalization in component.php or onPrepareComponentParams.
6. Add CUSTOM widget if standard types are insufficient.

<?php if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die(); use Bitrix\Main\Loader; $arIblockList = ['' => '-- Select information block --']; if (Loader::includeModule('iblock')) { $res = CIBlock::GetList(['SORT' => 'ASC'], ['ACTIVE' => 'Y', 'SITE_ID' => SITE_ID]); while ($ib = $res->Fetch()) { $arIblockList[$ib['ID']] = '[' . $ib['ID'] . '] ' . $ib['NAME']; } } $arSortOptions = [ 'SORT_ASC' => 'By order (ascending)', 'SORT_DESC' => 'By order (descending)', 'DATE_ACTIVE_FROM_DESC' => 'By date (newest)', 'NAME_ASC' => 'By name (A-Z)', 'RAND' => 'Random order', ]; $arLayoutOptions = [ 'grid' => 'Grid', 'list' => 'List', 'slider' => 'Slider', ]; $arComponentParameters = [ 'GROUPS' => [ 'DATA' => ['NAME' => 'Data source', 'SORT' => 10], 'FILTER' => ['NAME' => 'Filtering', 'SORT' => 20], 'DISPLAY' => ['NAME' => 'Display', 'SORT' => 30], 'SEO' => ['NAME' => 'SEO and titles', 'SORT' => 40], 'CACHE' => ['NAME' => 'Caching', 'SORT' => 50], ], 'PARAMETERS' => [ 'IBLOCK_ID' => [ 'PARENT' => 'DATA', 'NAME' => 'Information block', 'TYPE' => 'LIST', 'VALUES' => $arIblockList, 'DEFAULT' => '', 'REFRESH' => 'Y', ], 'SECTION_ID' => [ 'PARENT' => 'DATA', 'NAME' => 'Section (leave empty for all)', 'TYPE' => 'SECTION', 'IBLOCK_ID_VARIABLE' => 'IBLOCK_ID', 'DEFAULT' => '', ], 'ELEMENT_SORT_FIELD' => [ 'PARENT' => 'DATA', 'NAME' => 'Sorting', 'TYPE' => 'LIST', 'VALUES' => $arSortOptions, 'DEFAULT' => 'SORT_ASC', ], 'SHOW_ACTIVE_ONLY' => [ 'PARENT' => 'FILTER', 'NAME' => 'Only active', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'Y', ], 'ACTIVE_DATE_FROM' => [ 'PARENT' => 'FILTER', 'NAME' => 'Active from (date)', 'TYPE' => 'STRING', 'DEFAULT' => '', ], 'LAYOUT' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Display type', 'TYPE' => 'LIST', 'VALUES' => $arLayoutOptions, 'DEFAULT' => 'grid', ], 'COUNT' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Number of items', 'TYPE' => 'STRING', 'DEFAULT' => '12', ], 'COLUMNS' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Columns per row', 'TYPE' => 'LIST', 'VALUES' => ['2' => '2', '3' => '3', '4' => '4', '6' => '6'], 'DEFAULT' => '4', ], 'SHOW_PICTURE' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Show image', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'Y', ], 'PICTURE_SIZE_X' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Image width (px)', 'TYPE' => 'STRING', 'DEFAULT' => '300', ], 'PICTURE_SIZE_Y' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Image height (px)', 'TYPE' => 'STRING', 'DEFAULT' => '200', ], 'SHOW_PRICE' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Show price', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'Y', ], 'CSS_CLASS' => [ 'PARENT' => 'DISPLAY', 'NAME' => 'Additional CSS class for block', 'TYPE' => 'STRING', 'DEFAULT' => '', ], 'SET_TITLE' => [ 'PARENT' => 'SEO', 'NAME' => 'Set page title', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'N', ], 'BLOCK_HEADING' => [ 'PARENT' => 'SEO', 'NAME' => 'Block heading (H2)', 'TYPE' => 'STRING', 'DEFAULT' => '', ], 'CACHE_TYPE' => ['DEFAULT' => 'A'], 'CACHE_TIME' => ['DEFAULT' => 3600], 'CACHE_GROUPS' => ['DEFAULT' => 'N'], ], ]; 

How to add a CUSTOM parameter widget?

When standard types are not enough — for example, you need to select multiple sections or a color palette — the CUSTOM type is used?

On one project, we implemented a color scheme selection widget using a palette: development took 8 hours, but over the next year it saved 20 hours on edits. Development of such a widget on average takes 4-6 hours. Here's how it looks in code:

'SELECTED_SECTIONS' => [ 'PARENT' => 'DATA', 'NAME' => 'Sections (multiple selection)', 'TYPE' => 'CUSTOM', 'DEFAULT' => '', 'JS_EVENT' => 'onCustomParamRender', ], 

The JavaScript handler onCustomParamRender draws a custom HTML widget in the component settings form. This is an advanced feature, rarely used, but sometimes indispensable.

Why parameter normalization is important?

Parameters from .parameters.php arrive in component.php as strings or arrays — they need to be normalized before use:

$arParams['IBLOCK_ID'] = (int) $arParams['IBLOCK_ID']; $arParams['COUNT'] = max(1, min(100, (int) $arParams['COUNT'])); $arParams['COLUMNS'] = in_array($arParams['COLUMNS'], ['2','3','4','6']) ? (int)$arParams['COLUMNS'] : 4; $arParams['SHOW_PICTURE'] = $arParams['SHOW_PICTURE'] === 'Y'; $arParams['SHOW_PRICE'] = $arParams['SHOW_PRICE'] === 'Y'; $arParams['CSS_CLASS'] = htmlspecialchars(trim($arParams['CSS_CLASS'] ?? '')); 

Without normalization, the developer is protected from typos in the component call and from XSS via parameters. Normalization also includes converting dates, ID arrays, and checking the existence of records. Comparison: normalization reduces runtime errors by 40% compared to raw data.

Documenting parameters

For the team that will use the component — documentation in README or directly in .description.php:

$arComponentDescription = [ 'NAME' => 'Product slider', 'DESCRIPTION' => 'Displays a list of products from the selected information block. The LAYOUT parameter controls display type: grid = grid, slider = Swiper carousel.', ]; 

Good documentation reduces the time for a new developer to get up to speed by 30%.

What is included in custom parameters development

• Requirements analysis, parameter structure design
• Creating .parameters.php with groups and dependencies (REFRESH)
• Implementing CUSTOM widgets if needed
• Normalizing input data in component.php
• Configuring caching considering parameters for fast performance
• Documenting in .description.php or README
• Testing on all browsers and Bitrix versions
• Post-implementation support — we'll help with revisions

Our developers' experience: over 10 years in Bitrix development. We guarantee quality and adherence to security standards. If you want components to be flexible and manageable — order custom parameters development. Get a consultation on your project — we'll estimate the effort and suggest the optimal solution.

Deadlines

Contact us — we'll help make components flexible and manageable. Well-designed component parameters are documentation in code. A developer opens .parameters.php and immediately understands what the component does and what values it expects.