The how and why of customization

It’s likely, if you have applied for technical support or wrote on the forum with a question like: how do you get it to do this? can I make a... ? - you were told that what you want is not among the standard product features or functionality, but that the problem can be easily solved through customization of a component, template, and so on.

In this post I want to explain what customization in the Bitrix platform is and how to do it correctly – without harming the product and thus website or portal.

First, customization is NOT something that you do with the existing components or scripts. That is, if you are told that you need to customize a component, for example, news.detail, it does not mean that the corrections should be made in the file /bitrix/components/bitrix/news.detail/component.php. What it means, is that you should copy this component and make changes to the copy.

In addition to copying templates and components, there are other ways to alter the product’s standard logic. This is also discussed below.

So, some basic information to start with.

The core of the product are the following directories:

1. /bitrix/modules/ - contains the files of all the modules
2. /bitrix/components/bitrix/ - components included in the product package
3. /bitrix/gadgets/bitrix/ - all gadgets
4. /bitrix/activities/bitrix/ - actions of business processes
5. /bitrix/templates/<standard site (or portal) template>

Scripts in these directories, i.e. the kernel, must NOT be modified! These scripts are updated through the update system. So, if you have make changes in any files in the above directories, the update system will overwrite them, consequently:

1. In the best case, you just lose your changes.
2. There could be problems in the operation of your site: from a decline in performance to a complete stop due to a fatal error, an error in an SQL-query, a recursive function, and so on.
3. Technical support has the right to refuse service in such cases.

Component template customization

To customize a template, copy the default component template to the site template and change it according to your needs.

This is the thing to do if the logic of the standard component is adequate for your purposes, but you need to modify the appearance.

How to do it:

1. Copy the component template to a site template (or the .default folder of the site template) manually or using the options in the interface.
2. Change the template
3. Choose the new template in the component’s parameters (http://www.bitrixsoft.com/help/source/main/help/en/developer/general/component20/10.template_place.php.html).

Note

A single component can have multiple templates, and they can be located in different directories: the directory of the component (standard templates), the current site template, or the .default site template.
Suppose you select a template in the component settings (or do not specify the name of the template – which is equivalent to selecting the component template .default). This component will search for a template first in the current site template, and if nothing is found, in the site template .default, and if there is nothing there either, the directory component.

Customizing a component

To customize a component, copy the standard component in the user name space and modify it as you need.

This is the thing to do if the logic of the standard component needs to be modified slightly to suit your purposes.

How to do it:

1. Copy the component to the user name space.
2. Modify this copy as necessary
3. To include a component using the visual editor or by the method CMain :: IncludeComponent(), for example:
More: http://www.bitrixsoft.com/help/source/main/help/en/developer/general/component20/01.components.php.html

The modification of the result using the component file result_modifier.php

The file result_modifier.php is a tool that modifies the data of the component. A developer should create their own modifier file and it will be called (automatically) before include the component template.
This is used if you want to change the output of the component, but do not want to customize the component and want to continue updates for it.
In this file, you can request additional information and to place it in the array of the component $arResult.
Note: The result_modifier.php file only runs if the template is not cached. It is not possible to establish dynamic properties such as title, keywords, or description.

How to do it:

1. Template is copied to the site template
2. In the new template folder, create the result_modifier.php file with the appropriate coding
3. The file changes the result of the component $arResult for use in the template.
4. Change the component template to your requirements and include the component with this template.
Related links:
http://www.bitrixsoft.com/support/training/course/index.php?COURSE_ID=25&LESSON_ID=1400
 

Event Processing

Sometimes, a developer needs to modify the execution of an API function in some aspect. But if a function is changed manually, these modifications will be lost during the next update session. To enable developers to modify the system logic, an event processing system has been developed. Many API functions call event handlers during their execution.
More: http://www.bitrixsoft.com/help/source/main/help/en/developer/general/technology/events.php.html