Custom Bitrix parameters: where a standard template breaks
A standard component template is designed for an average case: a standard grid, a fixed set of fields, predictable output logic.
As soon as the client brings non-standard markup or a business rule like "the price depends on the warehouse region, and we hide the stock until a manager confirms," the template can no longer cope.
The developer's first reaction is to add a condition right in the template, the second is to dig into result_modifier.php or the component itself. That is how component template customization begins, which half a year later turns into an unreadable tangle.
Then duplicates appear: a copy of the template for a section, another one for a landing page, a third one for the mobile version — and an edit in one place no longer reaches the others.
At the same time, someone edits the Bitrix core directly because "it's faster that way." Bitrix core edits are the most expensive kind of debt: with the next platform update they get overwritten, and the site's behavior changes without warning.
Rolling back becomes harder because it's unclear which exact edit was holding the required scenario together.
Custom Bitrix parameters solve this differently. Instead of editing the logic in the template, we move what changes into the component settings: the set of fields, the output mode, the data source, the display conditions.
The template stays thin — it only renders what it was passed, while all the variability lives in the parameters and in a separate handler class.
Then the standard template no longer fits — but there's also no need to rewrite it entirely: we extend the built-in mechanism rather than break it.
The practical effect is that platform updates go through without manually sorting out conflicts, and new markup is connected by changing a parameter rather than by editing code.
Below we break down how this is structured and where the line runs between configuration and interference with the core.
What moving logic into component parameters gives you
Moving logic into component parameters is separating "what we show" from "how we show it." The template describes the output structure, while the settings determine which sections, fields, sorting, and limits a particular instance takes.
The same 1C-Bitrix component serves the homepage, catalog, and product page without forking the code for each page.
Platform updates without losing customizations
When logic lives in the body of the template, any update to the core or module wipes out the customizations — you have to manually migrate them again and reconcile the diff.
Parameters are stored in the settings of the component instance, not in the code of the files being updated, so the update proceeds as usual: the customizations stay in place, and the class of failures after an update goes away.
A single template instead of copies
Instead of five nearly identical templates with discrepancies in markup — one template with a set of parameters. An output edit is made in one place and immediately applies to all pages, and the desync between copies disappears as a class.
Speed of edits by a content manager
A content manager changes the number of displayed elements, the sort order, or the set of fields directly in the settings form, without touching the code and without waiting for a developer.
A typical edit is reduced from hours of waiting to a couple of minutes, and the developer stops being a bottleneck on routine changes.
Bottom line: fewer copies, predictable updates, content edits without a release.
Customization methods: comparison of approaches
Choosing a customization method is a choice between speed of implementation and cost of maintenance.
Editing the core solves the task in an hour, but the very first platform update wipes out the changes, and finding them later in someone else's code costs more than doing it from scratch.
A copy of a component template is safer, but when the original template is updated you lose your edits if you didn't keep a diff.
Custom parameters via .parameters.php are a compromise: the logic stays in the core, while the content manager controls the output without a developer.
Below is a comparison of four approaches by the criteria that determine a project's fate a year from now: labor costs for implementation, resilience to updates, who controls the result, and where the scaling limit lies.
| Approach | When it fits | Limitations |
|---|---|---|
| Editing the core | A one-off hotfix, a prototype, no time for architecture | Wiped out on update; incompatible with platform updates; no change history |
| Copy of a component template | Need to change the markup or output logic of a single block | Code duplication; when the original template is updated, edits are lost; the number of files grows |
| Custom component parameters | The content manager must control the output without a developer | Limited to the component's scope; complex logic requires a separate handler |
| Your own component | The task goes beyond typical output, reusability is needed | Higher barrier to entry; documentation and support required; initial development takes longer |
Practice shows: 80% of tasks are handled by custom parameters and a template copy, and only 20% require a custom component. The mistake is to start with editing the core "to be quick," and then spend years dealing with the consequences on every update.
We record the chosen approach in the documentation and in .parameters.php, so that a year later a new developer doesn't have to guess why the code works the way it does.
How we design custom Bitrix parameters
Parameter design starts with an audit: we look at which values are currently hardcoded in the component template, what is duplicated between calls, and where edits in one place break output in another.
The output is a customization map: which parameters already exist, which are needed, and what can be consolidated into a single call instead of copies across pages.
Next, we build the component parameter schema — a flat set with types, default values, and clear names, without nested arrays where a string or list will suffice.
Separately, we define what a parameter controls and what remains on the template side, so that a content manager cannot accidentally break the layout.
- Audit of current customization: inventory of component calls, hardcoded values, and core edits.
- Parameter schema: names, types, default values, and boundaries of responsibility for each.
- Implementation: moving logic out of the template into parameters, backward compatibility with old calls.
- Update check: running the system and module updates, recording overwrites and conflicts.
- Regression: comparing output before and after on key pages, checking cache and SEF URLs.
- Handover: documentation for each parameter with call examples.
- Training: a short session for content managers and developers, covering common mistakes.
The update check is a mandatory stage, not a formality: parameters moved into the template survive a component update, while edits in its files do not. Therefore, everything that must be preserved lives in parameters and in a custom template, not in modified core files.
We hand over the result with documentation: a parameter table, call examples, and a list of what must not be changed without approval. After that, further modifications are made through parameters rather than code edits — support stops depending on a specific developer.
What the client receives
Custom parameters are not "settings in the admin panel" but part of the codebase: if they are not documented, in six months no one will remember which parameter is responsible for what and why exactly this set of values is set.
That is why we hand over the project not as a "working website" but as a set of artifacts that the client's team can live with going forward without us.
- Component parameter files — descriptions in
parameters.php(and related.parameters.phpfor composite components) with types, default values, and hints. A parameter without a description is a parameter that the content manager will either not touch or will break. - Updated templates —
template.php, the template's.parameters.php, and style files where the new parameters are actually used. We separately record which parameters affect the output and which only affect behavior. - Dependency map — a "parameter → template → component → page" map: it shows what will change on the site if a specific value is changed. Without it, editing one parameter unexpectedly breaks the output somewhere else.
- Instructions for the content manager — what can be changed independently, what requires a developer, which values are acceptable. We write it in the editor's language, not in the language of code.
- Update regulations — the procedure for editing parameters, checking on a test environment, and what to do when updating the core and modules so that custom parameters are not overwritten.
- List of extension points — exactly where the standard logic was intervened in, so that during the next enhancement it does not have to be searched for across the entire project.
- Change history — what was added and why at each stage: it helps when investigating incidents and when handing the project over to another team.
Such a set removes the main risk of custom parameters — "it works, but it's unclear how." Describe your task: we will look at the current components and come back with an estimate and a plan for which parameters to extract and which to leave in the code.
Case Study: Catalog with Non-Standard Filters on Bitrix
The client — an industrial equipment supplier — came with a catalog on 1C-Bitrix, where the filter by characteristics worked only on one section.
The other 40+ sections used copies of a single component template: the selection logic, property list, and sorting rules were hardcoded directly into the code.
Any change — a new filter type, an additional selection axis, a change in output order — required modifying the core and manually duplicating the template across all sections.
What It Was Before
Platform updates turned into disruptions: modified core files conflicted with patches, some changes were lost, and the filter on two sections broke after every update.
Engineers spent 6-8 hours on restoration, and the content manager could not add a new characteristic without a developer.
What Was Changed
The filtering logic was moved into custom component parameters: the set of selection axes, property sources, value grouping rules, and output mode became settings rather than code.
One template replaced 40+ copies, and the configuration of each section is set in the parameters when placing the component.
What It Became
Core modifications stopped — updates pass without conflicts, and the time to restore after a platform release dropped from 6-8 hours to zero. A new filter type is added in 15-20 minutes by configuring a parameter instead of 2-3 days of development.
The content manager independently includes new characteristics in the filter without involving engineers.
The number of maintained templates decreased by 40 times, and the share of sections where the filter works properly grew from 5% to 100%.
What is the difference between a component parameter and a module setting?
A component parameter is part of the component call in a template or on a page: it is passed at render time and determines what exactly will be output in a specific place.
A module setting is a value that is stored at the level of the entire project and applies to all pages at once. The difference is fundamental: the first option lives together with the output point, the second — separately from it.
When a parameter is set in the component call, it is visible in the code and versioned along with it. If you copy the call to another page, you get the same settings. If you move the site to another server, the parameters move along with the template, and nothing is lost.
This is what portability of settings means: the configuration is inseparable from the place where it is applied.
A module setting behaves differently. It resides in the database and is tied to a specific installation. When transferring a project between environments, it must be exported separately and re-uploaded, otherwise the behavior will change in the new environment.
If there are dozens of such settings and several environments, desynchronization is almost inevitable — and it is caught only on the production site.
Hence the working rule. Everything related to a specific output point — sorting, filters, set of fields, limits — we keep in component parameters: it is local, transparent, and portable.
Into module settings we move only what is truly common to the entire project: integration keys, addresses of external services, global mode switches.
Mixing the approaches is the most common reason why after a transfer "everything works wrong." A setting that was convenient to put in the module remains on the old environment during migration, while the component on the new one takes the default value.
We separate these levels at the design stage: then the configuration is predictable, and migration between environments does not turn into a separate project.
Technical concerns before starting
Before starting, the same questions almost always come up: whether the customization will "break" the current template, what will happen during a platform update, and who is responsible for the code after handover. Below are short answers to each, without generic wording.
How will custom parameters survive a platform update?
Component parameters are described in a service file and read by the core during rendering — this is a standard mechanism, not a core modification. A platform update does not affect it: the core is updated, while our code remains within the project space.
The only thing we monitor separately is deprecated API calls: if the platform marks a method as deprecated, we proactively migrate the logic to the current one so that the update goes smoothly without surprises.
Is this compatible with the current template and markup?
Yes, the parameters are added on top of the existing template and do not require rewriting it. We move into settings what was previously hardcoded: headings, output order, filtering conditions, display options.
A content editor changes the block's behavior through the settings form without touching the files. If the template is custom, we first review its structure and connect the parameters in a way that does not affect the current markup.
How large is the scope of changes and how long does it take?
The scope depends on the number of blocks and the logic that needs to be moved into settings. A typical set of several parameters for one component is a targeted customization, not a rewrite of a section.
We provide an exact estimate after reviewing the template and the list of what should become configurable: this way the plan includes real changes rather than assumptions.
What about support after handover?
We hand over not only the code but also documentation: which parameters were added, what each of them changes, and how to roll back to the previous behavior.
After that, there are two possible modes — your team maintains the customization themselves using our documentation, or we stay on support and take on platform updates, template compatibility, and new parameters.
We discuss both options before starting so that no "dark" areas of code remain after handover.
Describe the task and the current template — we will get back to you with an estimate of the scope of changes and a work plan.
Let's discuss your customization task
To make the customization review concrete rather than "we'll take a look and let you know," send us the inputs for your task: exactly where custom Bitrix parameters are needed — in which component, template, or module, what it should accept as input, and how it should look in the public section and in the admin panel.
The more specific the source data, the more accurate the work plan and timeline estimate — without the "we'll clarify later, once we start" stage.
What helps us get to an estimate faster:
- task description: which parameter we're adding, what it changes in the component output, who it's intended for — a content manager or a developer;
- current code: the component file,
parameters.php, the template, and if present — a custom module or event handler; - access: a test environment or project copy, the repository, admin panel access to check how the parameters behave;
- constraints: the core version, the site template in use, third-party modules the parameter needs to work with;
- examples: screenshots of "how it is now" and "how it should be," links to similar solutions if any exist;
- operating conditions: load, caching, multi-site setup, backward compatibility requirements.
From there we work through a transparent sequence. First comes the customization review: we look at whether the task can be solved by extending the parameters with standard tools or whether a separate module is needed.
Then we lock in the technical solution and its boundaries — what we change, what we leave untouched, how the parameter will behave when the core is updated.
After that we prepare a work plan with stages and a timeline estimate, get it approved, and only then start making changes in the code.
What you get at the end is not an abstract "we'll do it," but a clear picture: which files will be affected, how the parameter is configured from the admin panel, how the result is verified, and what to do if a rollback is needed.
If risks come up during the review — a conflict with caching, incompatibility with a third-party module — we raise them right away, before the start.
Describe the task in free form and attach whatever you have on hand. We'll come back with an estimate and a work plan — with stages, timelines, and areas of responsibility.