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.

Custom 1C-Bitrix Component Development

How result_modifier.php Solves Pain Points That Core Doesn't

Consider a typical case: a catalog with 50,000 products and SKUs. The standard bitrix:catalog.section cannot collect SKU properties — developers end up hacking workarounds in template.php. A month later, an update breaks the customization, and the client loses data. We've learned from experience: result_modifier.php solves this without core modification. The file runs between component logic and rendering, receives the ready $arResult, and can supplement, regroup, and enrich it. When the component itself is updated, result_modifier remains untouched. Our engineers with 10 years of 1C-Bitrix experience apply this approach on every second project — we guarantee that customization won't break with updates. Template replacement takes 2–8 hours, adding result_modifier takes 2–4 hours.

Typical tasks we handle via result_modifier:

• Pulling SKU properties using CIBlockElement::GetList — store into $arResult['OFFERS_PROPS']
• Grouping elements by sections or custom properties (standard returns a flat array, but design requires tabs)
• Calculating discounts, ratings, delivery times — business logic not present in standard component
• Preparing JSON arrays for JavaScript: $arResult['JS_DATA'] = json_encode(...) directly in modifier, in template only <script>var data = <?=$arResult['JS_DATA']?></script>

Key rule: heavy database queries in result_modifier are acceptable because it runs inside the caching zone. However, in component_epilog.php they are not, and that's fundamental.

Why component_epilog.php Runs Outside Cache and How to Use It

Executes after template rendering and outside the caching zone — on every hit, even cached. Here we place:

• Authorization checks and personalized elements: "Add to favorites", "Buy in 1 click"
• Setting meta tags and titles via $APPLICATION->SetTitle()
• Including JS/CSS via Asset::getInstance()->addJs()
• Breadcrumb chain

Critical: no heavy SQL here. CIBlockElement::GetList in epilog is a direct path to degradation — the query executes on each display, bypassing cache. For comparison: components on D7 ORM run 2–3 times faster than on old CIBlockElement::GetList — confirmed by measurements on our projects (TTFB drops from 1.2 s to 0.4 s).

Component Architecture: What's Included

All on D7 core, ORM classes, and event model. CIBlockElement::GetList — only when D7 ORM doesn't cover the case. Documentation on components — see the official Bitrix documentation. General concept of component architecture — see Wikipedia.

Why Custom Components If Ready Ones Exist in Marketplace

Standard components suffice for 80% of scenarios. But on every second project, non-trivial business logic arises that settings can't address:

• Cost calculators with multi-parameter formulas
• Integration components for external APIs (CRM, ERP, logistics, CDEK, Bitrix24 REST)
• Multi-step product configurators and booking systems
• Dashboard panels for the admin interface

Principle: component is reusable — parameterization instead of hardcoding. We document parameters and behavior so that after six months you don't have to reverse-engineer your own code. Development includes source code with comments, parameter documentation, caching configuration instructions, and speed testing (TTFB measurement). Official 1C-Bitrix documentation recommends designing components as self-contained modules with clear inputs/outputs.

Ajax: D7 Controllers

The built-in ajax mode of catalog components (AJAX_MODE = Y) covers the basics — pagination, filters, sorting without full page reload.

For custom logic — controllers Bitrix\Main\Engine\Controller. Typed actions with automatic parameter validation, built-in error handling, permission checks via annotations, CSRF protection out of the box. Endpoint via ajax.php or custom routing. Response in JSON. Lazy loading of catalog on scroll, inline editing — all via controllers. For details on D7 controllers, refer to the official portal.

How Caching Determines Site Speed and Saves Budget

The difference between 200 ms and 3 seconds is the caching strategy. Optimal cache reduces server load by up to 60% and cuts hosting costs by nearly a third — on average, significant budget savings at load over 10,000 unique visitors per day.

• Managed cache — auto-invalidation on data change. Added a product to an infoblock — cache rebuilt. The most reliable option for content components. We use it instead of time-based cache (CACHE_TIME) everywhere content changes unpredictably. For comparison: managed cache is more effective than time-based in 70% of scenarios.
• Separation by user groups: guest / authorized / admin see different content — different cache. Personal data — strictly in component_epilog, outside cache.
• Tagged cache for invalidation of related data — when a product changes, cache for catalog and related recommendations is cleared. This is especially important when integrating with 1C and Bizproc.
• Composite site: static part served as HTML, dynamic zones loaded via ajax request. TTFB < 100 ms. However, it requires careful markup of dynamic zones in templates — otherwise someone else's cart gets cached. Monitoring hit ratio: if cache misses exceed 30% — configuration is wrong.

Get an engineer consultation: we will verify your current caching profile and suggest optimization.

Common Mistakes in Custom Component Development

• Database queries in component_epilog.php — kills cache
• Heavy business logic in template.php — mixing presentation and logic
• Missing .parameters.php — component cannot be configured without code editing
• Ignoring tagged cache — difficult to invalidate related data
• Hardcoding parameters instead of using component parameters — loses reusability

How We Develop Components: Step-by-Step Process

1. Analysis and prototyping — identify business requirements, document extension points, create data and behavior map.
2. Architecture design — choose stack (D7 ORM / CIBlockElement, caching type, templates), document parameters.
3. Implementation — write class in class.php, template and result_modifier. Complex logic moved to service providers (Bitrix D7).
4. Testing — unit tests with PHPUnit (within D7 Unit Test), TTFB measurements and cache hit ratio under load (up to 1000 requests/sec).
5. Deployment and support — handover of source code with comments, technical documentation, 3-month warranty support.

Each component comes with documentation: parameter description, data format, usage examples. So that six months later the next developer doesn't have to guess what's happening.

What's Included in Component Development (Deliverables)

• Full file stack: class.php, template.php, result_modifier.php (if needed), .parameters.php, .description.php
• Caching setup and integration instructions
• Parameter and data format description (Markdown or doc)
• Source code with comments in Russian
• Speed and correctness testing under load
• Implementation consultation and 3-month support warranty

Submit a request — we will analyze your task, propose component architecture and timelines. Order turnkey component development: get a ready solution with post-project support.

Development Timeline

Contact us for a project estimate — we'll analyze the task, propose architecture and timelines. Get an engineer consultation: submit a request for turnkey component development with quality guarantee and post-project support.