Bitrix Framework

Files

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'file',       
                ]           
            ],

        ]                   
    ] 
];

Setting for divided session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated',  // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +           
                'general' => [
                    'type' => 'file',       
                ],
            ],

        ]                   
    ] 
];

Redis

// bitrix/.settings.php
return [
//...        
   'session' => [
       'value' => [
           'mode' => 'default',
           'handlers' => [
               'general' => [
                   'type' => 'redis',  
                   'servers' => [
                       [
                           'port' => 6379,
                           'host' => '127.0.0.1',
                       ],
                       [
                           'port' => 6379,
                           'host' => '127.0.0.2',
                       ],
                       [
                           'port' => 6379,
                           'host' => '127.0.0.3',
                       ],
                   ],
                   'serializer' => \Redis::SERIALIZER_IGBINARY,
                   'persistent' => false,
                   'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
                   'timeout' => null,
                   'read_timeout' => null,    
               ],          
           ],
       ]                  
   ]
];

Cluster storage of session data

Difference from standard configuration: servers have additional options: serializer, persistent, failover, timeout, read_timeout. You can find detailed information about then in the official documentation.

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'redis',   
                    'servers' => [
                        [
                            'port' => 6379,
                            'host' => '127.0.0.1',
                        ],
                        [
                            'port' => 6379,
                            'host' => '127.0.0.2',
                        ],
                        [
                            'port' => 6379,
                            'host' => '127.0.0.3',
                        ],
                        'serializer' => \Redis::SERIALIZER_IGBINARY,
                        'persistent' => false,
                        'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
                        'timeout' => null,
                        'read_timeout' => null,
                    ],
                ],           
            ],
        ]                   
    ] 
];

Setting for separate session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated', // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +  
                'general' => [
                    'type' => 'redis',   
    		    'port' => '6379',
    		    'host' => '127.0.0.1',
                ],           
            ],

        ]                   
    ] 
];

Memcache

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'memcache',   
    		    'port' => '11211',
    		    'host' => '127.0.0.1',
                ],           
            ],

        ]                   
    ] 
];

Cluster storage for session data

When you need to create a cluster from server memcache, you just need to add the servers settings.

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'memcache',   
                    'servers' => [
                        [
                            'port' => 11211,
                            'host' => '127.0.0.1',
                            'weight' => 1, //read more about the weight settings in the memcahe-related documentation
                        ],
                        [
                            'port' => 11211,
                            'host' => '127.0.0.2',
                        ],
                    ],
                ],           
            ],
        
        ]                   
    ] 
];

Setting for separated session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated', // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +  
                'general' => [
                    'type' => 'memcache',   
    		    'port' => '11211',
    		    'host' => '127.0.0.1',
                ],           
            ],

        ]                   
    ] 
];

Mysql

Data is stored in the table b_user_session

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'database',       
                ]           
            ],         
        ]                   
    ] 
];

Setting for separate session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated', // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +  
                'general' => [
                    'type' => 'database',       
                ]           
            ],         
        ]                   
    ] 
];

Handling the sessions

Bitrix24 allows handling sessions as follows:

Session storage in memcached

You need to set the following constants to enable session storage in memcached in the old core/kernel's file /bitrix/php_interface/dbconn.php:

define('BX_SECURITY_SESSION_MEMCACHE_HOST', 'localhost');
define('BX_SECURITY_SESSION_MEMCACHE_PORT', 11211);

Or when using unix-socket:

define('BX_SECURITY_SESSION_MEMCACHE_HOST', 'unix:///path/to/memcached.sock');
define('BX_SECURITY_SESSION_MEMCACHE_PORT', 0);

Then, enable session storage in the database in the proactive protection module. As a result, we get kernel-enabled session storage in memcached.

This method of session storage provides the following advantages:

no need to track the number of old sessions on the highly-loaded project;
option to individuate sessions between servers in cluster;
option to use session that's not waiting for blocking;
option to use virtual sessions.

Session storage in the database has the same advantages as the session storage in memcached. However, database storage is significantly slower. That's why we recommend using memcached for this purpose instead of database.

Non-blocking sessions

One of issues encountered in large-scale projects with multiple ajax queries is the frequently blocked hits of a single user for standby of blocked session. This is especially applicable for Bitrix24 On premise, where in many locations, files attached to entities are passed to user, after checking access permissions for PHP. That's why, a sort of "sequence" can be built due to standby for blocked session. You can enable a non-blocking session by specifying the constant,before connecting the kernel:

define('BX_SECURITY_SESSION_READONLY', true);

After this action, the session is read from memcached or database without waiting for blocking. For example, this feature is used when passing files.

Important: the session won't be recorded when using this constant upon a completed hit. This can cause possible data loss saved within a hit in session.

Virtual sessions

Non-blocking sessions are sufficient for majority of cases. However, in some cases, when we do not need the session altogether, its overly excessive to use a non-blocking session - due to an extra session being created if unavailable. As the result, a large of "trash" sessions are created in case of large amount of unassociated hits. Example of such hits are REST hits.

Virtual session was added to resolve this issue. It works as follows: a session is created in the memory, doesn't wait for blockings and is not saved. To enable it, set the constant, before connecting the kernel .

define('BX_SECURITY_SESSION_VIRTUAL', true);

Please remember that this session type is not saved anywhere. It is used when processing REST queries.

Note: If you have a Bitrix24 On premise, a project with a large number of ajax queries or a high number of files - is passed with access permission check (for example, in blogs, social network, forum). It's better to use session storage in kernel-enabled memcached.

Encrypted cookies

Encrypted [ds]cookies[/ds][di] Cookie - is a text string of information, sent to a browser by a site visitor and which is saved in file on the site visitor device. Usually, a cookie is used to determine a user unique status, last visit time, personal settings, shopping cart unique ID and etc.
[/di] (\Bitrix\Main\Web\CryptoCookie) allows sending data to user, without disclosing contents and without allowing to modify data inside. Available from main 20.5.400.

Configuration

For the kernel to be capable to encrypt the data, indicate crypto_key in the settings /bitrix/.settings.php . By default, it's generated automatically in new distribution packages.

If it's unavailable, add it manually to kernel settings file:

<?php
return [
    //...
    'crypto' => [
        'value' => [
            'crypto_key' => 'mysupersecretphrase',
            //we recommend to set 32-character string from a-z0-9,
        ],
        'readonly' => true,
    ]

    //...
];

Examples

Setting a Cookie

To set an encrypted cookie, just create an object as in the snippet below, into a desired Response:

$cookie = new \Bitrix\Main\Web\CryptoCookie('someName', 'secret value');
\Bitrix\Main\Context::getCurrent()->getResponse()->addCookie($cookie);

Because the cookie is limited in length and data is encrypted and packaged in base64, to avoid data loss, the kernel can create several cookies with encrypted value.

As the result, http response will contain cookie someName with the value -crpt-someName_0. And cookie someName_0 with already encrypted value such as DRMg6jrwXO1aUxTvdyBYyT-3_bCqomI9MMN_enurA5abplMm2OiSlNdu_1zgjbkKT_3D3uT8366.

Reading a Cookie

To get access to encrypted cookies value, it's sufficient to use standard kernel API for cookie handling

$httpRequest = \Bitrix\Main\Context::getCurrent()->getRequest();

echo $httpRequest->getCookie('someName');
//secret value

Kernel automatically determines that cookie is encrypted or not encrypted, unpackages the value and decrypts it. In case the value cannot be decrypted, gets an empty value.

External Authorization

Sometimes it may be necessary to use special checking algorithms and/or external user storage databases for the user’s authorization (verification of login and password). E.g., there is a user database and they must have the possibility to undergo authorization on a CMS managed site. In these cases, all users sometimes may be moved to the CMS database using API functions, but often it is impossible because of the following two reasons:

First. Users’ passwords in the external database are not stored in the open form, only their hash is stored; that is why after migration the users will not be able to undergo authorization due to password inconsistency.
Second. Sometimes a common user database is necessary, with users’ passwords stored on the same remote server and used for verification in several places, including CMS.

In order to resolve such tasks, Bitrix Framework provides for an option to add own external authorization to the standard incorporated authorization system. It takes several steps that we will cover in detail taking an external authorization as an example and using users’ database of a popular forum PHP BB.

For a start, let us create a file, for example, /bitrix/php_interface/scripts/phpbb.php. A class with an external handler will be located in this class, let us call it __PHPBB2Auth:

class __PHPBB2Auth
{
}

In order to have our function invoked during an authorization attempt it is necessary to set the OnUserLoginExternal event handler that will be invoked automatically each time a user enters their login and password, before the built-in check. For this, let us use the AddEventHandler function in the file /bitrix/php_interface/init.php:

AddEventHandler(
     "main", 
     "OnUserLoginExternal", 
     Array("__PHPBB2Auth", "OnUserLoginExternal"), 
     100, 
     $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
);

We have specified our class method __PHPBB2Auth::OnUserLoginExternal as a handler. The OnUserLoginExternal event handler accepts as a parameter a link to an array with fields for the check:

define("PHPBB2_TABLE_PREFIX", "phpbb_");
function OnUserLoginExternal(&$arArgs)
{
    $table_user = PHPBB2_TABLE_PREFIX."users";
    $table_user_group = PHPBB2_TABLE_PREFIX."user_group";
    extract($arArgs);

    global $DB, $USER, $APPLICATION;

    $strSql = "SELECT * FROM ".
              $table_user.
              " WHERE username='".
              $DB->ForSQL($login).
              "' AND user_password='".
              $DB->ForSql(md5($password))."'";
    $dbRes = $DB->Query($strSql);
    if($arRes = $dbRes->Fetch())
    {
        if($arRes['user_active']!='0')
        {
            // user’s name and password are correct
        }
    }
}

Having verified the login and password according to the PHPBB algorithm, an external user must be created in the internal database so that internal objects (news, votes, etc.) could be linked to it. To do so, let us use the method CUser::GetList() with a filter by login and external source code. If there is no such user we will create it, and if such a user exists we will update information about it.

$arFields = Array(
    "LOGIN" => $login,
    "NAME" => $login,
    "PASSWORD" => $password,
    "EMAIL" => $arRes['user_email'],
    "ACTIVE" => "Y",
    "EXTERNAL_AUTH_ID"=>"PHPBB2",
    "LID" => SITE_ID
    );
$oUser = new CUser;
$res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$login, "EXTERNAL_AUTH_ID"=>"PHPBB2"));
if(!($ar_res = $res->Fetch()))
    $ID = $oUser->Add($arFields);
else
{
    $ID = $ar_res["ID"];
    $oUser->Update($ID, $arFields);
}
if($ID>0)
{
   // authorization is permitted
   return $ID;
}

Now we have a user ID in our database and it can be recovered from the handler function to make this user authorized by the system, but a new user will be anonymous, because it is not bound to any group. Let us use the binding in the PHPBB database to transfer it to our database before authorization.

$USER->SetParam("PHPBB2_USER_ID", $arRes['user_id']);
$groups_map = Array(
    /*'PhpBB2 Group ID' => 'Local Group ID',*/
     '2' => '1'
    );

$user_groups = Array();
$dbUserGroup = $DB->Query('SELECT * FROM '.$table_user_group.' WHERE user_id='.$arRes['user_id']);
while($arUserGroup = $dbUserGroup->Fetch())
    $user_groups[] = $arUserGroup['group_id'];

if(count($user_groups)>0)
{
    $arUserGroups = CUser::GetUserGroup($ID);
    foreach($groups_map as $ext_group_id => $group_id)
    {
        if(in_array($ext_group_id, $user_groups))
            $arUserGroups[] = $group_id;
        else
        {
            $arUserGroupsTmp = Array();
            foreach($arUserGroups as $grid)
                if($grid != $group_id)
                    $arUserGroupsTmp[] = $grid;
            $arUserGroups = $arUserGroupsTmp;
        }
    }
    CUser::SetUserGroup($ID, $arUserGroups);
}

That is all. Now the local user account is consistent with the remote one, a user’s code may be recovered, and it will be authorized. Let us tentatively switch off the function "remember me on this computer” if the user has enabled the checkbox, because in this case we will not be able to correctly check the access rights:

$arArgs["store_password"] = "N";
return $ID;

In order to register a new external system authorization check, the event OnExternalAuthList must be handled. Let us add a relevant invocation in the file /bitrix/php_interface/init.php:

AddEventHandler(
     "main", 
     "OnExternalAuthList", 
     Array("__PHPBB2Auth", "OnExternalAuthList"), 
     100, 
     $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
     );

Handler function must return the array from a set of handlers with the fields ID and NAME.

function OnExternalAuthList()
{
    return Array(
        Array("ID"=>"PHPBB2", "NAME"=>"PhpBB2")
        );
}

Now on the user editing page a drop-down list indicating external authorization sources appears. We provide the entire text of the file /bitrix/php_interface/scripts/phpbb.php below. A reverse mechanism is additionally implemented in it: once authorized in our system, a user is automatically authorized in the forum.

<?
define("PHPBB2_TABLE_PREFIX", "phpbb_");

class __PHPBB2Auth
{
    function OnUserLoginExternal(&$arArgs)
    {
        ////////// <settings> ////////////
        $table_user = PHPBB2_TABLE_PREFIX."users";
        $table_user_group = PHPBB2_TABLE_PREFIX."user_group";
        $groups_map = Array(
            /*'PhpBB2 Group ID' => 'Local Group ID',*/
            '2' => '1'
            );
        ////////// </settings> ////////////
        extract($arArgs);

        global $DB, $USER, $APPLICATION;

        $strSql = "SELECT * FROM ".
                  $table_user.
                  " WHERE username='".
                  $DB->ForSQL($login).
                  "' AND user_password='".
                  $DB->ForSql(md5($password))."'";
        $dbRes = $DB->Query($strSql);
        if($arRes = $dbRes->Fetch())
        {
            if($arRes['user_active']!='0')
            {
                $arFields = Array(
                    "LOGIN" => $login,
                    "NAME" => $login,
                    "PASSWORD" => $password,
                    "EMAIL" => $arRes['user_email'],
                    "ACTIVE" => "Y",
                    "EXTERNAL_AUTH_ID"=>"PHPBB2",
                    "LID" => SITE_ID
                    );
                $oUser = new CUser;
                $res = CUser::GetList($O, $B, 
                                      Array("LOGIN_EQUAL_EXACT"=>$login, 
                                            "EXTERNAL_AUTH_ID"=>"PHPBB2"));
                if(!($ar_res = $res->Fetch()))
                    $ID = $oUser->Add($arFields);
                else
                {
                    $ID = $ar_res["ID"];
                    $oUser->Update($ID, $arFields);
                }

                if($ID>0)
                {
                    $USER->SetParam("PHPBB2_USER_ID", $arRes['user_id']);

                    $user_groups = Array();
                    $dbUserGroup = $DB->Query('SELECT * FROM '.
                                              $table_user_group.
                                              ' WHERE user_id='.$arRes['user_id']);
                    while($arUserGroup = $dbUserGroup->Fetch())
                        $user_groups[] = $arUserGroup['group_id'];

                    if(count($user_groups)>0)
                    {
                        $arUserGroups = CUser::GetUserGroup($ID);
                        foreach($groups_map as $ext_group_id => $group_id)
                        {
                            if(in_array($ext_group_id, $user_groups))
                                $arUserGroups[] = $group_id;
                            else
                            {
                                $arUserGroupsTmp = Array();
                                foreach($arUserGroups as $grid)
                                    if($grid != $group_id)
                                        $arUserGroupsTmp[] = $grid;
                                $arUserGroups = $arUserGroupsTmp;
                            }
                        }
                        CUser::SetUserGroup($ID, $arUserGroups);
                    }
                    $arArgs["store_password"] = "N";

                    return $ID;
                }
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"PHPBB2", "NAME"=>"PhpBB2 Board")
            );
    }

    function OnAuthorize(&$arArgs)
    {
        extract($arArgs);

        global $DB, $APPLICATION, $USER;
        $user_id = $USER->GetParam("PHPBB2_USER_ID");
        if($user_id<=0)
            return;
        $table_user = PHPBB2_TABLE_PREFIX."users";
        $table_sessions = PHPBB2_TABLE_PREFIX."sessions";
        $table_config = PHPBB2_TABLE_PREFIX."config";

        $dbConfig = $DB->Query("SELECT * FROM ".
                               $table_config.
                               " WHERE config_name
                                 IN ('cookie_name', 'cookie_path', 'cookie_domain', 'cookie_secure')");
        while($arConfig = $dbConfig->Fetch())
            ${$arConfig['config_name']} = $arConfig['config_value'];

        if (isset($HTTP_COOKIE_VARS[$cookie_name . '_sid']) || 
            isset($HTTP_COOKIE_VARS[$cookie_name . '_data']))
            $session_id = isset($HTTP_COOKIE_VARS[$cookie_name . '_sid']) ? 
                               $HTTP_COOKIE_VARS[$cookie_name . '_sid'] : '';

        $ip_sep = explode('.', $_SERVER['REMOTE_ADDR']);
        $user_ip = sprintf('%02x%02x%02x%02x', $ip_sep[0], $ip_sep[1], $ip_sep[2], $ip_sep[3]);
        $current_time = time();
        $sql =
            "UPDATE ".$table_sessions." SET ".
            "    session_user_id = ".$user_id.", ".
            "    session_start = ".$current_time.", ".
            "    session_time = ".$current_time.", ".
            "    session_page = 0, ".
            "    session_logged_in = 1 ".
            "WHERE session_id = '".$DB->ForSQL($session_id)."' ".
            "    AND session_ip = '".$user_ip."'";

        $r = $DB->Query($sql);
        if($r->AffectedRowsCount()<=0)
        {
            $session_id = md5(uniqid($user_ip));
            $sql =
                "INSERT INTO ".
                $table_sessions.
                "(session_id, session_user_id, session_start, session_time, session_ip, session_page, session_logged_in)".
                "VALUES ('".$session_id."', ".$user_id.", ".$current_time.", ".$current_time.", '".$user_ip."', 0, 1)";
            $DB->Query($sql);
        }

        $sql =
            "UPDATE ".$table_user." SET ".
            "    user_session_time = ".$current_time.", ".
            "    user_session_page = 0, ".
            "    user_lastvisit = ".$current_time." ".
            "WHERE user_id = ".$user_id;

        $DB->Query($sql);

        $sessiondata = Array('userid' => $user_id);

        setcookie($cookie_name.'_data', 
                  serialize($sessiondata), 
                  $current_time + 31536000, 
                  $cookie_path, 
                  $cookie_domain, $cookie_secure);
        setcookie($cookie_name.'_sid',
                  $session_id, 0, $cookie_path, 
                  $cookie_domain, $cookie_secure);
    }
}
?>

The following lines must be added to /bitrix/php_interface/init.php:

<?
AddEventHandler(
    "main", 
    "OnUserLoginExternal", 
    Array("__PHPBB2Auth", "OnUserLoginExternal"),
    100, 
    $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
    );

AddEventHandler(
    "main", 
    "OnExternalAuthList", 
    Array("__PHPBB2Auth", "OnExternalAuthList"),
    100,
    $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
    );

AddEventHandler(
    "main", 
    "OnAfterUserAuthorize", 
    Array("__PHPBB2Auth", "OnAuthorize"),
    100
    );
?>

As an example, here is another script for external authorization – for the Invision Power Board forum:

<?
define("IPB_TABLE_PREFIX", "ibf_");
define("IPB_VERSION", "2");

AddEventHandler("main", "OnUserLoginExternal", Array("__IPBAuth", "OnUserLoginExternal"));
AddEventHandler("main", "OnExternalAuthList", Array("__IPBAuth", "OnExternalAuthList"));

class __IPBAuth
{
    function OnUserLoginExternal(&$arArgs)
    {
        extract($arArgs);

        ////////// <settings> ////////////
        $table_user = IPB_TABLE_PREFIX."members";
        $table_converge = IPB_TABLE_PREFIX."members_converge";
        $groups_map = Array(
            /*'IPB Group ID' => 'Local Group ID',*/
            '4' => '1'
            );
        ////////// </settings> ////////////

        global $DB, $USER, $APPLICATION;

        if(IPB_VERSION == '1')
        {
            $strSql = "SELECT * FROM ".$table_user." WHERE name='".$DB->ForSql($login)."' AND password='".md5($password)."'";
        }
        else
        {
            $strSql =
                "SELECT t1.* ".
                "FROM ".$table_user." t1, ".$table_converge." t2 ".
                "WHERE t1.name='".$DB->ForSql($login)."' ".
                "    AND t1.email = t2.converge_email ".
                "    AND t2.converge_pass_hash = MD5(CONCAT(MD5(t2.converge_pass_salt), '".md5($password)."'))";
        }

        $dbAuthRes = $DB->Query($strSql);
        if($arAuthRes = $dbAuthRes->Fetch())
        {
            $arFields = Array(
                "LOGIN" => $login,
                "NAME" => $arAuthRes['title'],
                "PASSWORD" => $password,
                "EMAIL" => $arAuthRes['email'],
                "ACTIVE" => "Y",
                "EXTERNAL_AUTH_ID"=>"IPB",
                "LID" => SITE_ID
                );

            $oUser = new CUser;
            $res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$login, "EXTERNAL_AUTH_ID"=>"IPB"));
            if(!($ar_res = $res->Fetch()))
                $ID = $oUser->Add($arFields);
            else
            {
                $ID = $ar_res["ID"];
                $oUser->Update($ID, $arFields);
            }

            if($ID>0)
            {
                $USER->SetParam("IPB_USER_ID", $arAuthRes['id']);

                $user_group = $arAuthRes['mgroup'];
                $arUserGroups = CUser::GetUserGroup($ID);
                foreach($groups_map as $ext_group_id => $group_id)
                {
                    if($ext_group_id==$user_group)
                        $arUserGroups[] = $group_id;
                    else
                    {
                        $arUserGroupsTmp = Array();
                        foreach($arUserGroups as $grid)
                            if($grid != $group_id)
                                $arUserGroupsTmp[] = $grid;
                        $arUserGroups = $arUserGroupsTmp;
                    }
                }
                CUser::SetUserGroup($ID, $arUserGroups);
                $arArgs["store_password"] = "N";

                return $ID;
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"IPB", "NAME"=>"Invision Power Board")
            );
    }
}
?>

This script must be connected in /bitrix/php_interface/init.php to become operable.

Mail subsystem

Mail subsystem is the technology used to handle e-mail messages within a site.

The mail system operation includes the following stages:

Creating a mail event type. A mail event type can be created using the function CEventType::Add only.
Creating a mail template. Can be accomplished in the administrative menu Mail templates, as well as using the CEventMessage::Add function.
Creating a mail event. A mail event can be created using the function CEvent::Send only.

When a page finishes execution, the function CEvent::CheckEvents is called automatically. This function is used to accomplish the following main tasks:

select unprocessed mail events from the table b_event;
use the above selected events to generate e-mail messages;
send these messages;
write one of the following values as the send result to the table b_event in the field SUCCESS_EXEC:

CEvent::CheckEvents

Developers can affect sending messages by modifying the following settings of the Main (Kernel) module:

Convert Unix new line symbols to Windows format during email sending
Convert 8-bit characters in the message header
One or comma-separated list of E-mail addresses to receive copies of all the outcoming messages
E-mail address in caption
Send email event and template identifiers in message

Besides the above parameters, the constant ONLY_EMAIL can be used. If initialized, it allows sending all messages only to the specified address or group of addresses.

Example of creating the mail event type:

Add(array(
    "EVENT_NAME"    => "ADV_BANNER_STATUS_CHANGE",
    "NAME"          => "Banner status changed",
    "SITE_ID"       => "en",
    "DESCRIPTION"   => "
        #ID# - banner ID
        #CONTRACT_ID# - contract ID
        #TYPE_SID# - type ID
        "
    ));
?>

Example of creating the mail template:

Add($arr);
?>

Example of creating the mail event:

 124,
    "CONTRACT_ID" => 1,
    "TYPE_SID"    => "LEFT"
    );
CEvent::Send("ADV_BANNER_STATUS_CHANGE", 
             array("de", "en"), $arFields);
?>

Related links:

Balancing queries in cluser

Starting from the main module version 24.0.0 the query balancing system in cluster has been [dw]improved significantly[/dw][di] The previous balancing system system version had any query update interrupting the conveyor process and all queries were submitted to the main (master) database. [/di], optimizing load between servers.

Main updates

The system functions in a standard mode before the first query for data update.
In case of an update query, list of modified tables is registered.
Upon subsequent retrieving queries, the updated tables are checked. If no tables were modified, queries will continue to be processed via slave servers.

Tests demonstrate significant increase of queries, processed by slave servers and minimized errors when handling cluster configuration. This allows for better distribution of queries between servers and reduced load on master server.

Load balancing

Legacy (standard) variant: Master 30 la, Slave 3 la.
New variant: Master 1 la, Slave 50 la.

Now cluster settings allow to redirect 100% of load to slave servers, which significantly increases system performance and effectiveness.

Core D7

Development Purpose is the creation of a new software core at a new technology level while eliminating “layers” of outdated technology.

The compatibility principle to which Bitrix, Inc. must adhere to made it necessary to perform a large scope of work not directly intended to develop Bitrix Framework. It immediately affected the speed and quality of development of the platform itself and implicitly affected the distribution of the company’s products in the market.

Actually, the new core is a new development method. At the same time, all old API continues working in the product. And a new API is added for development in a new style. Gradually the old API must become something like an adaptor that ensures compatibility. And all logic with relevant refactoring must move to a new core.

Technical Requirements

The minimal technical requirements for the product version 18.5.400 (with core D7):

PHP version 7.1.
MySQL version 5.6.

Main Differences from the Old Core

Database
- The following databases are supported: MySQL and NoSQL.
- Abandoning the inefficient driver MSSQL ODBC, only native driver is supported.
- ORM (query builder) with noSQL is used.
Object-Oriented Programming (OOP)
- Strong engagement. All code belonging to a certain area must be concentrated in a single place, in the same class, and in the same class set.
- Components with OOP (class.php) have the possibility to write a more structured component code and a possibility of inheritance.
Development
- Consistent code. All equal queries have the same name, the same sets of parameters, and return unified data. I.e. GetList of users does not differ from GetList of groups of users.
- Support of name spaces.
- New uniform rules of code formatting with strict control at the level of development.
- Abandoning of global variables.
- Support of exceptions.
- Support of new types: date, time, and files. Classes with methods replace unformatted data. The values of these types are objects with formatting methods, etc.
- Class library.
- Unified events. A possibility of modification and integration using handlers.
- Autoload. All system entities are located in previously determined places; accordingly, an autoload is supported without additional actions on the part of the developer.
- Specialized handlers (classes, entities) for different situations – types of applications (http, cli).
- Deferred load of language files. Files from /lang files are not connected simultaneously with a component connection; they are loaded after the first query of a language phrase.
- Object providers for main operations (cache, log).o Object providers for main operations (cache, log).

Core Parameter Setup

Special file

Bitrix Framework has several specific core settings that do not have an edit interface. Such design choice is due to occurrences when settings update or error in them can easily lead to rendering the whole system inoperable (due to database connection setting, caching settings and etc.).

Settings in a Core D7 are entered in the file /bitrix/.settings.php. Please be advised, that in the old core/kernel similar settings were made in the file \bitrix\php_interface\dbconn.php. The file .settings.php differs significantly from the former dbconn.php in terms of structure.

Note: due to the fact that the system uses 2 cores in parallel - old kernel and the new D7, both settings files are used simultaneously. That's is why you must configure both files.

Even if you are using the old kernel's code, the file .settings.php is still must be created. A situation is possible when upon installing the updates, some of the in-built system mechanisms will be re-written to the new core. If this file is not configured correctly, it could lead to system inoperability.

In some cases, the .settings.php file is missing. It can be created automatically, via executing it in [dw]command line[/dw][di]PHP Command line - system tool, allowing to launch arbitrary code on PHP with function calls. [/di]: Bitrix\Main\Config\Configuration::wnc();.

Parameters can be edited via the Configuration class (Bitrix\Main\Config\Configuration).

Note: Some sections of the setting file contain the readonly parameter. This parameter means that these settings will not be amended through API.

In addition, these settings can be specified in the file .settings_extra.php. Basic settings file contains invariable settings, with available API. File .settings_extra.php can contain arbitrary code that changes settings dynamically. Accordingly, it doesn't have API functions.

Starting from the Main module version 24.100.0, the files .settings.php and .settings_extra.php can be replaced in the folder [dw]/local[/dw][di]Core D7 has the user project files moved from the folder /bitrix to the folder /local. This allows isolating updated files of your project from the product folder.[/di], and the file dbconn.php — in the folder /local/php_interface.

Parameter description

Below are parameters that can be modified:

Parameters that may be changed are described below:

cache section

exception_handling section

connections section

root section

pull section

http_client_options section

services section

Cache Section

Responsible for caching settings and permits to set the caching method and its parameters.

Before version 18.5.200, the old record format was as follows:
'cache' => array ( 'value' => array ( 'type' => 'files', ), 'readonly' => false, ),

In the version 18.5.200 the record format was updated simultaneously with the option to use Redis in caching. Presently, both formats are operational, however vendor strongly recommends to use new record format.

Examples of new record format for various caching methods.

Parameter Value

type

The following can be set as values:

memcache
eaccelerator
apc
xcache
files
[dw]redis[/dw][di]From version 18.5.200.[/di]
none

or indicate arrays with values:

class_name - a class implementing ICacheEngine interface,
required_file - an add-on file with a path starting from bitrix or local (if required),
required_remote_file - an add-on file with an absolute path (if required).
extension - attempts to connect extension via extension_loaded. Only when successful, then connects already specified class.

cache_flags

Restriction on caching or updating the ttl. Set keys that include table name and suffixes:

'cache_flags'=>   array(
      'value'=> array(
         "b_group_max_ttl" => 200,
         "b_group_min_ttl" => 100,
      )
   ),

By setting the b_group_max_ttl = 0, administrator restricts caching for this entity. By setting the b_group_min_ttl = 86400, admin expands our TTL for up to 24 hours (if the code contains 3600).

Note: In addition to type there may be additional parameters if a specific caching class requires them.

Note: The memcache settings may also be set in the file /bitrix/.settings_extra.php.

Sample file /bitrix/.settings_extra.php

Base file .settings.php contains invariable settings that have API functions. The file .settings_extra.php may contain arbitrary code that updates settings depending on various factors. Accordingly, this file doesn't contain API for setting updates. Naturally, array with the same base file structure will be returned upon executing this arbitrary code.

Section exception_handling

Responsible for exception handling.

  'exception_handling' => array (
    'value' => array (
      'debug' => false,
      'handled_errors_types' => E_ALL & ~E_NOTICE & ~E_STRICT & ~E_USER_NOTICE,
      'exception_errors_types' => E_ALL & ~E_NOTICE & ~E_WARNING & ~E_STRICT & ~E_USER_WARNING & ~E_USER_NOTICE & ~E_COMPILE_WARNING & ~E_DEPRECATED,
      'ignore_silence' => false,
      'assertion_throws_exception' => true,
      'assertion_error_type' => 256,
      'log' => array (
        'settings' => array (
          'file' => 'bitrix/modules/error.log',
          'log_size' => 1000000,
        ),
      ),
    ),
    'readonly' => false,
  ),

Parameter	Value
debug	The key is responsible for displaying an error on a browser page. Errors should be displayed only at the development or debugging stage. Otherwise, there is a potential risk of information disclosure.
handled_errors_types	This key is intended for setting error types to be caught by the system (not ignored).
exception_errors_types	The key sets error types for which the system gives an exception.
ignore_silence	The key cancels action of the error management operator (@).
log	The key sets error logging parameters. If there is no key, there will be no logging. If set as in the example: 'log' => array ( 'settings' => array ( 'file' => 'bitrix/modules/error.log', 'log_size' => 1000000, ), ), the logging will be made into a file with limited size. If site root contains the file error.php and error printing on screen is enabled, this file will be connected in case of unprocessed exception. If set in a general case, logging can be made to anywhere: 'log' => array( 'class_name' => 'MyLog', // custom log class, must extends ExceptionHandlerLog; // can be omited, in this case default Diag\FileExceptionHandlerLog will be used 'extension' => 'MyLogExt', // php extension, is used only with 'class_name' 'required_file' => 'modules/mylog.module/mylog.php' // included file, is used only with 'class_name' 'settings' => array( // any settings for 'class_name' ), ), The provided example: class_name - custom class, descendant from `\ExceptionHandlerLog`. May not be specified. In this case, uses `\Bitrix\Main\Diag\FileExceptionHandlerLog`. extension - PHP extension, use only jointly with class_name. required_file - enabled file. Used only jointly with class_name. settings - settings for class, specified in class_name
assertion_throws_exception	Enabling support for command `assert`.
assertion_error_type	The key specifies only error types for which the incorrect `assert` throws exception.

Error type must be passed in handled_errors_types, exception_errors_types, assertion_error_type. Error type is a numerical code. For example, parameter exception_errors_types. And what does such record means: E_ALL & ~E_NOTICE & ~E_WARNING & ~E_STRICT & ~E_USER_WARNING & ~E_USER_NOTICE & ~E_COMPILE_WARNING?

First, let's refer to levels of PHP error interpreter. There are specific values and determined constants matching them. In our case, this record means that E_ALL (constant value 2047), is bit-wise and not E_NOTICE, and not E_WARNING and not E_STRICT and not E_USER_WARNING and not E_USER_NOTICE and not E_COMPILE_WARNING. That is E_ALL with exception of previosuly specified constants that define one or the other PHP interpreter error level.

Connections section

Database and other data source connection parameters. The class name and connection parameters are specified.

'connections' => array (
        'value' => array (
            'default' => array (
                'className' => '\\Bitrix\\Main\\DB\\MysqlConnection',
                'host' => 'localhost:31006',
                'database' => 'admin_bus',
                'login' => 'admin_bus',
                'password' => 'admin_bus',
                'options' => 2,
                'handlersocket' => array (
                    'read' => 'handlersocket',
                ),
            ),
            'handlersocket' => array (
                'className' => '\\Bitrix\\Main\\Data\\HsphpReadConnection',
                'host' => 'localhost',
                'port' => '9998',
            ),
        ),
        'readonly' => true,
    ),

Attention: The mysqli extension can be used starting from core version 14.5.2 and higher

'className' => '\\Bitrix\\Main\\DB\\MysqliConnection'.

Also, for this purpose, mysqli extension can be installed via PHP. Additional checks for extension availability are not performed! Mysqli can be enabled separately for the old (dbconn.php) and the new (.settings.php) core D7.

Parameter	Value
options	Checkboxes of persistent connection and deferred connection with the database. Example: Connection::PERSISTENT == 1 Connection::DEFERRED == 2 Their combinations can be recorded via bit operations. Example 3 - both PERSISTENT and DEFERRED.
handlersocket	The key specifies which connection must be used for read (read key). Connection must be created, where class, host and port are specified. The example of code above, 'read' parameter is specified with the handlersocket value. Below is the description for the handlersocket connection.
className	Class name, that receives the result of handling the specific database type.
host	host name, where the database is located; can be specified with the port
database	database name
login	database user login
password	database user password

Note:
Several databases can be handled within the ORM.
To use the handlersocket connection, the HSPHP - PHP HandlerSocket client library must be installed

Root section

General settings are located in the root section.

Parameter	Value
disable_iconv	Restricts the use of iconv library. Equivalent of the BX_ICONV_DISABLE constant in the old core
logger	Loggers, implementing PSR-3 interface. Details.

Pull section

This section is specifically required only for hosting partners (for deployment automation). For the rest, its recommended to use the setup via administrative control panel interface.

'pull' => Array(
       'value' =>  array(
           'path_to_listener' => "http://#DOMAIN#/bitrix/sub/";,
           'path_to_listener_secure' => "https://#DOMAIN#/bitrix/sub/";,
           'path_to_modern_listener' => "http://#DOMAIN#/bitrix/sub/";,
           'path_to_modern_listener_secure' => "https://#DOMAIN#/bitrix/sub/";,
           'path_to_mobile_listener' => "http://#DOMAIN#:8893/bitrix/sub/";,
           'path_to_mobile_listener_secure' => "https://#DOMAIN#:8894/bitrix/sub/";,
           'path_to_websocket' => "ws://#DOMAIN#/bitrix/subws/",
           'path_to_websocket_secure' => "wss://#DOMAIN#/bitrix/subws/",
           'path_to_publish' => 'http://127.0.0.1:8895/bitrix/pub/',
           'nginx_version' => '3',
           'nginx_command_per_hit' => '100',
           'nginx' => 'Y',
           'nginx_headers' => 'N',
           'push' => 'Y',
           'websocket' => 'Y',
           'signature_key' => '1111111111',
           'signature_algo' => 'sha1',
           'guest' => 'N',
       ),
   ),

Example of section code and parameters table

Parameter	Value
path_to_listener	path to connect to server (http) to receive commands
path_to_listener_secure	path to connect to server (https) to receive commands
path_to_modern_listener	path to connect to server for modern web browsers (http) to receive command
path_to_modern_listener_secure	path to connect to server for modern browsers (https) to receive commands
path_to_websocket	path to connect to server for modern browsers with socket support (http) to receive commands
path_to_websocket_secure	path to connect to server for modern browsers with web-socket support (https) to receive commands
path_to_publish	path to publish commands from the server
path_to_publish_web	path to publish commands from the web browser (http)
path_to_publish_web_secure	path to publish commands from the web browser (https)
nginx_version	queue server version
nginx_command_per_hit	number of channels to his which the same data will be sent per hit
nginx	enables the queue server
nginx_headers	allows to send special headers
push	enables the queue server
websocket	activates the web-sockets
signature_key	secret signature key for messages
signature_algo	signature encryption algorithm
guest	enables module active status for guests
enable_protobuf	enables new format for messages
limit_max_payload	maximum size of a message in bytes
limit_max_messages_per_request	maximum number of messages per hit
limit_max_channels_per_request	maximum number of channels per hit

Http_client_options section

This section specifies options by default for the Bitrix\Main\Web\HttpClient.

[ICO_NEW data-adding-timestamp="1706700990"]

Starting from main 23.0.0 HttpClient now supports PSR-18. In addition to PSR, client works in legacy mode, supports queues with asynchronous queries and CURL.

[/ICO_NEW]

Parameter	Value
redirect	true by default, execute redirect
redirectMax	maximum number of such redirects (by default: 5)
waitResponse	if true - wait for response (by default), otherwise - return the response immediately
socketTimeout	response timeout period in seconds (by default: 30)
streamTimeout	stream timeout in seconds (by default: 60)
version	version http - 1.0 or 1.1 (by default: 1.0)
proxyHost / proxyPort / proxyUser / proxyPassword	parameter group to setup a proxy
compress	if true, sends Accept-Encoding: gzip
charset	encoding for the object body (is used in the header field for the Content-Type request for POST and PUT)
disableSslVerification	if true, ssl certificates verification will not be performed

Config example:

  'http_client_options' =>
   array (
     'value' =>
        array (
         'redirect' => true,//execute redirects, if required
         'redirectMax' => 10,//but not more than 10
         'version' => '1.1'//work via the http 1.1 protocol 
        ),
     'readonly' => false,
   ),

You can check if your settings are correct as follows:

use Bitrix\Main\Config\Configuration;
print_r(Configuration::getValue("http_client_options"));

Your array should be displayed.

services section

This section is intended for registering services. Find more details in the lesson [ds]Service Locator[/ds][di]Service locator is a design template for convenient handling of application services. Instead of creating specific services directly (via new) service locator is responsible for creating and finding services.

Learn more ...[/di]

Connection to Redis, Memcache

Add a titled connection into connections section to create a connection inside bitrix/.settings.php settings file.

Redis

Ensure that you have installed Redis extension for working via PHP.

Standard connection:

 'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.redis' => [
        'className' => \Bitrix\Main\Data\RedisConnection::class,
        'port' => 6379,
        'host' => '127.0.0.1',
        'serializer' => \Redis::SERIALIZER_IGBINARY,
      ],
      'custom2.redis' => [
        'className' => \Bitrix\Main\Data\RedisConnection::class,
        'port' => 6379,
        'host' => '127.0.0.4',
        'serializer' => \Redis::SERIALIZER_IGBINARY,
      ],
    ],
    'readonly' => true,
  ]

You can find additional information about serializer config variants in the official documentation.

Cluster

When creating cluster from redis servers, just add servers config.

'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.redis' => [
        'className' => \Bitrix\Main\Data\RedisConnection::class,
        'servers' => [
            [
                'port' => 6379,
                'host' => '127.0.0.1',
            ],
            [
                'port' => 6379,
                'host' => '127.0.0.2',
            ],
            [
                'port' => 6379,
                'host' => '127.0.0.3',
            ],
        ],
        'serializer' => \Redis::SERIALIZER_IGBINARY,
        'persistent' => false,
        'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
        'timeout' => null,
        'read_timeout' => null,
      ],
    ],
    'readonly' => true,
  ]

Additional information about configurations for variants serializer, persistent, failover, timeout, read_timeout can be found in the official documentation.

Use

To get a connection instance, you may query the connection name using the method \Bitrix\Main\Application::getConnection.

/** @var \Redis $redisConnection **/
$redisConnection = \Bitrix\Main\Application::getConnection('custom.redis')->getResource();
$redisConnection->setnx('foo', 'bar');

Memcache

Ensure that you have installed Memcache extension for working via PHP.

Standard connection

'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.memcache' => [
        'className' => \Bitrix\Main\Data\MemcacheConnection::class,
        'port' => 11211,
        'host' => '127.0.0.1',
      ],
      'custom42.memcache' => [
        'className' => \Bitrix\Main\Data\MemcacheConnection::class,
        'port' => 6379,
        'host' => '127.0.0.4',
      ],
    ],
    'readonly' => true,
  ]

Cluster

When creating cluster from memcache servers, just add servers config.

'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.memcache' => [
        'className' => \Bitrix\Main\Data\MemcacheConnection::class,
        'servers' => [
            [
                'port' => 11211,
                'host' => '127.0.0.1',
                'weight' => 1, //read more about weight config in the memcahe documenation
            ],
            [
                'port' => 11211,
                'host' => '127.0.0.2',
                'weight' => 1, //read more about weight config in the memcahe documenation
            ],
        ],
      ],
    ],
    'readonly' => true,
  ]

Use

To get a connection instance, query connection name using the method \Bitrix\Main\Application::getConnection.

/** @var \Memcache $memcacheConnection **/
$memcacheConnection = \Bitrix\Main\Application::getConnection('custom.memcache')->getResource();
$memcacheConnection->set('foo', 'bar');

SMTP server local settings

Bitrix24 On-premise editions Main module version 21.900.0 has a new SMTP option allowing to organize dedicated email streams.

General information

How emails are sent fr om site/instance

For Bitrix24 On-premise, user calls a global function bxmail, triggering standard PHP mail function, wrapping an email with headers. After that, mail function queries your internal infrastructure (depending on your [ds]configuration[/ds][di] Bitrix Framework requires setup for sending and receiving emails. There are three options for sending emails:

- via local sendmail or postfix (when site uses Linux);

- via third-party SMTP server without authentication (for Windows);

- via third-party server with authentication by replacing email sender function.[/di]: postfix, sendmail or any custom solution, operating based on queues, sending all emails via mail function).

All emails (email campaigns and single emails, CRM emails, password restoration emails, workflows, etc.) are included into a single stream.

Using new local SMTP server settings you can configure dedicated streams as per custom requirements.

Advantages of sender's SMTP server

dedicated streams;
use of [dw]aliases[/dw][di] Aliases are additional mailbox names. They are used to assign additional names to a single mailbox located at your domain. For example, you have a mailbox mysite@example.com. You can add an alias marketing<mysite@example.com> for marketing department. After this action, users receiving an email from marketing department will see only marketing as a sender.

When users respond to this email, their reply is sent to an actual mailbox mysite@example.com. [/di] (alias);
simple setup;
debugging option;
option to send on hits;
option to maintain open connection (useful for bulk mail).

Enabling SMTP server

To enable sender's SMTP server in Bitrix24 On-premise editions, you need to edit the file [ds]/bitrix/.settings.php[/ds][di] Bitrix Framework has a variety of kernel/core settings that do not have visual UI for editing. This is due to updated settings or an error can easily cause the complete system to malfunction (database connection settings, cache settings and etc.).

Learn more...[/di], by adding the corresponding code:

return [
	//…
	'smtp' => [
		'value' => [
			'enabled' => true,
			'debug' => true, //optional
			'log_file' => '/var/mailer.log' //optional
		]	 
	]
];

Important! Extra caution is advised when editing the .settings.php file: a single error can easily cause the complete system to malfunction.

Settings parameters:

enabled – enabling the SMTP server for the sender;
debug – optional parameter (disabled by default). Enable it if you want to see the complete interaction process with SMTP servers;
log_file – optional parameter. Can indicate a file for collection of logs, by entering full path to file (this file requires access). By default, project/site directory already contains the file mailer.log with all logs incoming logs.

SMTP connection setup

SMTP connection can be configured by two methods:

When creating new email message, [dw]add a sender[/dw][di] [/di], click on the link [dw]SMTP server[/dw][di] [/di] and complete the displayed config fields for connecting an SMTP server:
- enter name and email;
- indicate SMTP server sender's visibility: for you only or visible for all users;
  Note: Each employee can connect a dedicated SMTP server.
- indicate email server;
- enter a port (mostly three values are used: 25, 465, 587);
- indicate [dw]maximum daily message limits[/dw][di] Various email services (Google, Yahoo, etc.) have different limits on the number of sent emails (most frequently its the lim it on the number of emails sent per 24 hours). With this option enabled, Bitrix24 will maintain statistics on the number of dispatched emails and issue errors, when limits are reached. [/di];
- enter login and password for connected SMTP server.
Similar form for connecting SMTP server can be completed at the site's Control panel at Settings > System settings > Email and SMS events > SMTP settings, by clicking on the button Add SMTP connection:

Note: Currently, daily message limits config is not available for SMTP connections added inside the Control panel.

Are the settings described above connected with SMTP settings at the Bitrix24 Virtual Appliance?

SMTP server settings described in this lesson are not associated with [ds]BitrixVM SMTP settings[/ds][di] Complete the following actions to configure SMTP client:

1. Go to the main menu 6. Configure pool sites > 4. Change e-mail settings on site and enter email host name

Learn more...[/di].

Example: BitrixVM site has a configured Gmail [ds]via BitrixVM menu[/ds][di] This lesson contains some examples of email services employed at BitrixVM.

Learn more...[/di]. Add new SMTP connection for Yahoo.com via site administrative section. Now, the From field in a new email or email campaign has a selection of two email services: Gmail and Yahoo. Depending on which service is selected, system sends emails either using Bitrix Virtual Appliance or Bitrix24 core.

Can there be conflicting email duplication in case SMTP has been configured both locally and on the virtual appliance?

No, settings won't clash or emails won't duplicate. When sending an email the system checks, if there is an active smtp parameter in the file /bitrix/.settings.php:

if such such parameter exists, email will be sent via local SMTP;
if such parameter doesn't exist, an email will be sent using server functionality via [ds]msmtp[/ds][di]For SMTP client setup, execute the following:

1. At the main menu, go to 6. Configure pool sites > 4. Change e-mail settings on site and enter the host name to configure email dispatch

Learn more...[/di].

Name Spaces

Name spaces

The notion of name spaces permits giving system elements clearer names, getting rid of numerous name prefixes, and also avoiding potential conflicts. All classes delivered in a standard installation package must be located in the Bitrix name space that does not overlap either with PHP or with partner implementations. Each standard module determines its subspace in the Bitrix name space which coincides with the module name. For example, for the forum module Bitrix\Forum will be the name space, and for the main module – Bitrix\Main.

Note. For partner classes, the namespace can be as follows:

namespace Asd\Metrika;  
 
class CountersTable extends Entity\DataManager  
{  
   ....

This means that this class (in /lib/) belongs to the module asd.metrika and it can be addressed as follows (after the indicated module is connected):

\Asd\Metrika\CountersTable::update();

The class itself is located in the file asd.metrika/lib/counters.php.

If necessary, a module may organize subspaces inside its name space. For example, Bitrix\Main\IO, Bitrix\Forum\Somename\Somename2. But this option should be used only if it is justified for the organization of a correct architecture of this module.

Naming Rules

Name spaces must be named in “UpperCamelCase.”
Names cannot contain any symbols but for Latin letters.
Class name must be a noun. Unnecessary acronyms and abbreviations should be avoided.

Examples:

namespace Bitrix\Main\Localization;
namespace Bitrix\Main\Entity\Validator;

Abbreviations that are not generally accepted (in Bitrix Framework) cannot be used.

Attention! The examples that are provided does do not mention name spaces. It make the text more readable and easier to comprehend. Prior using the examples provided in the documentation, a name space must be added.

It ca be done as follows:

By using PHPdoc;
By using IDE;
additionally, the documentation context usually clarifies which class is described.

Full address line can be abridged. Instead \Bitrix\Main\Class::Function() you can specify Main\Class::Function().

Synonyms also can be used instead of long name spaces. To do it, use is inserted. For example, the following long structure is available:

\Bitrix\Main\Localization\Loc::getMessage("NAME");

To abridge it, declare a synonym at the start of the file and use an abridged variant of the call afterwards:

use \Bitrix\Main\Localization\Loc;
...
Loc::getMessage("NAME");

Related links:

PHP: name spaces (PHP documentation).

Modules in D7

System modules (both standard and downloaded from Bitrix24 Marketplace) are located in the bitrix/modules system folder. User modules can be located in the folder /local/modules (Third-party developer modules may be located in different folders)]. Such difference allows developers to conveniently organize version control for their development products and maintain continuous updates using the standard update system.

Module's API (classes, logic) are located in the module's subfolder [dw]/lib[/dw][di]This folder is optional if your class doesn't have its own methods.[/di]. For example, Main module path can be as follows: bitrix/modules/main/lib. The same folder is used for connecting API when specific rules are satisfied:

Class files must be titled in lower case, with class name equal to file name. For example: /lib/myclass.php.
Files must contain a correct namespace. Example: when module is connected as follows:
Loader::includeModule('company.shotname');
the class must have a namespace: namespace Company\Shotname.
Corresponding method must be connected where such module classes are used in the Control Panel.

Exceptions

The new core uses the mechanism of exceptions.

Exception case (when an exception may be given) is an atypical situation when it makes no sense to continue the performance of the basic algorithm.

Examples

If a user has sent a form with an empty Name field, it is not an exception case. It is a regular expected case that must be handled appropriately.

But if in case of API method invocation in order to change an infoblock element an empty element id was specified, it is an exception case. It is unexpected and it makes no sense to continue changing the element.

If the method is waiting for the user id and you transmit a line, it is an exception, because the method does not know what to do with the line in this case.

If the GetList method accepts the timestamp filter, and developer has written “tymestamp,” it will be an exception.

Exception Hierarchy

Available exceptions have a hierarchy. It handles exceptions, shows the activated exceptions, which allows to take appropriate actions. The general hierarchy logic is as follows:

\Exception
   Bitrix\Main\SystemException         - basic class of all system exceptions
      Bitrix\Main\IO\IoException         - basic class of all exceptions of file input-output
         Bitrix\Main\IO\FileDeleteException   - exception in case of file deletion
         Bitrix\Main\IO\FileNotFoundException   - absence of a required file
         Bitrix\Main\IO\FileOpenException   - exception in case of file opening
         Bitrix\Main\IO\InvalidPathException   - invalid path
         Bitrix\Main\IO\FileNotOpenedException - file not opened 
      Bitrix\Main\Config\ConfigurationException   - configuration error
      Bitrix\Main\Security\SecurityException      - security error
      Bitrix\Main\Security\Sign\BadSignatureException  - signature error exception.
      Bitrix\Main\ArgumentException      - basic class of exceptions associated with incoming parameters of methods
         Bitrix\Main\ArgumentNullException   - parameter must not be left empty
         Bitrix\Main\ArgumentOutOfRangeException   - parameter outside a permitted range
         Bitrix\Main\ArgumentTypeException   - inadmissible type parameter
      Bitrix\Main\DB\DbException      - basic class for database exceptions
         Bitrix\Main\DB\ConnectionException   - exception during connection
         Bitrix\Main\DB\SqlException      - exception during performance of a query
      Bitrix\Main\NotSupportedException   - is invoked if the functionality is not supported
      Bitrix\Main\NotImplementedException   - is invoked if the functionality must be supported but is not implemented so far
 Bitrix\Main\ObjectPropertyException - is invoked when the object properties are invalid
 Bitrix\Main\ObjectNotFoundException - is invoked when object does not exist 
 Bitrix\Main\ObjectException - is invoked if object cannot be created.  
 Bitrix\Main\LoaderException      - exception in loader

Bitrix\Main\SystemException is the basic class for all system exceptions; all the rest of exceptions are inherited from it. This class re-defines the constructor for the \Exception system class. If the system class receives the message and error code on input:

<?php
public function __construct($message = null, $code = 0, Exception $previous = null);

the constructor Main\SystemException additionally receives the file with a thrown exception and a number of string:

<?php
public function __construct($message = "", $code = 0, $file = "", $line = 0, \Exception $previous = null);

Thrown exception must have the most suitable type possible.

If your method creates an exception, it must be described in the method phpDoc.

In Bitrix Framework, it is done as follows:

 /**
     * Searches connection parameters (type, host, db, login and password) by connection name
     *
     * @param string $name Connection name
     * @return array|null
     * @throws \Bitrix\Main\ArgumentTypeException
     * @throws \Bitrix\Main\ArgumentNullException
     */
    protected function getConnectionParameters($name) {}

Ignoring exceptions

Sometimes, an occurred error must not interrupt execution of a script. Such situation can be exemplified by the operation of CDN module administration page.

If the CDN module is enabled, the traffic data is displayed at the top of the page. Its code looks as follows:

$cdn_config = CBitrixCloudCDNConfig::getInstance()->loadFromOptions();
$APPLICATION->SetTitle(GetMessage("BCL_TITLE"));
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");
if (is_object($message))
	echo $message->Show();

if (CBitrixCloudCDN::IsActive())
{
	try
	{
		if ($cdn_config->getQuota()->isExpired())
			$cdn_config->updateQuota();

		$cdn_quota = $cdn_config->getQuota();
		if ($cdn_quota->getAllowedSize() > 0.0 || $cdn_quota->getTrafficSize() > 0.0)
		{
			CAdminMessage::ShowMessage(array(
				"TYPE" => "PROGRESS",
				"DETAILS" => ''.GetMessage("BCL_CDN_USAGE", array(
					"#TRAFFIC#" => CFile::FormatSize($cdn_quota->getTrafficSize()),
					"#ALLOWED#" => CFile::FormatSize($cdn_quota->getAllowedSize()),
				)).'#PROGRESS_BAR#',
				"HTML" => true,
				"PROGRESS_TOTAL" => $cdn_quota->getAllowedSize(),
				"PROGRESS_VALUE" => $cdn_quota->getTrafficSize(),
			));
		}
	}
	catch (Exception $e)
	{
		CAdminMessage::ShowMessage($e->getMessage());
	}
}

The code above shows that if CDN is active, the progress bar with the displayed traffic data is created. However, if an error occurs during execution of this code, an exception will be thrown. This exception will be caught, because all the code is located in try and the branch will be executed after catch, where the error message is displayed via the standard function. The script execution will not be interrupted.

Code Writing Rules

The quality of a program begins with the quality of the source code. The fundamental factor for quality of source code is its readability and clarity. Formalized rules are necessary to write code which will be readable and understandable.

The rules for formatting code must be uniform throughout the entire project. It is highly desirable for the rules to be similar from project to project.

Note: The code formatting rules for core D7 are somewhat different from the code formatting rules for old core.

Source Code Formatting
Naming Conventions
Comments
- PHPDoc
Other
- Magic numbers
- Automatic formatting tools
  - php_beautifier

1. Source Code Formatting

1.1. Text Structure Rules

1.1.1. Line Length

Avoid typing lines whose length exceeds 120 characters. If a line spans beyond that limit, use the line wrapping rules described below.

1.1.2. Line Wrapping Rules

If a line length exceeds 120 characters, the following wrapping rules apply:

wrap lines after the comma or before the operator;
the wrapped line must be indented by one tab;
use UNIX line ends.

Example 1: The code

$arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD, $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

needs to be wrapped as follows:

$arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD,
     $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

Example 2: The code

if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&$TYPE=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))

needs to be wrapped as follows

if (COption::GetOptionString("main", "new_user_registration", "N") == "Y")
     && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
     && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true)

1.1.3. Spaces And Tabs

Use tabs for indentation. Using spaces for indentation is forbidden for the following reasons:

with tabs, any developer can configure his or her text editor to show the desired tab length;
using tabs makes file size smaller;
if both tabs and spaces are used for indentation, the originally intended text formatting is likely to be damaged if a different tab size is used in a text editor.

1.1.4. Scopes And Code Blocks

The code block contents must be indented by one tab. The code block contents must not be on the same line as the controlling statement.

Example:

function func()
{
     if (condition)
     {
          while (condition2)
          {

          }
      }
}

1.1.5.Rules for placing braces

Opening braces must be place under a corresponding operator and on the same indent with it. Closing braces must be placed under the corresponding opening braces.

Example:

if ($condition)
{
   ...
}

1.1.6. Using the ternary operator "?:"

Conditions must be enclosed in parentheses, and thus separated from the rest of the code. As much as possible, actions that occur under these conditions should be simple functions. If an entire branched block reads poorly, then it is worth replacing it with if/else.

Example:

(condition ? funct1() : func2());

1.2. Expressions And Statements

1.2.1. Expressions

One line must contain only one expression.

Example. This expression is formatted incorrectly:

$a = $b; $b = $c; $c = $a;

Rewrite it like this:

$a = $b;
$b = $c;
$c = $a;

1.2.2. The statements if, else, while etc.

Use one of the following two formatting rules depending on the statement length.

if a controlled code block contains only one statement, use the following form:

if (expression)
     statement 1;
else
     statement 2;

if at least one controlled code block contains multiple statements, use braces:

if (expression)
{
     statement 1;
}
else
{
      statement 2; 
      statement 3;
}

The rule Scopes And Code Blocks must be obeyed when writing multiple statements: they must be indented by one tab off the controlling statement. The braces must exist on new lines on the same level as the controlling statement.

Example. This code:

if ($a == 0) $a = 10;
else{
$a = 5;
$b = 10;}

must be reformatted like this:

if ($a == 0)
{
  $a = 10;
}
else
{
  $a = 5;
  $b = 10;
}

1.2.3. Compound Expressions

Compound expressions must be split in multiple lines according to rules described in “The statements if, else, while etc.”.

For example, consider the following code:

 if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&
     $TYPE=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))

Make it readable by sticking to the formatting rules:

if (COption::GetOptionString("main", "new_user_registration", "N") == "Y"
     && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
     && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true))
{
}

It is recommended that you split an extremely complex expression into several simple lines of code.

For example, the code

if((!(defined("STATISTIC_ONLY") && STATISTIC_ONLY && substr($APPLICATION->GetCurPage(), 0,
     strlen(BX_ROOT."/admin/"))!=BX_ROOT."/admin/")) && COption::GetOptionString("main", "include_charset", "Y")=="Y"
     && strlen(LANG_CHARSET)>0)

is definitely more readable when written like this:

$publicStatisticOnly = False;
if (defined("STATISTIC_ONLY")
  && STATISTIC_ONLY
  && substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) != BX_ROOT."/admin/")
{
     $publicStatisticOnly = True;
}
if (!$publicStatisticOnly && strlen(LANG_CHARSET) > 0
     && COption::GetOptionString("main", "include_charset", "Y") == "Y")
{
}

or like this:

if (!defined("STATISTIC_ONLY") || ! STATISTIC_ONLY
  || substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) == BX_ROOT."/admin/")
{
  if (strlen(LANG_CHARSET) > 0 && COption::GetOptionString("main", "include_charset", "Y") == "Y")
  {
  }
}

1.2.4. Arrays

The arrays consisting of multiple lines of code should be formatted like this:

$arFilter = array(
  "key1" => "value1",
  "key2" => array(
      "key21" => "value21",
      "key22" => "value22",
  )
);

1.3. Empty Lines And Spaces

1.3.1. Empty Lines

Use empty lines to logically divide your source code. Use multiple empty lines to divide the source code into logical or functional sections in one file. Use a single empty line to separate methods, as well as expressions and statements within a method for better readability.

It is recommended to add a comment before a logical or functional section (see Comments).

1.3.2. Spaces

The comma must be followed by the space. The semicolon must be followed by the space unless it is the last character on the line (for example, in a complex “for” statement). No spaces before the comma or semicolon is allowed. Tabs must not be used instead of spaces in such cases.

Use Cases

The following example shows how a space is used after the commas, but not before the parenthesis:
```
TestMethod($a, $b, $c);
```
These two code fragments are formatted incorrectly:
```
TestMethod($a,$b,$c);
```
and
```
TestMethod( $a, $b, $c );
```
The following example shows to use spaces to properly separate the operators:
```
$a = $b * $c / $d;
```
as opposed to the same code formatted incorrectly:
```
$a=$b*$c/$d;
```
Use spaces to format the “for” statements:
```
for ($i = 0; $i < 10; $i++)
```
Do not merge operators and expressions like this:
```
for($i=0;$i<10;$i++)
```
Note that using tabs to format expressions inside statements is not allowed.
The following formatting should not be made a common practice:
```
$arArray = array(
  "key1" => "value1",
  "key2" => "value2",
);
```
There is no special rule regarding the use of the space, or lack thereof, after the “if” statement.

1.4. Other regulations

Use parentheses to group operators in complex expressions regardless of operator precedence for better readability.

$r = $a + ($b * $c);

2. Naming Conventions

2.1. General Provisions

Do not use underscores in the identifier names because it makes them longer and less readable. Use such names that can describe the identifier purpose and meaning in an unambiguous fashion.

At the same time, try to make your identifier shorter (but they still must be well readable).

If a name contains an abbreviation, it’s better to use a single capital letter for the first letter of the abbreviation than to use capitals for the entire abbreviation. So it would be better to assign a name like getHtmlStatistic than getHTMLStatistic.

2.2. Variable Names

Start with a lowercase character and use uppercase character as separators (camelCase). Variable names can have prefixes if there is a clear need to show the type of variable: ar – for arrays, db – for data sets from databases, etc.

For example: $testCounter, $userPassword.

2.3. Method Names

Clarity in action names, which will execute a function or method.
Use of prefixes: is (indicates a question), get (to get a variable), set (set value).

Example: isFileWriteable()

2.4. Class Names

The name should signify an entity described by the class.
The name should not consist of more than 3 words.
The underscore symbol (‘_’) cannot be used.
To separate words in the name, the first letter of each word can be capitalized.

Example: class SaleAffiliateAccount

3. Comments

Commentary must be in English and contain relevant information

3.1. PHPDoc

All classes and their public methods must be described in PHPDoc style.

Example:

/**
 * Gets a value that indicates whether a directory exists in the file system
 *
 * @param string $path - Path to the directory
 * @return bool - True if the directory exists, false - otherwise
 */

4. Other

4.1. Magic numbers

Code should not contain magic numbers. Here is an example of bad code:

$task->Update($taskId, array('STATUS' => 3), 1);

Proper code:

$task->Update($taskId, array('STATUS' => CTaskStatus::New), TASK_PERMISSIONS_WRITE);

4.2. Automatic formatting tools

4.2.1. php_beautifier

1. Install the php_beautifier (ubuntu) pack:

sudo aptitude install php_beautifier or sudo aptitude install php-pear и sudo pear install PHP_Beautifier-0.1.15
cd
hg clone http://hg.max/repos/Bitrix_php_beautifier
sudo ln -s Bitrix_php_beautifier/Bitrix.filter.php /usr/share/php/PHP/Beautifier/Filter/Bitrix.filter.php

Configure the editor:

Select the menu point Settings - Configure Kate...
Select the setting Plugins and place a check next to Text Filter
Click OK
Now the Tools menu will have a point called Filter Text

Use:

Select a text excerpt (or Ctrl-A for all the text)
Tools - Filter Text
Enter (or select from history): php_beautifier -t -f - -l 'Lowercase Bitrix'
Click OK.

Applications and Context

Application is an object responsible for core initialization.

Application is the entry base point (router) for query to (kernel) core global entities: connection with data sources, managed cache, etc. Also, the application contains global data that belongs to the site itself and do not depend on a specific hit. I.e. the application is an unaltered part not dependent on a specific hit.

Any specific class of application is a successor of the abstract class Bitrix\Main\Application.

The specific class Bitrix\Main\HttpApplication is responsible for a regular http hit on the site.

The application supports the Singleton template. I.e. as a part of the hit there is only one copy of a specific type of application. It can be obtained using the instruction:

$application = Application::getInstance();

Context is an object responsible for a specific hit. It contains a query of a current hit, response to it, and also the server parameters of the current hit. I.e. it is a variable part that depends on the current hit.

Any specific class of a context is a successor of the abstract class Bitrix\Main\Context. Two specific classes of the context are supported – Bitrix\Main\HttpContext and Bitrix\Main\CliContext. The specific class Bitrix\Main\HttpContext is responsible for a regular http hit on the site.

The following code may be used in order to obtain a context of the current hit execution:

$context = Application::getInstance()->getContext();

If the application of the Bitrix\Main\HttpApplication type was initiated, this call will bring an instance of the Bitrix\Main\HttpContext context type.

The context contains a query of the current hit. In order to receive the query the following code may be used:

$context = Application::getInstance()->getContext();
$request = $context->getRequest();

Note: In all the examples, a full form of record is used (sometimes without indicating name spaces) that permits you to obtain the result from any code point. However, short forms may exist for this specific code point in order to access the result.

A request is a class instance that is a successor of the Bitrix\Main\Request class. In case of a normal http request the request will be a class instance of Bitrix\Main\HttpRequest that extends Bitrix\Main\Request. This class is a dictionary providing access to “key-value” pairs of incoming parameters.

The following code may be used in order to access an incoming parameter transmitted by the GET or POST methods:

$value = $request->get("some_name");
$value = $request["some_name"];

Note: Code $value = $request["some_name"]; returns string processed by the security module filters. However, this doesn't signify about its security, all depends on how it will be used further.

Other useful query methods:

$value = $request->getQuery("some_name");   // receive GET parameter
$value = $request->getPost("some_name");   // receive POST parameter
$value = $request->getFile("some_name");   // receive downloaded file
$value = $request->getCookie("some_name");   // receive cookie value
$uri = $request->getRequestUri();   // receive an address requested
$method = $request->getRequestMethod();   // receive a request method
$flag = $request->isPost();      // true - POST-request, otherwise false

Errors

In the old core, API tried to interpret for a user/developer and was overlooking errors and inaccuracies. As a result, errors that are difficult to catch may occur. In addition, such an approach causes a lot of implicit agreements that must be taken into account.

For example, a user/developer selects entries for deletion using a filter. In this case, they incidentally make a writing error in the filter name. A typical API of the old core will ignore this filter and return all the entries. The next instruction will successfully delete all of these entries.

The method changes in the new core D7. API does not have to guess anything for a user. API must respond appropriately if it meets an unexpected situation, such as an unknown filter, no id transmitted, lack of value, excessive value, must not be invoked in this mode, etc.

When an error is displayed on the screen (if the debugging mode is available), connects the file /error.php (The file /error.php is located in site root. It can contain, for example, error message print).

Example of error.php

You can print error in the site design inside this file, as well as specify HTTP status code (for example, "500 Internal Server Error").

API

Module API (classes) is not divided by databases. ORM takes care of all the twists and turns of work with a specific database.

No prefixes or suffixes shall be used in class names.

Each module API class may be located in a separate file with a name that coincides with the class name written in lower case. The classes located in the root of module namespace must be based in the files of the /lib module folder root. The classes located in subspaces inside the module namespace must be based in the files of the relevant subfolders of the /lib module folder.

For example, the Bitrix\Main\Application class must be located in the file /lib/application.php in respect of the main module root folder; the Bitrix\Main\IO\File class must be located in the file /lib/io/file.php in respect of the main module root folder; and the Bitrix\Forum\Message class must be located in the file /lib/message.php in respect of the root folder of the forum module.

If these naming rules are complied with, once a module is connected, its classes are uploaded automatically upon first call. No additional actions are needed for the registration and connection of files with classes.

Note: However, for performance reasons, additional registration and connection are recommended for classes that are used often.

Classes of the ORM entities (successors of the class Bitrix\Main\Entity\DataManager) constitute an exception from the class and file naming rules. The names of such classes are generated with the Table suffix. E.g., CultureTable, LanguageTable. But file names do not contain the table suffix. Such classes are also connected automatically.

Note: There is a possibility to register a class in the autoload system using the following method:

void Loader::registerAutoLoadClasses(
	$moduleName,
	array $arClasses
)

It can be used in order to merge small classes in one file.

Non-standard classes (partner’s classes) must be located in their own namespaces that coincide with the names of relevant partners. Each partner’s module determines its own subspace in the partner’s namespace that coincides with the module name without the partner’s name. E.g., for the module mycompany.catalog of the partner "Mycompany", the namespace will be MyCompany\Catalog. Other rules are the same as for standard modules.

The following instruction is used in order to connect a module in a new core:

mixed Loader::includeModule($moduleName);

Naming Rules

Classes

Classes must be named in UpperCamelCase.
Their name cannot contain any other symbols but for Latin letters.
Class name must be a noun. Unnecessary acronyms and abbreviations should be avoided.

Examples:

class User;
class UserInformation;

Methods

The methods, including class methods, must be named in lowerCamelCase.
Their name cannot contain any other symbols but for Latin letters.
Numbers may be used, provided that the name cannot be formed otherwise. E.g.: encodeBase64, getSha1Key.
The method name must start with a verb.
The name length must contain at least 3 characters.

Examples:

run();
setImage();
getName();

Pure data

Pure data, including class pure data, must be written in UPPER_REGISTER_WITH_A_FLATWORM_SEPARATOR.
May contain Latin letters, flatworm character, and numbers (except for the first position).

Examples:

DATE_TIME_FORMAT
LEVEL_7

Class Members, Method Parameters, and Variables

Must be named in a lowerCamelCase.
May not contain prefixes meaning membership in class, appurtenance to parameters, type, and other insignificant things. Example of unnecessary prefixes: $this->mAge, function setName($pName), $arrArray.
May contain Latin letters and numbers (but for the first position).

Examples:

$firstName = '';
$counter = 0;

Generally Acceptable Abbreviations of the Names of Variables and Methods

Abbreviations in the first position must be written in lower case letters, abbreviations in other positions must start with a capital letter, with all other letters being written in lowercase.
Class names should start with a upper case letter, with all other letters being written in lower case.

Example:

$xmlDocument
$mainXmlDocument
HttpParser

Abbreviations that are not generally acceptable (in Bitrix) cannot be used.

Working with the Database

General architecture of API classes for working with databases:

The connection pool Bitrix\Main\DB\ConnectionPool contains information about connections of applications. There are default connections (main connections) and there may be a set of named connections to connect elsewhere, including to another database of a different type.
Specific connection classes inheriting the abstract class Bitrix\Main\DB\Connection ensure low-level operations with the database. They are divided into classes by databases.
Specific classes of forming SQL queries inheriting Bitrix\Main\DB\SqlHelper that help to form a query without going into the syntax of a specific database.
Specific classes for work with query execution result inheriting Bitrix\Main\DB\Result. They also vary according to databases.

These classes permit working with databases at a low level, but it is rarely required. Instead, working through ORM is recommended since ORM permits programming only at a business logic level.

Obtaining Database Connection, Named Connections

A connection may be obtained through applications and is, among other things, an entry point. From this entry point, instances of “star” objects for this application may be obtained that are needed for all (or almost all) pages or components of this application.

$connection = Main\Application::getConnection();
$sqlHelper = $connection->getSqlHelper();

$sql = "SELECT ID FROM b_user WHERE LOGIN = '".$sqlHelper->forSql($login, 50)."' ";

$recordset = $connection->query($sql);
while ($record = $recordset->fetch())
{
   ***

Various Forms of Query Execution Call

Accordingly, a call must be executed through the application in various forms: simple query, query with a limit for entries, scalar query, or a query “in general.”

$result1 = $connection->query($sql);
$result2 = $connection->query($sql, $limit);
$result3 = $connection->query($sql, $offset, $limit);

$cnt = $connection->queryScalar("SELECT COINT(ID) FROM table");

$connection->queryExecute("INSERT INTO table (NAME, SORT) VALES ('Name', 100)")

Obtaining Query Results:

$connection = Main\Application::getConnection();
$sqlHelper = $connection->getSqlHelper();

$sql = "SELECT ID FROM b_user WHERE LOGIN = '".$sqlHelper->forSql($login, 50)."' ";

$recordset = $connection->query($sql);
while ($record = $recordset->fetch())
{
   ***

Typed data are immediately returned as a type and not as lines or numbers.

Result Modification:

$connection = \Bitrix\Main\Application::getConnection();
$recordset = $connection->query("select * from b_iblock_element", 10);
$recordset->setFetchDataModifier(
   function ($data)
   {
       $data["NAME"] .= "!";
       return $data;
   }
);

while ($record = $recordset->fetch(\Bitrix\Main\Text\Converter::getHtmlConverter()))
   $data[] = $record

Result may be modified and conversed immediately, e.g. for preparation to XML displaying, etc.

Classes. Examples

Configuration

Located in the namespace \Bitrix\Main\Config. Consists of 2 classes: \Bitrix\Main\Config\Configuration и \Bitrix\Main\Config\Option.

Configuration

$realm = \Bitrix\Main\Config\Configuration::getValue("http_auth_realm");
if (is_null($realm))
    $realm = "Bitrix Site Manager"

Class is responsible for the global settings of the entire application. (This feature is determined by pure data in the old core.) Class operates a single base of settings stored in the file /bitrix/.settings.php. The data stored are random. For example, the entire data pool can be stored for named connections.

Option

$cookiePrefix = \Bitrix\Main\Config\Option::get('main', 'cookie_name', 'BITRIX_SM');
$cookieLogin = $request->getCookie($cookiePrefix.'_LOGIN');
$cookieMd5Pass = $request->getCookie($cookiePrefix.'_UIDN');

The option class is virtually the same as the COption class of the old core and works with the parameters of modules and sites stored in the database. It is controlled from the administrative section: settings of specific forms, setup, etc.

Files

Work with files is object-oriented. It is located in the Bitrix\Main\IO namespace and has 3 basic classes:

Path – handling paths, static.
Directory – handling folders.
File – handling files.

Some other classes, including abstract, for managing hierarchy are also available in addition to these classes.

Other classes

The folder bitrix/modules/main/lib contains class library for implementing different frequent actions, included in the Main module and not spread among different modules. В том числе в соответствующих пространствах лежат файлы и API для работы:

Bitrix\Main\Data - with cache, including managed cache.
Bitrix\Main\Text - with text: classes for converting text and other
Bitrix\Main\Type - with data types: date, files and other.
Bitrix\Main\Web - with web: handling the URL, web queries and other.

Equivalent CUtil::jSPostUnescape() in Core D7

If you need to use HttpRequest in AJAX queries:

Application::getInstance()->getContext()->getRequest()->getPost('name')

you'll have to consider that CUtil::JSPostUnescape won't help in case of encoding win-1251.

You can use instead:

use Bitrix\Main\Web\PostDecodeFilter;
...
Application::getInstance()->getContext()->getRequest()->addFilter(new PostDecodeFilter)

After this, you can get decoded data via getPost.

Handling D7. Location example

Do not forget to connect sale module.

Types of locations

Adding a location type:

$res = \Bitrix\Sale\Location\TypeTable::add(array(
	'CODE' => 'CITY',
	'SORT' => '100', // nesting level
	'DISPLAY_SORT' => '200', // display priority when searching
	'NAME' => array( // language names
		),
		'en' => array(
			'NAME' => 'City'
		),
	)
));
if($res->isSuccess())
{
	print('Type added with ID = '.$res->getId());
}

Location type update

$res = \Bitrix\Sale\Location\TypeTable::update(21, array(
	'SORT' => '300',
	'NAME' => array(
		'en' => array(
			'NAME' => 'New City'
		),
	)
));
if($res->isSuccess())
{
	print('Updated!');
}

Deleting location type

$res = \Bitrix\Sale\Location\TypeTable::delete(21);
if($res->isSuccess())
{
	print('Deleted!');
}

Getting type of location by ID

$item = \Bitrix\Sale\Location\TypeTable::getById(14)->fetch();
print_r($item);

Getting list of types with names on the current language

$res = \Bitrix\Sale\Location\TypeTable::getList(array(
	'select' => array('*', 'NAME_EN' => 'NAME.NAME'),
	'filter' => array('=NAME.LANGUAGE_ID' => LANGUAGE_ID)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting groups with account of hierarchy having this location

<?
\Bitrix\Main\Loader::includeModule('sale');

function getGroupsByLocation($locationId)
{
    $res = \Bitrix\Sale\Location\LocationTable::getList([
        'filter' => ['=ID' => $locationId],
        'select' => [
            'ID', 'LEFT_MARGIN', 'RIGHT_MARGIN'
        ]
    ]);

    if(!$loc = $res->fetch())
    {
        return [];
    }

    $locations = [$locationId];

    $res = \Bitrix\Sale\Location\LocationTable::getList([
        'filter' => [
            '<LEFT_MARGIN' => $loc['LEFT_MARGIN'],
            '>RIGHT_MARGIN' => $loc['RIGHT_MARGIN'],
            'NAME.LANGUAGE_ID' => LANGUAGE_ID,
        ],
        'select' => [
            'ID',
            'LOCATION_NAME' => 'NAME.NAME'
        ]
    ]);

    while($locParent = $res->fetch())
    {
        $locations[] = $locParent['ID'];
    }

    $res = \Bitrix\Sale\Location\GroupLocationTable::getList([
        'filter' => ['=LOCATION_ID' => $locations]
    ]);

    $groups = [];

    while($groupLocation = $res->fetch())
    {
        $groups[] = $groupLocation['LOCATION_GROUP_ID'];
    }

    return $groups;
}

Locations

Adding

$res = \Bitrix\Sale\Location\LocationTable::add(array(
	'CODE' => 'newly-created-location-code',
	'SORT' => '100', // priority for showing in list
	'PARENT_ID' => 1, // parent location ID
	'TYPE_ID' => 14, // type ID
	'NAME' => array( // language names
		'en' => array(
			'NAME' => 'New York'
		),
	),
	'EXTERNAL' => array( // external service values
		array(
			'SERVICE_ID' => 1, // service ID
			'XML_ID' => '163000' // value
		),
		array(
			'SERVICE_ID' => 1,
			'XML_ID' => '163061'
		),
	)
));
if($res->isSuccess())
{
	print('Location added with ID = '.$res->getId());
}
else
{
	print_r($res->getErrorMessages());
}

Update

$res = \Bitrix\Sale\Location\LocationTable::update(3156, array(
	'PARENT_ID' => 33,
	'NAME' => array(
		'de' => array(
			'NAME' => 'New York'
		),
	)
));
if($res->isSuccess())
{
	print('Updated!');
}

Deleting

$res = \Bitrix\Sale\Location\LocationTable::delete(3156);
if($res->isSuccess())
{
	print('Deleted!');
}

Getting location by ID

$item = \Bitrix\Sale\Location\LocationTable::getById(3159)->fetch();
print_r($item);

Getting location by CODE, with optional filtering\field retrieval. In fact, this is a wrapper \Bitrix\Sale\Location\LocationTable::getList().

$item = \Bitrix\Sale\Location\LocationTable::getByCode('newly-created-location-code', array(
	'filter' => array('=NAME.LANGUAGE_ID' => LANGUAGE_ID),
	'select' => array('*', 'NAME_EN' => 'NAME.NAME')
))->fetch();
print_r($item);

Getting list of locations with names on the current language and type codes

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array('=NAME.LANGUAGE_ID' => LANGUAGE_ID),
	'select' => array('*', 'NAME_EN' => 'NAME.NAME', 'TYPE_CODE' => 'TYPE.CODE')
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting node direct descendants with ID=1 with names on the current language, codes and names for location types

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=ID' => 1, 
		'=CHILDREN.NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=CHILDREN.TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'CHILDREN.*',
		'NAME_EN' => 'CHILDREN.NAME.NAME',
		'TYPE_CODE' => 'CHILDREN.TYPE.CODE',
		'TYPE_NAME_EN' => 'CHILDREN.TYPE.NAME.NAME'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting parent nodes for three nodes

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=ID' => array(3159, 85, 17), 
		'=PARENT.NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=PARENT.TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'PARENT.*',
		'NAME_EN' => 'PARENT.NAME.NAME',
		'TYPE_CODE' => 'PARENT.TYPE.CODE',
		'TYPE_NAME_EN' => 'PARENT.TYPE.NAME.NAME'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting path from tree root to the current item

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=ID' => 224, 
		'=PARENTS.NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=PARENTS.TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'I_ID' => 'PARENTS.ID',
		'I_NAME_EN' => 'PARENTS.NAME.NAME',
		'I_TYPE_CODE' => 'PARENTS.TYPE.CODE',
		'I_TYPE_NAME_EN' => 'PARENTS.TYPE.NAME.NAME'
	),
	'order' => array(
		'PARENTS.DEPTH_LEVEL' => 'asc'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting list of root nodes with indicated number of descendants

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=PARENT_ID' => 0,
		'=NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'ID',
		'NAME_EN' => 'NAME.NAME',
		'TYPE_CODE' => 'TYPE.CODE',
		'TYPE_NAME_EN' => 'TYPE.NAME.NAME',
		'CHILD_CNT'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting external data for locations with indicated service code

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'CODE' => array('newly-created-location-code', '0000028090'),
	),
	'select' => array(
		'EXTERNAL.*',
		'EXTERNAL.SERVICE.CODE'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting subtree of nodes on the current language

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'runtime' => array(
		'SUB' => array(
			'data_type' => '\Bitrix\Sale\Location\Location',
			'reference' => array(
				'>=ref.LEFT_MARGIN' => 'this.LEFT_MARGIN',
				'<=ref.RIGHT_MARGIN' => 'this.RIGHT_MARGIN'
			),
			'join_type' => "inner"
		)
	),
	'filter' => array(
		'=CODE' => '0000028042',
		'=SUB.NAME.LANGUAGE_ID' => LANGUAGE_ID
	),
	'select' => array(
		'S_CODE' => 'SUB.CODE',
		'S_NAME_EN' => 'SUB.NAME.NAME',
		'S_TYPE_CODE' => 'SUB.TYPE.CODE'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting locations included into the group without hierarchy.

\Bitrix\Main\Loader::includeModule('sale');


/* Group identifier */
$groupId = 1

/* Get locations included into group */
$res = \Bitrix\Sale\Location\GroupLocationTable::getConnectedLocations(1);

while($item = $res->fetch())
{
    var_dump($item);
}

Service Locator

Description

Service locator - is a design pattern used for convenient handling of application services. You can find more details in this article.

Idea of service patten is designed to use special object (service locator) that will be responsible for creating and locating services instead of creating specific services directly (via "new"). It's a kind of a register.

Class \Bitrix\Main\DI\ServiceLocator implements the interface PSR-11. Available from main version 20.5.400.

Simple example of use:

$serviceLocator = \Bitrix\Main\DI\ServiceLocator::getInstance();

if ($serviceLocator->has('someService'))
{
    $someService = $serviceLocator->get('someService');
    //...$someService service use
}

Service registration

Service registration via bitrix/.settings.php files

Before querying the service, register it, using .settings.php files. All the necessary services are listed in the services section.

 [
        'value' => [
            'someServiceName' => [
                'className' => \VendorName\Services\SomeService::class,
            ],                      
            'someGoodServiceName' => [
                'className' => \VendorName\Services\SecondService::class,
                'constructorParams' => ['foo', 'bar'],
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

As a result, these services will be available immediately after kernel is initialized. Below you can read about the available service describing methods.

$serviceLocator = \Bitrix\Main\DI\ServiceLocator::getInstance();
$someGoodServiceName = $serviceLocator->get('someGoodServiceName');
$someServiceName = $serviceLocator->get('someServiceName');

Service registration has been performed via the {moduleName}/.settings.php module setting files

Module root directory can also contain the .settings.php file. It can contain service descriptions belonging to this module and are used in it. Semantics is similar to description in the global bitrix/.settings.php and config description rules.

 [
        'value' => [
            'someModule.someServiceName' => [
                'className' => \VendorName\SomeModule\Services\SomeService::class,
            ],                      
            'someModule.someAnotherServiceName' => [
                'constructor' => static function () {
                    return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
                },
            ],                      
            'someModule.someGoodServiceName' => [
                'className' => \VendorName\SomeModule\Services\SecondService::class,
                'constructorParams' => static function (){
                    return ['foo', 'bar'];
                },
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

Attention! These services will be registered only after module is connected. Also, it is recommended to name module services by using module name prefix, to avoid duplicate service codes, for example:

 iblock.imageUploader
    disk.urlManager
    crm.entityManager
    crm.urlManager
    someModule.urlManager.

Registering service via API

Services can be registered via API as well. Use the class methods \Bitrix\Main\DI\ServiceLocator

Service configuration

Configuration is described as an array and prompts service locator a method for creating an object. Presently, there are three description methods:

Indication of service class. Service locator creates the service by calling new $className.

 'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
        ]

Indicating service class and parameters to be passed into constructor. Service locator creates a service by calling new $className('foo', 'bar').

'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => ['foo', 'bar'],
        ]                      

        'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => static function (){
               return ['foo', 'bar'];
            },
        ]

Indicating closure-constructor that create and return service object.

 'someModule.someAnotherServiceName' => [
            'constructor' => static function () {
                return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
            },
        ]

Locator registration

Service registration

Service registration via the bitrix/.settings.php files

Before querying the service, it must be registered. It can be done via .settings.php files. All the necessary services are listed in the services section.

 [
        'value' => [
            'someServiceName' => [
                'className' => \VendorName\Services\SomeService::class,
            ],                      
            'someGoodServiceName' => [
                'className' => \VendorName\Services\SecondService::class,
                'constructorParams' => ['foo', 'bar'],
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

As the result, these services will be available immediately after core D7 initialization. Read below about which service description methods are presently available.

$serviceLocator = \Bitrix\Main\DI\ServiceLocator::getInstance();
$someGoodServiceName = $serviceLocator->get('someGoodServiceName');
$someServiceName = $serviceLocator->get('someServiceName');

Service registration using the module settings {moduleName}/.settings.php files

The module root can also have the .settings.php file. You can describe services that belong and are used in this module. Semantics is similar to the description in the global bitrix/.settings.php files and config description rules.

 [
        'value' => [
            'someModule.someServiceName' => [
                'className' => \VendorName\SomeModule\Services\SomeService::class,
            ],                      
            'someModule.someAnotherServiceName' => [
                'constructor' => static function () {
                    return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
                },
            ],                      
            'someModule.someGoodServiceName' => [
                'className' => \VendorName\SomeModule\Services\SecondService::class,
                'constructorParams' => static function (){
                    return ['foo', 'bar'];
                },
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

Attention! These services will be registered only after module is connected. Also, it is recommended to name the module services by using the module name prefix to avoid issues with service code duplicates, for example:

 iblock.imageUploader
    disk.urlManager
    crm.entityManager
    crm.urlManager
    someModule.urlManager.

Service registration via API

Services can be registered via API as well. Use the class methods \Bitrix\Main\DI\ServiceLocator

Service configuration

Configuration is described as an array and prompts service locator a method for creating an object. Presently, there are three methods for description:

Indicating a service class. Service locator creates a service by calling a new $className.

 'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
        ]

Indicating a service class and parameters to be passed into constructor. Service locator will create a service by calling a new $className('foo', 'bar').

'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => ['foo', 'bar'],
        ]                      

        'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => static function (){
               return ['foo', 'bar'];
            },
        ]

Indicating a closure-constructor that must create and return a service object.

 'someModule.someAnotherServiceName' => [
            'constructor' => static function () {
                return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
            },
        ]

Controllers

Terminology

Action, or AJAX action is a responder method that implements final logic, executes operations and returns data.
Controller - is a combination of AJAx-actions.
configureActions() method regulates configuration of actions inside the controller, defining rules of access to actions.
Pre-, post-filters are configuration items, that are action start and end event handers. Prefilter can block the start, postfilter can affect the result.

Agreements

Note: Main (main) module version 20.600.87 supports PSR-4 in ajax-controllers.

Upon calling all parameter names are caseSEnsitive
Upon calling all parameter names are caseSEnsitive
Upon calling all action names are case-INsensitive

Full action name is generated by the template vendor:module.partOfNamespace0.partOfNamespace1.Controller.action.

    \Bitrix\Disk\Controller\Folder::getAction() 
    bitrix:disk.Controller.Folder.get

    \Bitrix\Disk\Controller\Intergation\Dropbox::connectAction() 
    bitrix:disk.Controller.Intergation.Dropbox.connect

    \Qsoft\Somedisk\Controller\SuperFolder::getAction() 
    qsoft:somedisk.Controller.SuperFolder.get

When not indicating the vendor:, it means it is bitrix:

    \Bitrix\Disk\Controller\Folder::getAction() 
    disk.Controller.Folder.get

When indicating defaultNamespace in module settings, it can be omitted and not indicated in the action.

	defaultNamespace = \Bitrix\Disk\Controller
	
    \Bitrix\Disk\Controller\Folder::getAction() 
    disk.Folder.get

When indicating alias in module settings, use it instead of abbreviated namespace.

	\Bitrix\Disk\CloudIntegration\Controller => cloud
	
    \Bitrix\Disk\CloudIntegration\Controller\File::getAction() 
    disk.cloud.File.get

Upon calling the action from component, indicate full component name and action name (without Action suffix).

    bitrix:list.example
    showFormAction

    BX.ajax.runComponentAction('bitrix:list.example', 'showForm', {
        ...
    }).then(function (response) {});

Time, date, links must be returned not in string format, but as objects.

        \Bitrix\Main\Type\DateTime
        \Bitrix\Main\Type\Date
        \Bitrix\Main\Web\Uri

Controller

Controllers is the part of MVC architecture, responsible for query processing and response generation.

Actions

Controllers consist of main operational actions, employed by user to get a result. Single controller can have one or several actions. For example, let's create controller with two actions item.add and item.view in the module example. Specifically for this example, controller must be located at /modules/vendor.example/lib/controller/item.php.

First step - create file .settings.php in the module root.

<?php
//modules/vendor.example/.settings.php
return [
	'controllers' => [
		'value' => [
			'defaultNamespace' => '\\Vendor\\Example\\Controller',
		],
		'readonly' => true,
	]
];

Next, create controller file (see details for available methods here):

namespace Vendor\Example\Controller;

use \Bitrix\Main\Error;

class Item extends \Bitrix\Main\Engine\Controller
{
	public function addAction(array $fields):? array
	{
		$item = Item::add($fields);

		if (!$item)
		{
			$this->addError(new Error('Could not create item.', {error_code}));

			return null;
		}

		return $item->toArray();
	}

	public function viewAction($id):? array
	{
		$item = Item::getById($id);
		if (!$item)
		{
			$this->addError(new Error('Could not find item.', {error_code}));
					
			return null;
		} 

		return $item->toArray();
	}
}

First, the add action (using specific method Item::addAction) attempts to create a specific Item passed by $fields.

Note. Array $fields retrieved by automatic binding of method parameters and $_REQUEST.

When an activity was failed due to specific reasons, return null and complete the controller by errors. In this case, kernel generates a response:

{
	"status": "error", //please note that status has been automatically updated
	"data": null,
	"errors": [
		{
			"message": "Could not create item.",
			"code": {code}
		}
	]
}

Otherwise, add an item and return it as an array $item->toArray() from activity. This array, kernel generates the response:

{
	"status": "success",
	"data": {
		"ID": 1,
		"NAME": "Nobody",
		//...element fields
	},
	"errors": null
}

Generally, activity can return not only scalars, but objects as well.

The view activity (using specific method Item::viewAction) first attempts loading a specific Item object by specific passed parameter $id. It's important to note, the $id will be automatically retrieved from $_POST['id'] or $_GET['id'].

When this parameter is not found, kernel generates response with error:

{
	"status": "error",
	"data": null,
	"errors": [
		{
			"message": "Could not find value for parameter {id}",
			"code": 0
		}
	]
}

How execute controller action?

Specific AJAX-action requires action naming convention awareness. In our case: Item::addAction -> vendor:example.item.add Item::viewAction -> vendor:example.item.view.

vendor:example.item.add, vendor:example.item.view can be used for calling actions using BX.ajax.runAction:

BX.ajax.runAction('vendor:example.item.add', {
	data: {
		fields: {
            ID: 1,
            NAME: "test"
        } 
	}
}).then(function (response) {
	console.log(response);
	/**
	{
		"status": "success", 
		"data": {
			"ID": 1,
			"NAME": "test"
		}, 
		"errors": []
	}
	**/			
}, function (response) {
	//receives all responses with status status !== 'success'
	console.log(response);
	/**
	{
		"status": "error", 
		"errors": [...]
	}
	**/				
});

Or retrieve the link to action and send individual http-query.

/** @var \Bitrix\Main\Web\Uri $uri **/
$uri = \Bitrix\Main\Engine\UrlManager::getInstance()->create('vendor:example.item.view', ['id' => 1]);
echo $uri;
// /bitrix/services/main/ajax.php?action=vendor:example.item.view&id=1
// execute GET-query

Starting from main 24.0.0 an option is now available to add your own commands via module's {moduleName}/.settings.php file. Module commands are listed in the section console:

Composer and Bitrix Framework

In the version 18.0.5 we started to use composer inside the product in development mode. It will be required, if you would like to use such advantages, as ORM class annotation and generally in CLI command line interface. If you already use composer in your Bitrix24 project, we have prepared a completed integration profile with your dependencies configuration.

First, you need to have an installed composer. The installation manual is available at the official website.

Below description will be based in the tact that composer is installed globally and is called by a simple command:

Dependency configuration

After that, folder bitrix/vendor is created with necessary libraries installed. When you want to specify another location for this directory, you need to create your own composer.json - look up the second option for dependencies config below.

Be default, system awaits to see your file composer.json in the folder bitrix, but we recommend to locate it somewhere outside DOCUMENT_ROOT (for it not to be available publicly). In this case, specify the path to file in .settings.php, for it's configuration to be used in the product.

Inside, connect our file with dependencies bitrix/composer-bx.json via the plugin Composer Merge Plugin. Minimally, your composer.json must contain plugin call and our configuration connection.

Instead of /path/to/bitrix/ you need to specify a real path to folder bitrix.

You can add your dependencies and settings. For example, to directly specify path to vendor folder (by default it will be in the same location as the file composer.json), use the command "vendor-dir".

Now you can use the advantages of composer in your project, connecting the file vendor/autoload.php. When using the CLI-commands, it is connected automatically.

UTF-8 or a National Encoding?

A website developer always faces the problem: which encoding to choose for the project.

UTF-8 is considered promising. However, everything has its drawbacks. And the decision to use any encoding only because it is promising, without taking into account many other factors is not correct. The choice will be good only when it completely takes into account all aspects of a specific project. That it is not easy to foresee all of the aspects is another matter.

We think that the use of UTF-8 is preferable, but it is up to a project developer to decide what to choose.

How to Switch a Website from the National Encoding to UTF-8

It is possible to re-encode all website files to UTF-8 (second option) through SSH using the command convmv. For example, convert ISO8859-1 (legacy Western European) filenames to UTF-8:

Working with databases

These classes allow handling databases at the low level. This, however, is necessary in a small amount of cases. It's preferable to work via ORM, that allows to code at the domain logic level.

You can get connection via applications, which will serve as an entry point, among other things. You can get instances of "key" objects from this entry point for this app, necessary for all (or almost all) pages or components of this application.

Accordingly, an application is used to execute a query: standard query, query with limit on records, scalar query or a "custom" query.

Type-safe data is returned immediately as a type, but not as strings or numerals.

Result can be modified, immediately apply converter to results and, for example, prepare data for printing in XML, and etc.

When designing your own database, a question arises, which data type to use: datetime or timestamp? When handling a database, converting the time to GMT is a minimal requirement. But, to depend less on server settings, it's better to use datetime. In this case, you will have to get current time value in PHP.

Within ORM you can work with several databases. For this, create several records for handling the database in the file /bitrix/.settings.php section connections:

In this manner, there are 2 connected databases: default (by default, Bitrix Framework uses this connection) and old_db (indicates connection parameters to 2nd database). You need to query old_db as follows:

The parameter include_after_connected must indicate path to file to be connected and executed after the first connection with additional database:

For binding ORM entity to a specific connection, re-define the method Bitrix\Main\ORM\Data\DataManager::getConnectionName() inside your *Table class.

In rare cases, there is a necessity to connect databases that cannot use inbuilt driver for PHP (for example, customer has an extremely outdated (or otherwise, most recent) DMBS version. To add support of the new database type to Bitrix Framework, you need the following:

Example of database handling

Practical example of handling a Database using API D7 for creating a custom component. Create such a component:

We get a connection in the class constructor via applications which serve as input point.

Because we have a generated query string: retrieves all user logins from user tables, i. e. with the field ACTIVE set as Y. The query string uses the method forSql for secure input parameters. It also can limit the string length. In our case, it is shown as an example: passes Y but the length shall not be more than a single character.

Function var1: it executes query and gets results via fetch. Standard data is returned immediately as a type, not as strings or numerals.

Function var2. Here, executes the same query but indicates the limit for the number of retrieved elements. In out case, its 2.

Function var3. Executes the same query, but indicates two additional parameters. Such record indicates that two elements will be returned. This is the last parameter. And theses elements are returned starting from the second position. This is a second parameter. We have есть отступаем два элемента и отдаем два, начиная с третьего элемента.

Function var5 - executing the query without getting the result. It's needed in case of INSERT, UPDATE, DELETE.

Function var6 modifies the result. Using the method addFetchDataModifier declare the function which will get array with result for a single element and returns it after modifying it. In our case, the example is not complex: just adds User login text to the login field after colon.

It's permissible to use methods Bitrix\Main\Text\Converter::getHtmlConverter and Bitrix\Main\Text\Converter::getXmlConverter. Accordingly, they prepare to display as html and as xml.

Migration to MySQL

Migrating a site Database from Oracle or MSSQL to MySQL can be performed using the migrator. You can "move" it from Oracle or MSSQL only to MySQL not vice versa.

Updating the site encoding

Starting from the module main version 24.0.0, Bitrix24 fully uses UTF-8 encoding. Single-byte installations are no longer supported.
You can change encoding using Convert to UTF-8 (It's located at the wizard list page /bitrix/admin/wizard_list.php?lang=en). You can also to perform it manually via lesson's guide.

General sequence of actions

You can connect to SSH to edit files and introduce updates to the server.

General sequnce:

Change the encoding to UTF-8 for all languages inside the regional settings Settings > System settings > Language parameters > Regional settings;

mbstring.func_overload prior to the main module version 20.100.0

In case of version 20.100.0 or earlier, you need to add the following strings in the file /.htaccess:

php_value mbstring.func_overload 2 
php_value mbstring.internal_encoding UTF-8

Starting from version main module version 20.100.0 you need to delete PHP settings mbstring.func_overload. This option is no longer required and no longer supported by Bitrix24.

Set the value default_charset = "utf8" in the settings file php.ini;
The location of the settings file php.ini can be viewed previously in the admin section at the page [dw]PHP settings[/dw][di]PHP settings (Settings > Tools > System Administration > PHP settings), this page displays information about current PHP settings.
[/di] (Loaded Configuration File) or using a PHP function phpinfo().

In case of the Hosting-located site, you may need to request a hosting provider to implement these settings.
Add to /bitrix/php_interface/dbconn.php
```
define("BX_UTF", true);
```
In the same file, delete the strings, having the encoding CP1251:
```
setlocale(LC_ALL, 'en_EN.CP1251');
mb_internal_encoding("Windows-1251");
```

Set the value 'value' => true for utf_mode in the file /bitrix/.settings.php:

utf_mode =>
    array(
        'value' => true,
        'readonly' => true,
    ),

Re-encode the complete database to UTF-8. Most likely, you will have to request assistance of server administrator.

Configure the file /bitrix/php_interface/after_connect.php

$DB->Query("SET NAMES 'utf8'");
$DB->Query('SET collation_connection = "utf8_unicode_ci"');

and the file /bitrix/php_interface/after_connect_d7.php

$this->queryExecute("SET NAMES 'utf8'");
$this->queryExecute('SET collation_connection = "utf8_unicode_ci"');
//Versions prior to main 22.0 used variable $connection instead of $this.

Set inside /.htaccess:
```
php_value default_charset utf-8
```
Re-encode all site files to UTF-8.
Reset all cache;
Exit and enter the site to refresh the session data.

Database

For database (DB) conversion, you need to change the database encoding, all its tables and all table text fields. DO NOT convert a database from administrative section. Use other available tools for this purpose.

In a simplest case (without serialized data) you can re-encode the database all tables using the following procedure:

Files

In a simple case, when all site files have the encoding CP1251, re-encode them to UTF-8 by executing the following command in the root site folder (for UNIX systems):

// fo to the site root folder. For example:
cd /var/www/html/ 

// execute the command for file re-encoding
find . -name '*.php' -type f -exec iconv -fcp1251 -tutf8 -o /tmp/tmp_file {} \; -exec mv /tmp/tmp_file {} \;

Important:

This method won't be suitable for sites that have different localization languages, because the structure will have files with different encodings.

Please consider specifics for Unix version that you use. The example specified above may not suitable for it. In this case, adapt it for your OS. For example:

// execute the command for re-coding of files
find ./ -type f -name "*.php" -exec bash -c 'file="$1"; iconv -f cp1251 -t utf8 "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"' _ {} \;

Using third-party software or converting files manually

Sometimes, when using third-party software or choosing to convert files manually there is an occurring special sequence of characters, the so-called BOM. These characters must be located only at the start of file, because the final page is a composite of several php files, and wildcard characters appear in the page body. If you convert files manually - do not save with BOM! file signature

Workflows

Workflow templates with variables, constants and parameters are stored in a serialized and packed format inside the table b_bp_workflow_template. Changing database encoding won't affect them. To update their encoding, you need to perform additional actions.

First, create a copies of tables b_bp_workflow_template using one of several methods detailed below:

Next step is to execute script in a command PHP string that will update data encoding:

Hints and links

Main steps for site conversion are complete. In case of any errors occurring when opening the site, enable the debugging mode 'debug' => true in the file /bitrix/.settings.php. This will allows to see, where and which errors have occurred.

You must perform the [dw]system check[/dw][di]The System check form (Settings > Tools > System check) is designed for comprehensive system parameters check to match recommended minimal product technical requirements and enabling proper project operation.
[/di]. The check results will display what issues must be addressed and rectified. Use pop-up hints under the question mark characters to view additional details.

Check the system check log if issues have occurred with database tables. The log file ends with queries that can be used for removing these errors. It's recommended to copy the database before starting the repairing procedure.

Related links:

Language Files

Example of a language file for the German language:

Example of a language file for the English language:

Work Example

Each language has its own set of language files stored in subcatalogs /lang/ (for more details please refer to the documentation system file structure and module file structure).

Language files are normally used in the administrative scripts of modules or in the components and it defines which of the following functions is used to connect them:

In order to make searching more convenient and to modify the language phrases further, the page parameter show_lang_files=Y, can be used, which permits you to quickly locate and correct any language phrase using means of the module Localization.

Language Files in Own Components

/bitrix/templates/[website_template|.default]/components/[namespace]/[component_name]/[component_template_name]/lang/[language_code]/template.php

The following function can be used to connect to the component language messages of another component:

Replacement of Language Phrases of a Product

Sometimes the development of a website requires that some words or phrases be changed in components or modules.

Let us look into this technique wherein the bottom line is that after a language file is connected, product phrases are replaced with those determined by the developer.

The file must determine the elements of the array $MESS in the form $MESS['language file']['phrase code'] = 'new phrase', for example:

The first line changes link text in the authorization form component; the second line changes the name of the public panel tab; the third line changes the name of the index page of the control panel.

URL SEF configuration

In order to store identifiers of elements/sections of information blocks the field Symbolic Code is most convenient. For example, in the link www.myserver.com/catalog/mobile/nokia_3310/, mobile is the symbol code of the section Mobile telephones, and nokia_3310 is the symbol code of the element located in the section Mobile telephones. The symbol code must be unique, and the system itself checks its uniqueness.

The variable $_SERVER["REQUEST_URI"] in the error 404 handler must be broken down by parameters. To do so, a number of useful functions are available in PHP:

For example, links similar to myserver.com/users/ are processed in the file 404.php as follows:

But fixed check in preg_match not permit to do links similar to www.myserver.com/users/user_login/?r1=banner&r2=computerra.com that are very much needed to analyze advertising campaigns. That is why we write the following in the beginning of the file 404.php:

Complex component and SEF mode

Complex components have an in-built SEF generating function. These components always have an input parameter SEF_MODE, which can accept values Y and N. When parameter SEF_MODE equals N, the component operates with actual links and passes all parameters using query's standard HTTP parameters. For example:

When the parameter SEF_MODE equals Y, the component generates and processes links based on templates. For example, it can recognize and process the link as follows:

When the parameter SEF_MODE equals Y, the component must have the parameter SEF_FOLDER, containing path to folder handled by the component. This path can may match with actual path and may not. For example, the component bitrix:catalog, connected in the file /fld/cat.php can have the specified parameters SEF_MODE = Y and SEF_FOLDER=/catalog/. Then component will respond to queries at the path /catalog/.... By default, editor must set a current actual path to edited file.

Complex component that can operate in SEF mode, must have a defined set of default path templates. For example, complex component bitrix:catalog can have a defined array as follows:

These path templates can be redefined using the complex component input parameter SEF_URL_TEMPLATES, containing new array with all path templates or their segments.

Upon saving a page in editor with the component, operating in SEF mode, the system creates or updates an urlrewrite record. For example, urlrewrite system creates or updates the record type when saving the file /fld/cat.php, containing the component bitrix:catalog, switched to SEF mode with the parameter SEF_FOLDER=/catalog/:

When the record with such PATH and ID already exist, it's updated, if doesn't - it's added.

Upon querying a non-existent page, the urlrewrite run-time searches a corresponding record by CONDITION and forwards control to the PATH page.

Based on template paths, component at the PATH page identifies the requested page and restores variables, hidden within the path.

Examples

Example

News of the type as follows: /about/news/23.html (link for print /about/news/print_23.html) instead of /about/news/detail.php?ID=23 (/about/news/detail.php?ID=23&print=Y)

Additional

How to remove "PHPSESSID=..." from URL?

If this gives no result, you need to update parameter value session.use_trans_sid to Off directly in php.ini on server.

How to remove from page URL a question mark character?

Access permissions

Access to files and catalogs/directories

This level of access permissions is verified in the prolog and defined using special file .access.php, containing PHP array of the following format:

Site admin section can assign access permissions to file using file manager.

When user belongs to several groups, maximum access permissions among all these groups are assigned to this user.

If the current file or catalog doesn't have clearly defined level of access permissions, the system assigns the level of permissions defined for abovelisted catalogs in the catalog tree.

Example 1

When attempting to open the page /dir/index.php, the user belonging to the group ID=3 will have the access permission D (denied), user from the group ID=2 will have the permission R (read). A user, belonging to both groups will have the maximum level of access - R (Read).

Example 2

When accessing the page /admin/index.php, a user in the group ID=3 will have access, and the a user ID=2 will have access denied. When accessing the page /index.php all visitors will have access.

Access permissions within module

In case of standard static public pages, they have only the first level of access applicable to files and catalogs.

When user has at least a minimum R (read) access permission to a file and if this file is a functional part of a specific module, the system checks 2nd level of permissions, specified in the settings of corresponding module. For example: upon entering List of tickets within techsupport administrator sees all messages, techsupport employee - only those messages such employee is responsible for, and a standard user can view only her/his own tickets. Such example shows how access permission works within the logic of Helpdesk module.

The are two methodologies for assigning access permissions of 2nd level (level of permissions within module logic):

The main difference is when a user has several permissions, the maximum permission is selected. When user has several roles, such user accordingly will have summarized capabilities of these roles.

Modules that support roles can be browsed in the Module filter at the page Settings > Users > Access Levels in the Admin section. The remaining modules and in the rest of system settings - use access permissions.

JS Library

Bitrix JS library-related documentation requires по a confident level of JavaScript developer.

Bitrix24 Javascript library is multifaceted. The main class is BX. At the same time, developer can employ a significant number if extensions. For example, date-handling extension.

When working with JS in Bitrix Framework you can use both standard library and third-party libraries. However, you need to connect such libraries beforehand. You can find more details on connecting external JS code in this article.

Connecting JS code

Variants for code locations

Before starting to write JS code, there is a valid question - where to store it?

Registering and connecting libraries

Let's examine the last option in more detail. Indeed, you can allocate the code in the site template via Bitrix\Main\Page\Asset::getInstance()->addJs();. However, more correct solution will be the third approach.

Each file within your folder is essentially an individual mini-library, which you need to register. [dw]Registering[/dw][di]Registering libraries in the module's include.php or within init.php.[/di] is performed via the following code:

As you can see, this code is universal and you can register several files. You can additionally specify CSS file in the CSS key (in case when CSS code used jointly with JS code), and use the key rel to enumerate codes of other BX libraries which will be automatically connected when connecting this library.

When libraries have been registered, they can be connected via the following structure:

Two blocks of code, listed above are used together and sometimes - separately. For example, when developing your own module, you need to register in the module's include.php, and initiate (call InitJSCore) in the location you need (for example, in the component template).

JS class for component template

Sometimes, when developing a component, its template must be supplemented with JS functionality, events and other features. It must look approximately as follows:

Similar approaches can be seen in Bitrix Framework JS core (located in /bitrix/js/). You can get a clearer understanding of Bitrix24 developer JS code after overviewing this example.

JS class actions: memorizes a specific ID (for example, it can be a container ID) and parameter array, as well as associates handler to a confirmation button click event inside the indicated container form.

Media player JS extensions

The most important thing here: is to pass mime-type for each file. This example shows player selecting through all listed files and playing the first that is available. That's why the list must contain the same video with different extensions.

Formatting dates in Javascript

Connecting in PHP

Call in Javascript

The format is a fully similar to the format function date, except for the format T and e (character names for timezone). Also supports extended formats for function FormatDate.

When specific characters must not be formatted, you need to replace these characters with "slash" characters.

When format starts from the symbol ^, the function will crop any zeros. Examples:

date it's either a timestamp in seconds (Number type), or a Date class object. Otherwise, it's current time (new Date()). Examples:

The same as FormatDate, BX.date.format can receive an array with formats for calculating a "1 seconds ago", "2 minutes ago" types and etc.

format array consist of elements ["format interval", "format"], where format interval defines to which time interval the format applies.
format array is processed sequentially until the first match.
Time interval is defined between specified date (first parameter in BX.format.date) and current date.

BX.date.format full signature

current date - date (timestamp in seconds, either Date class object), used for such calculations as "1 seconds ago", "2 years ago". When not specified, default value new Date().

Small hint for matching the server and client codes:

BX.date.convertBitrixFormat

Function converts bitrix-date format into the date function format. Current site date formats can be received as follows:

Examples of JS Code Optimization

Developers rarely think about the number of hits when making a tool they do not use themselves and for which they do not lease capacities. They leave this for clients’ discretion: “they might buy a server with a higher capacity, and everything will work really fast.” However, a professional developer should be able to see all consequences of their work and find solutions that are appropriate not only for themselves as programmers, but also for the client.

Where to Search for an Error in the Ajax Handler in POST Queries

Let us review an example of reduction of the number of hits based on Bitrix24 desktop application.

The specifics of this tool are that it can make an exorbitant amount of hits. There is no other tool in Bitrix Framework which can make even a half of the messenger’s hits.

The number of Bitrix24 users grew almost exponentially, and so did the amount of hits. A critical moment arrived when these numbers simply could not be ignored any longer:

The following problem was revealed during log review: the log contained only the name of a handler, because all the data were sent by POST query to the server. Logging POST queries is not very convenient, that is why another solution was required in order to determine whether these queries were legitimate or stray.

The solution is very easy and consists in GET tags. The query just has to be executed together with a GET tag: im.ajax.php?GET_HISTORY, im.ajax.php?UPDATE_STATE etc.

Server queries could be grouped by these tags thus permitting to reveal bottlenecks.

The most popular tags were determined and run time was optimized. Some of the tags were completely remade to avoid unnecessary server queries (agents were created to send data using the Push & Pull module).

Frequent Errors and Recommendations

Below we include a short list of frequent errors and recommendations on work with the library.

Extensions

Extension location

Structure

If you have an installed @bitrix/cli, the extension structure can be [ds]created[/ds][di] To create an extension:

1) Go to directory local/js/{module}

2) Execute command bitrix create

3) Reply to wizard questions

Learn more...[/di], by executing the command bitrix create.

Extension use

Toolkit: @bitrix/cli

Description

Installation

Configuration

Find more details in the [ds]corresponding lesson.[/ds][di] Extension is a method for organizing JS and CSS in Bitrix24 products.

Learn more...[/di]

Assembly

Assembler recursively finds all files bundle.config.js and executes assembly and transpiling for each config.

Test launch

Creating an extension

@bitrix/cli: building project with NPM

Previous article has covered the console tool [ds]@bitrix/cli[/ds][di] @bitrix/cli is a Bitrix24 developer console tool. The main purpose is to simplify and automate frontend development for Bitrix24 projects.
The following are requirements for normal operation, versions:
Node: 9.11.2
NPM: 5.6.0.

Learn more...[/di]. In this article, we'll overview how to execute assembly for projects with [dw]NPM[/dw][di] NPM (Node Package Manager) is a package manager for JavaScript and for node.js by default. It's used for downloading packages from NPM cloud-based server, or for uploading packages to such servers. [/di].

Nested libraries

Number of nested folders is unlimited. Each new folder must be specified in the extension name, separated by a point:

Vue.js and Bitrix Framework

The Vue library enables the use and customization of Vue components, integrated in the Bitrix Framework core.

This course highlights the direct (and easiest) ways to integrate Vue to Bitrix Framework (CoreJS, localizations, events, inheriting) and explains how to work with Vue components and create Vue-employing applications.

You need to have the following knowledge (basic levels as a minimum) to successfully familiarize yourself with this course:

Integration with Vue.js

What is Vue.js?

Vue is based on the idea of [ds]virtual DOM.[/ds][di] DOM (abbreviated Document Object Model) is the interface for designing a
structural document using objects. It's a platform- and
language-neutral agreement for constructing and deconstructing
data in HTML, XML and etc.

The main issue with DOM is it was never designed for creating dynamic
user interface (UI). We can work with it, using JavaScript and libraries similar to jQuery,
but its use doesn't solve issue with performance.

Instead of interacting with DOM directly, we are working with its lightweight copy.
We can modify the copy based on our requirements,
and then apply the changes to the actual DOM.[/di] This excludes the direct interaction with the interface nodes. Original work is performed with a virtual copy (virtual DOM) and the changes are applied afterwards to the actual interface nodes. Simultaneously, actual DOM tree and its virtual copy are compared, differences pinpointed and only updated sections are re-written. This means that all changes are accumulated for a brief period of time and then these changes are applied to actual interface nodes via a single patch. Due to this, a much higher execution speed is achieved.

Vue is convenient when data is used in several components. In this case, such data is transferred to a dedicated library.

Vue implements all the modern approaches to the development of user interfaces and is a framework that is easy to learn, flexible and highly integrated with third-party technologies.

The Vue library is included in the Bitrix24 On premise products which allows the use and customization of Vue components, integrated in the Bitrix Framework core. The Vue library versioning issue is resolved as well: the Vue version is always the same within current Bitrix Framework.

This section of the course covers the best (and easier) ways to integrate Vue in Bitrix Framework (CoreJS, localizations, events, inheriting).

You can find more details on the framework (including examples of use) at the [ds]official website.[/ds][di] If you are an experienced frontend developer, and you want to know, how Vue differs from other libraries or frameworks, please take a look at the comparisons with the other frameworks.

Learn more...[/di]

Why the framework is included in the product?

We have included the framework into the Bitrix24 products and created BitrixVue for a convenient interaction between Vue and Bitrix Framework.

First: by using BitrixVue, you can integrate into the Bitrix Framework system and work effectively with other components and internal systems (such as localizations and component dynamic load).

Second: resolves issue of versioning, when two developers (for example, two applications from Bitrix24.Market) are using Vue of different versions, causing conflicts. Principally BitrixVue was created to avoid such issues.

Third: Bitrix24 Partner developers gain an opportunity to customize and clone components in Bitrix Framework modules (where it's possible) without changing the product source code.

And finally: Vue framework, that is main part of BitrixVue, is not exported to a global visibility scope. This avoids any issues with third-party applications. Such apps can continue securely using standard Vue connection, including its use in Webpack, without danger of conflicts with library inside Bitrix Framework.

Vue framework versions

Vue 2 ha deprecated and is no longer supported. Please use BitrixVue 3 in your projects (based on Vue 3).

BitrixVue 3

Possibilities, described in this section, are available from the module version ui 22.100.0. Read on how to connect and launch BitrixVue 3 in the corresponding article.

Connecting and launching BitrixVue 3

To work within a page and scripts without transpiling, use the namespace BX.Vue3 to access the features (e. g., use the namespace BX.Vue3.BitrixVue for BitrixVue).

Options, described in this chapter are available from module version ui 22.100.0.

Creating Vue application

BitrixVue.createApp method

BitrixVue.createApp method initializes Vue-based application (root component):

Parameters:

Result:

Method returns initialized Vue instance (application). List of available methods is listed in the documentation (app.*).

Description:

Example

For you to have a full-scale Vue-based application, you need to create a DOM element at the page with Vue instance to be bound.

In addition to the template, the name property will also going to be useful for aesthetically pleasing display of your application in Vue DevTools.

The above example is the easiest variant of interaction. If you want to use all Bitrix Framework capabilities, you need to create a separate JS extension with your own structure, as well as controller that will initialize and launch Vue as required. Read more in the following article: Example of completed Vue-based application.

Example of completed Vue app

Any Vue application is designed for executing a specific task (for example can show list of smileys, list of users or complex CRM forms). Such applications must be collected in the format Bitrix Core.js Extension.

Managing script (entry point, controller)

Such script is used to call the method to BitrixVue.createApp initialize Vue application and bind Vue to a required DOM element. Additionally, you can create a reverse binding to call controller methods from the Vue app.

Example:

/**
 * TaskManger Application
 *
 * @package demo
 * @subpackage local
 * @copyright 2001-2022 Bitrix
 */

import {BitrixVue} from 'ui.vue3';
import {Dom, Loc} from 'main.core';

import {TaskManger} from './component/task-manager';

export class TaskManager
{
	#application;

	constructor(rootNode): void
	{
		this.rootNode = document.querySelector(rootNode);
	}

	start(): void
	{
		const button = Dom.create('button', {
			text: Loc.getMessage('TASK_MANAGER_OPEN'),
			events: {
				click: () => this.attachTemplate()
			},
		});
		Dom.append(button, this.rootNode);
	}

	attachTemplate(): void
	{
		const context = this;

		this.#application = BitrixVue.createApp({
            name: 'TaskManager',
			components: {
				TaskManger
			},
			beforeCreate(): void
			{
				this.$bitrix.Application.set(context);
			},
			template: '<TaskManger/>'
		});
		this.#application.mount(this.rootNode)
	}

	detachTemplate(): void
	{
		if (this.#application)
		{
			this.#application.unmount();
		}

		this.start();
	}
}

Structure elements that require extra attention:

We create the Vue app in the method attachTemplate() and save it in the variable this.#application. This allows to manage Vue application in the future.
Now, let's handle to the webhook beforeCreate:
```
beforeCreate(): void
{
	this.$bitrix.Application.set(context);
}
```
We forward context inside the application - find more details about this mechanism in the lesson Class for link forwarding to the app (execution context). Thanks to this approach, you can get access to the context using the method this.$Bitrix.Application.get() at any level of nesting (this will be useful for implementing the app disabling function).

Next, let's overview the root component <TaskManger/> and how it interacts with the controller:

import {Item} from './item';
import "./task-manager.css";

export const TaskManger =
{
    components:
    {
        Item
    },

    data(): object
    {
        return {
            list: []
        }
    },

    methods:
    {
        addNew(): void
        {
            const result = prompt(this.$Bitrix.Loc.getMessage('TASK_MANAGER_QUESTION'));
            this.list.push(result);
        },

        close(): void
        {
            this.$Bitrix.Application.get().detachTemplate();
        },
    },

    // language=Vue
    template: `
        <div class="taskmanager-list">
            <div class="taskmanager-list-title">{{$Bitrix.Loc.getMessage('TASK_MANAGER_TODAY_TITLE')}}</div>
            <template v-for="(value, index) in list" :key="index">
                <Item :position="index+1" :text="value"/>
            </template>
            <template v-if="list.length <= 0">
                <div class="taskmanager-list-empty">{{$Bitrix.Loc.getMessage('TASK_MANAGER_LIST_EMPTY')}}</div>
            </template>
            <div class="taskmanager-list-buttons">
                <button @click="addNew">{{$Bitrix.Loc.getMessage('TASK_MANAGER_ADD')}}</button>
                <button @click="close">{{$Bitrix.Loc.getMessage('TASK_MANAGER_CLOSE')}}</button>
            </div>
        </div>
    `
};

Please note, you can execute methods of controller which initialized Vue app thanks to the method this.$Bitrix.Application.get().

You can use the event-driven model as well. Please find more details in the article: Event-driven model - Site level events.

Additionally, the listed example shows handling of localizations using $Bitrix.Loc.getMessage.

After creating controller and required components, the last thing to do is to load extension at the page and create a class instance:

<?
\Bitrix\Main\UI\Extension::load("local.taskmanager");
?>

<div id="application"></div>
<script type="text/javascript">
	const taskManager = new BX.TaskManager('#application');
	taskManager.start();
</script>

Example

You can download and launch the example of component, described in this lesson. To do it, perform the following steps:

Download the example taskmanager (utf8);
Unpack the archive at the address /<installation path>/local/js/local/;

Create a public page and connect the extension:

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
?>

<?
\Bitrix\Main\UI\Extension::load("local.taskmanager");
?>

<div id="application"></div>

<script type="text/javascript">
	const taskManager = new BX.TaskManager('#application');
	taskManager.start();
</script>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

Do not forget about the transpiler, If you want to edit the component and add your own custom logic:

Open the terminal;
Go to the local extensions folder cd //local/js/;
Launch the transpiler in the change track mode bitrix build -w. You will see the following text after the launch:
```
 ✔ 12:30:32 Build extension local.taskmanager  js: 3 KB, css: 300 B
```
Update the page: you will see the introduced changes;
Upon new changes, just repeat the item 4.

Components

General information and examples

Component in Vue 3 (just a "component" hereinafter) - is an autonomous application that performs a single task (for example, shows list of smileys or users).

You can find more details about all component features in the Vue 3 documentation: Components basics and Advanced components.

Example

Create new component and call it ButtonCounter:

const ButtonCounter = {  
	data() 
	{
		return {
			count: 0
		}
	},
	// language=Vue
	template: '<button @click="count++">Click counter — {{ count }}</button>'
};

It can be used as user tag inside the root Vue 3 instance, created via BitrixVue.createApp, or in other component template:

import {BitrixVue} from 'ui.vue3';

const ButtonCounter = {  
    data()
    {
        return {
            count: 0
        }
    },
    // language=Vue
    template: '<button @click="count++">Click counter — {{ count }}</button>'
};

BitrixVue.createApp({  
    components: {  
		ButtonCounter  
    },
    template: '<ButtonCounter/>' 
}).mount('#application');

Due to Vue 3 components being re-used Vue instances, they accept the same options, as BitrixVue.createApp: such as data, computed, watch, methods, and life cycle webhooks are well.

Component reuse

Components can be used unlimited number of times:

import {BitrixVue} from 'ui.vue3';

const ButtonCounter = BitrixVue.mutableComponent('ui-button-counter', {
    data()
    {
        return {
            count: 0
        }
    },
    // language=Vue
    template: '<button @click="count++">Click counter — {{ count }}</button>'
});

BitrixVue.createApp({ 
    components: {
		ButtonCounter
    },
    template: `
        <ButtonCounter/>
        <ButtonCounter/>
        <ButtonCounter/>
    ` 
}).mount('#application');

The example uses mutable components BitrixVue. You can find more details on how they operate in the article: Component handling (Mutable components).

Note: Please note, the Vue 3 (different to Vue 2) template root can contain several components and not a single component, as before.

Component operation diagram

Application has a tree-like structure of nested components (for example, separate components for header, side panel, content area, each containing other components for navigation links, blog posts and etc.):

You can find more details on how to handle components in the article: Handling components.

Handling components

BitrixVue supports two local types of components:

First type: classic Vue components based on plain objects without special processing.
Second type: mutable BitrixVue components. This type was created for affiliated third-party developers could customize components, supplied within Bitrix Framework, without the need to modify product source code.

Before selecting a suitable type, you need to determine whether you want to provide access to mutation (component editing) to other developers. If you don't want to - select the first type, if you do - select the second type.

Classic Vue components

This is a standard component format as a standard object with parameters (learn more Vue 3 documentation: Components basics и Advanced components):

const Component = {
	...
};

Example:

import {BitrixVue} from 'ui.vue3';

const Component = {
	template: 'Hello, world!'
};

BitrixVue.createApp({
	components: {
		Component
	},
	template: `
        <Component/>
    `
}).mount('#application');

Component must adhere to the general formatting rules.

Mutable BitrixVue components

Using the method BitrixVue.mutableComponent you can get an object for component local registration. Such components can be mutated by affiliated developers:

BitrixVue.mutableComponent(name: string, definition: object): BitrixVueComponentProxy

Parameters:

name - unique string component identifier, necessary for applying mutation by name (for example: ui-name-local);
definition - object with component parameters, learn more in Vue documentation (Options Api section).

Result:

BitrixVueComponentProxy – specialized BitrixVue component object to be inserted to Vue application. Allows applying mutations via link to object or by identifier.

Note:

The result is the Proxy object for BitrixVue component. This object can be inserted into property components inside any Vue component (including the root component) and use it in the template. Upon inserting of such component, Vue get either the definition object, or definition object with applied mutations, if such were registered until the template rendering.

Such component can be mutated (customized) or cloned.

Component must adhere to general rules for naming and formatting.

Example:

import {BitrixVue} from 'ui.vue3';

const Component = BitrixVue.mutableComponent('module-component', {
	template: 'Hello, world!'
});

BitrixVue.createApp({
	components: {
		Component
	},
	template: `
        <Component/>
    `
}).mount('#application');

Handling of components is reviewed in detail in the lesson Example of component as JS extension.

Component lazy loading

Method BitrixVue.defineAsyncComponent

Vue 3 has introduced a new feature of component lazy loading. Such components will be loaded progressively as required to show them in the template. Special method BitrixVue.defineAsyncComponent is used within BitrixVue to support the lazy loading; it loads components formatted as individual Bitrix Core.js Extension.

Such behavior can be useful when employed in the component not immediately, but when executing an action:

BitrixVue.defineAsyncComponent(extension: string|string[], componentExportName: string, options?: VueAsyncComponentOptions): Promise<object>

Parameters:

Parameter	Description
extension	String ID for Bitrix Core.js extension.
componentExportName	Name for export variable, containing Vue-component.
options	Additional parameters object: `loadingComponent` – Vue component for showing a stub during lazy loading of component; `delay` – delay before showing the loaded component. Default value: 200 m/s; `errorComponent` – Vue component for showing a stub in case of a loading error; `timeout` – error component; will be displayed if standby timeout has been exceeded. Default value: unlimited; `delayLoadExtension` – delay before starting component loading. This parameter is required for testing the stub `loadingComponent`. Default value: not set.

Result:

Promise<object> – a Promise object, that returns Vue component when resolved, for subsequent automatic inserting into template.

Note:

Mechanics for components lazy loading are fairly simple:

You need to pass specially prepared object to components parameter of Vue component and indicate this component in the required location inside the template.
As soon as this component must be displayed, Vue will request the component lazy loading. Our BitrixVue uses Runtime.loadExtension as the loader.
Runtime.loadExtension loads the extension (one or several) after which the function uses a variable indicated in componentExportName to find the component and returns it in the Vue template.

Example

import {BitrixVue} from 'ui.vue3';

BitrixVue.createApp({
	components: {
		AudioPlayer: BitrixVue.defineAsyncComponent('ui.vue3.components.audioplayer', 'AudioPlayer')
	},
	data() {
		return {
			show: false
		}
	},
	template: `
        <button @click="show=!show">Toggle player</button>
        <AudioPlayer v-if="show" src="https://files.johnsmith.com/bitrix/video-ringtone.mp3" style="width: 300px; margin: 10px 0"/>
    `
}).mount('#application');

Example with substituting placeholders

const LoadingComponent = {
	template: `<div>Loading...</div>`,
};

const ErrorComponent = {
	template: `<div>Error while loading...</div>`,
};

BitrixVue.createApp({
	components: {
		AudioPlayer: BitrixVue.defineAsyncComponent('ui.vue3.components.audioplayer', 'AudioPlayer', {
			loadingComponent: LoadingComponent,
			delay: 200,

			errorComponent: ErrorComponent,
			timeout: 3000,

		})
	},
	data() {
		return {
			show: false
		}
	},
	template: `
			<button @click="show=!show">Toggle player</button>
			<AudioPlayer v-if="show" src="https://files.johnsmith.com/bitrix/video-ringtone.mp3" style="width: 300px; margin: 10px 0"/>
		`
}).mount('#application');

If you want to check the operability of placeholders, add the key delayLoadExtension: 10000, in parameters for initializing lazy-loaded component. This will allow to view placeholder for both the lazy loading and for an error.

Component mutation

Use this approach if you must implement changes in an already existing interface instead of creating a new one. You can mutate any mutable BitrixVue components .

Method BitrixVue.mutateComponent

Method for registering component mutations (customizations) without altering product's source code.

When called, registers a mutation to be applied to the component, when it's available:

BitrixVue.mutateComponent(source: string|BitrixVueComponent, mutations: object): boolean

Parameters:

Parameter	Description
source	Component BitrixVue string ID or component BitrixVue object.
mutations	Object with parameters to be replaced in the original component. Corresponds to Vue component parameters. You can find mode details about mutations in the article Component mutation rules.

Result:

boolean:

true – if mutation is registered;
false – if a classic Vue component was passed to the method.

Note:

You can register mutation before and after registering an original component. However, it will be applied only after declaring a mutable component. Please note, if you have registered a mutation after inserting the component into a template, your mutation won't be applied in this application.

You cannot mutate a classic Vue component object, but you can clone it with required alterations - learn more in the article: Component cloning. In contrast to BitrixVue 2, component mutation in BitrixVue 3 no longer applies to clones of original.

Attention! We try to preserve backward compatibility for mutable components, however, it's recommended to check your mutations after product updates (to ensure that component continues to operate as you expected).

Example

Mutate component by name, replace template with a new one (add a frame):

import {BitrixVue} from 'ui.vue3';

BitrixVue.mutateComponent('ui-digits', {
	template: `
		<div style="border: 1px solid red">
			#PARENT_TEMPLATE#
		</div>
	`
});

Mutate component by object, change a calculated property (extend the current list):

import {BitrixVue} from 'ui.vue3';
import {Digits} from 'ui.digits'

BitrixVue.mutateComponent(Digits, {
	computed: {
		digitsList() 
        {
			return [
                ...this.parentDigitsList,
				11, 12, 13, 14, 15
			]; 
        }
    }
});

By executing these two mutations one after another, you will see both the frame and new numbers. This example is reviewed in detail in the article: Component mutation rules.

Rules for component mutations

About mutations

Option to mutate (customize) was created to allow modifying standard component behavior without changing a source code.

Any standard definition object parameter can be subjected to mutation. Such object was used when registering a component or added later by another mutation. Mutation must have only those parameters that you want to edit or add. The rest of parameters will remain unchanged.

You can register mutation before and after registering a mutable component.

Note: In contrast to BitrixVue 2, component mutation in BitrixVue 3 no longer applies to clones of original component.

Mutations are created primarily for mutable components, but you can use them for classic Vue components as well cloning them; learn more in the article Component cloning.

For example, you need to replace the method sendText in the original component. Then the object mutations will look as follows:

{
	methods:
	{
		sendText()
		{
			...
		}
	}	
}

After applying this mutation, the remaining functions will remain unchanged. Adding new method is done in the same manner as is the replacement of existing method. Mutation rules apply to all fields of parameter object, such as methods, props, template and etc.

String values mutation

Sting values can be replaced with option of using the previous text. For this, you need to indicate the name for this parameter, enclosed with hashtag symbols in the new text. For example, new component template can use the original template. For this, add the tag #PARENT_TEMPLATE# to the template.

For example, original template looked as follows:

{
	template: "<span>Hello</span>"
}

Now, use the old template in your new template:

{
	template: "<div>#PARENT_TEMPLATE#, world!</div>"
}

Final layout after component rendering will look as follows:

<div><span>Hello</span>, world!</div>

Object mutation

Objects (such as props, methods, computed, components) can be expanded or replaced by new values.

Additionally, replacing existing parameters in objects allows accessing previous value. Add the parent to the key name and enter the first letter in the uppercase. For example, original component has a calculated property dateText. In a mutation, we can query its name using parentDateText.

Let's review the example of method replacement in case of sendText that sends an event with text to the above component:

{
	methods:
	{
		sendText(text)
		{
			this.emit('send', text);
		}
	}	
}

You are satisfied with method operation, but you want to modify the text before sending:

{
	methods:
	{
		sendText(text)
		{
			// edit the text
			text = '['+text+']';
			
			// call parent method, but now with another text version
			this.parentSendText(text);
		}
	}	
}

Let's overview another example of calculated property with a localization example.

Here's a calculated property that generates localizations in original component:

{
	computed:
	{
		localize()
		{
			return BitrixVue.getFilteredPhrases(this, 'IM_MESSENGER_MESSAGE_');
		},
	},
}

You can add you own phrases without loosing original ones:

{
	computed:
	{
		localize()
		{
			return Object.assign({},
				this.parentLocalize,
				BitrixVue.getFilteredPhrases(this, 'IMOL_MESSAGE_')
			);
		},
	},
}

Mutation of properties: props and watch

The props property cam be presented by both an object and an array. In case original and mutation don't match, the property will be converted to object. In all the rest, the mutation algorithm repeats the general object mutation procedure.

The watch property is a little different from the standard object mutation. It can still use the previous function value, but prefix won't a parent, but parentWatch (its done to avoid mutation errors, when you need to simultaneously edit both calculated property and watcher).

Original component:

watch: {
	counter(current, previous)
	{
		if (current === 5)
		{
			this.watcherText = `Watcher detects change counter ${current}`
		}
	},
},

You have applied the mutation:

watch: {
	counter(current, previous)
	{
		this.parentWatchCounter(current, previous);
		if (current === 10)
		{
			this.watcherText = `Watcher detects change counter ${current}`
		}
	},
},

During operation of the component, the updated counter triggers text updates twice: once at value 5, second time at value 10.

Function mutation

Functions (such as data(), created()) will be replaced with new ones, but you can use them as original versions via prefix parent.

The function data() in the original component:

{
	data()
	{
		return {
			data1: 'text1',
			data2: 'text2',
        }
	}	
}

The method data(), indicated in the mutation:

{
	data()
	{
		return {
			...this.parentData(),
			data2: 'mutated data2',
			data3: 'text3',
        }
	}	
}

Component operational time result:

{
	data1: 'text1',
	data2: 'mutated data2',
	data3: 'text3',
}

Mutation with full replacement

Sometimes, you have to not only modify elements or update current properties, but to completely replace them. You need to indicate the prefix replace to do it, and capitalize the property itself name.

Such approach is supported by the following properties: mixins, inject, emits.

Example:

{
	replaceMixins: [
		textarea
	]
}

Example of complex mutation

Let's present the component that prints values from 1 to 10 as a black text. We will mutate and clone it.

First mutation will change the component in such a way, that it will print the event numbers in red color and uneven numbers - in green color.

Second mutation will add a frame around the template and expand its numerals to 15.

Create second component based on the first one using the cloning, but update it to show numerals in random order.

Important! The clone will be created using the original component (despite to previously applied mutations).

import {BitrixVue} from 'ui.vue3';

const Digits = BitrixVue.mutableComponent('ui-digits', {
	data()
	{
		return {
			digits: [1,2,3,4,5,6,7,8,9,10]
		}
	},
	computed: {
		digitsList() {
			return this.digits;
		}
	},
	template: `
        <span v-for="digit in digitsList" style="padding: 0 5px;">{{digit}}</span>
    `
});

BitrixVue.mutateComponent(Digits, {
	computed: {
		digitsList()
		{
			return [
				...this.parentDigitsList,
				11, 12, 13, 14, 15
			];
		}
	},
	template: `
        <template v-for="digit in digitsList">
            <span v-if="digit % 2" style="color: green; padding: 0 5px;">{{digit}}</span>
            <span v-else style="color: red; padding: 0 5px;">{{digit}}</span>
        </template>
    `
});

BitrixVue.mutateComponent('ui-digits', {
	template: `
        <div style="border: 1px solid red; display: inline-block;">
            #PARENT_TEMPLATE#
        </div>
    `
});




const DigitsRandom = BitrixVue.cloneComponent(Digits, {
	computed:
    {
        digitsList()
        {
            return this.shuffleArray(this.digits)
        }
    },
	methods:
    {
        shuffleArray(array)
        {
            for (let i = array.length - 1; i > 0; i--)
            {
                const j = Math.floor(Math.random() * (i + 1));
                [array[i], array[j]] = [array[j], array[i]];
            }
            return array;
        }
    },
});



BitrixVue.createApp({
	components: {
		Digits,
		DigitsRandom
	},
	template: `
        <div><strong>Mutated component - colors and numerals</strong></div>
        <Digits/>

        <div><strong>Cloned component - random order</strong></div>
        <DigitsRandom/>
    `
}).mount('#application');

Component cloning

Method BitrixVue.cloneComponent

Sometimes the component fits into the project, except for a single action (for example, you need to insert a selected smiley as [smile], but not as :smile:). Or, a default component template is not suitable for your project, but you are okay with the rest of component parts (for example, database data retrieval, actions, events).

In this case, you can clone an existing component and update any required elements inside it, without touching the rest of features.

In contrast to Component mutation, you can clone any component, whether BitrixVue component or classic Vue component. Find more details about mutations (and their types) in the article Component mutation rules.

The method BitrixVue.cloneComponent allows cloning a local component and to mutate (customize) without changing the original component:

BitrixVue.cloneComponent(source: string|object|BitrixVueComponent, mutations: object): BitrixVueComponentProxy

Parameters:

Parameter	Description
source	BitrixVue component string ID, BitrixVue component object or classic Vue component object.
mutations	Object of parameters to be replaced in original component. Corresponds to Vue component parameters. Read more in the article: Component mutation rules.

Result:

BitrixVueComponentProxy is a specialized BitrixVue component object to be inserted into Vue application. Allows to apply mutations using object links.

Note:

Result of this function will be Proxy object for BitrixVue component. This object can be inserted into the property components in any Vue component (including the root component) and used in the template. Upon inserting such component, Vue gets a definition object, or a definition object with applied mutations, if such were registered before template rendering.

If you are cloning component by name, original component must be loaded before the a clone is inserted into component template.

In contrast to BitrixVue 2, in BitrixVue 3 components are cloned using not the final component version (original + mutations), but always using original.

Important! We strive to preserve backward compatibility of mutable components. However, you need to verify the availability of your mutations after product updates (to ensure that component continues to successfully operate as expected). Take extra caution with operability check if you clone classic objects of Vue components: backward compatibility for them is not guaranteed!

Examples

import {BitrixVue} from 'ui.vue3';
import {Local} from 'ui.components.local';

const LocalByObject = BitrixVue.cloneComponent(Local, {
	template: `
		Clone BitrixVue component by Object. Previous template: #PARENT_TEMPLATE#
	`
});

import {BitrixVue} from 'ui.vue3';

const LocalByName = BitrixVue.cloneComponent('ui-local', {
	template: `
		Clone BitrixVue component by Name. Previous template: #PARENT_TEMPLATE#
	`
});

import {BitrixVue} from 'ui.vue3';
const LocalVue = {
	template: `Base local component.`
}

const LocalVueByObject = BitrixVue.cloneComponent(LocalVue, {
	template: `
		Clone Vue component by Object. Previous template: #PARENT_TEMPLATE#
	`
});

Example of component as JS extension

What to remember

Before creating a component you need to decide, which component do you require: classic or mutable.

If a component is created for internal objectives and you are not ready to support backward compatibility – its a [ds]classic Vue component[/ds][di] There are two local components supported by BitrixVue:

First type are classic Vue components based on simple objects without special processing.

Second type are BitrixVue mutable components. This type is created for affiliated third-party developers. They can customize components supplied within Bitrix Framework, without necessity to modify product's source code.

Learn more...[/di]. When you develop a component that can be changed by a third party – its a [ds]mutable BitrixVue component[/ds][di] There are two local components supported by BitrixVue:

First type are classic Vue components based on simple objects without special processing.

Second type are BitrixVue mutable components. This type is created for affiliated third-party developers. They can customize components supplied within Bitrix Framework, without necessity to modify product's source code.

Learn more...[/di].

You must create components as СoreJS extensions in new format.

Do not forget this

Naming
There are several rules for naming and export. For more details, please read the article: Component naming and import.
Component properties
Component properties are structured and overviewed in detail in the following article: Generating and sorting component properties.
Localization
BitrixVue 3 components can handle with localizations and this aspect is overviewed in detail in the article: Handing localization.
Event-driven model
There are several types of events. You can find how to select a suitable event in this article: Event-driven model.
Handling $Bitrix global variable functions
In addition to localizations and event-drive model, there are several additional classes that help to better reveal interaction with Bitrix Framework. You can find more in this article: Interaction with Bitrix Framework.

Local component file content

Note: Naming variable for export doesn't contain the module - only the component name in PascalCase.

/**
* Some Vue3 сomponent
*
* @package bitrix
* @subpackage module
* @copyright 2001-2022 Bitrix
*/

import {BitrixVue} from 'ui.vue3';

export const Component = {
	
	/**
	 * @bitrixEvents 'module:component:eventName' {} (global)
	 */

	emits: ['sendEvent'],

	props:
    {
        ...
    },

	data()
	{
		return {
			...
		}
	},

	computed:
    {
        ...
    },

	created()
	{
		this.$Bitrix.eventEmitter.subscribe('module:component:eventName', this.onDoSomething);
	    ...
	},

	beforeUnmount()
	{
		this.$Bitrix.eventEmitter.unsubscribe('module:component:eventName', this.onDoSomething);
	    ...
	},
	methods:
		{
			onDoSomething(event)
			{
			    ...
			}
		},
	// language=Vue
	template: `
        ...
        {{$Bitrix.Loc.getMessage('MODULE_PHRASE_CODE_1')}}
		...
	`
};

File content for mutable BitrixVue component

Mutable component contents fully repeat the abovementioned classic Vue component. The only difference is the registration method.

/**
* Some BitrixVue3 component
*
* @package bitrix
* @subpackage ui
* @copyright 2001-2021 Bitrix
*/

import {BitrixVue} from 'ui.vue3';

export const Component = BitrixVue.component('module-component', {
	...
});

Example

We have prepared several example of component handling:

example of classic Vue component;
example of BitrixVue component;
example of lazy-loading.

Perform the following steps to launch an app demo:

Download the demo (utf8);
Unpack the archive at the URL address /<installation location>/local/js/local/;

Create public page and connect the extension:

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
?>

<?
\Bitrix\Main\UI\Extension::load("local.demo.application");
?>

<div id="application"></div>

<script type="text/javascript">
	const application = new BX.DemoApplication('#application');
	application.run();
</script>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

Open this page in browser to view the result:

If you want to edit the component and add your own custom logic, do not forget to launch the transpiler:

Open the terminal;
To to the folder for local extensions at cd /<installation path>/local/js/;

Launch transpiler in changes track mode bitrix build -w to see the following text upon launch:

 ✔ 11:19:44 Build extension local.demo.application  js: 2 KB, css: 170 B
 ✔ 11:19:44 Build extension local.demo.components.async  js: 312 B
 ✔ 11:19:44 Build extension local.demo.components.bitrixvue  js: 646 B
 ✔ 11:19:44 Build extension local.demo.components.vue  js: 546 B

Update the page: the implemented modifications will become visible;
In case of new updates, just repeat the item 4.

General rules for formatting and order

It's recommended to allocate Vue components in the folder components at the first level of module JS extensions, for example, /modules/timeman/install/js/timeman/components/.

If your component uses Vue as template engine and all logic is located in JS extension, then Vue component is located in the folder src/components.

You can read more about component naming in this article: Component naming and import.

The Vue developer community has a current special component/instance options order. We recommend to strictly follow it in the components for BitrixVue 3 as well.

Vue 3 components are written in such a manner, that you can clearly understand at the superficial glance, which input parameters are used (props), what internal data (data) and which events are emitted (emits).

If you component creates and stands by for an event from EventEmitter, you must describe them at the start of component: this will significantly help other developers.

You can read about component formatting in the article: Component properties formatting and order.

Component property formatting and order

Component formatting and property order

Options for component/instance must be consistently ordered

The Vue developer community has a current special order for blocks. We recommend to strictly follow it in the components for BitrixVue 3 as well.

Indicating the employed events

Vue 3 components are written in such a manner that you can clearly understand at the superficial glance, which input parameters are used (props), what internal data (data) and which events are emitted (emits).

If your component creates or stands by for events from EventEmitter, you must describe them at the start of component: this will significantly help other developers.

Events in components (emits)

When your component creates a component-dedicated event (local event), you need to describe it at the component's start. Other developers can identify necessary events, without studying the code of Your component.

Event description for the component this.$emit('sendMessage', {text: 'Some text'}):

{
    ...
    emits: ['sendMessage']
    ...
}

Listeners in components (BitrixEvents)

You need to describe it at the start of component if it listens to events at the website or application level. Other developers will be able to learn that component can react to external events without studying your code in detail.

Description is prepared in a comment format; event name must start with the module name, followed by component and action name. Such format will fully exclude conflicts between names of various components.

/**
 * @bitrixEvents 'ui:textarea:insertText' {text: string} (application)
 */

You can generate subscription to such events in the component method created and not forget to unsubscribe from event in the method beforeDestroy.

You can learn more about event-driven model in the article under the same name.

Component naming and import

Component naming

It's recommended to allocate Vue components in the folder components at the first level of module JS extensions, for example, /modules/timeman/install/js/timeman/components/.

If your component uses Vue as template engine and all logic is located in JS extension, then Vue component is located in the folder src/components.

Naming local component

export const Component = {...};

Variable for export shouldn't contain the module, only the component name in PascalCase.

Registering local components in target component looks as follows:

import {ComponentName} from './component/name';
import {ComponentSubName} from './component/subname';

export const BaseComponent = {
	...
	components:
	{
		ComponentName,
		ComponentSubName
	},
	...
	// language=Vue
	template: `
        <ComponentName/>
        <ComponentSubName/>
	`
};

Please note, component is named in the template's PascalCase the same as you have indicated during import.

Such notation allows to understand at superficial glance which components are local and which are global.

Additionally, by name searching you can easily find a necessary object in the import and can switch to its source code.

Naming a mutable component

export const ComponentName = BitrixVue.mutableComponent('module-component-name', {
	...
});

Component name must start from the module name and end by the component name in kebab-case.

Export variable is generated the same as for the local component.

Examples for naming, depending on the location:

/modules/timeman/install/js/timeman/components/schedule/ – component name is timeman-schedule;
/modules/im/install/js/im/components/dialog/list/ – component name is im-dialog-list;
/modules/ui/install/js/ui/vue/components/hint/ – component name is ui-hint;
/modules/ui/install/js/ui/picker/src/components/selector.js – component name is ui-picker-selector.

Such name allows avoiding collisions between modules and quickly find a needed component if required.

When your module has components for two framework versions, you need to directly designate the version to prevent confusion when connecting.

Important! When component name includes a dash - a dedicated folder is optional. For example, timeman-day-control in file structure looks as /modules/timeman/install/js/timeman/components/day-control/.

Directives

In addition to native directives (such as v-model и v-show), Vue 3 also allows you to register your own custom directives.

It's an important to know that you need to use components instead of directives to create repeatedly used content.

Nevertheless, user directives can be very useful for executing low-level operations with DOM and when configuring supplemental behaviour (for example, action when hovering on the element).

You can find more details on capabilities of directives in the Vue documentation.

Registering directives

Local directive - const directive = {...}

Directive parameter object: you learn more in Vue documentation.

const directive = {
	...definition...
};

Example

export const focus = {
	mounted: (el) => el.focus()
};

Please note, the first letter of variable is in lower case. This is done to avoid re-naming it locally after registering the directive in your application or component.

import {focus} from './directives/focus';

const Component = {
	directives: {
		focus
    },
    template: `
        <input v-focus>   
    `
}

Important! If you use animation for display (showing content due to visibility area limits), then do not use autofocus directives, because the browser will momentarily set the focus on the element outside the visibility limits and animation won't look as expected.

Example of directive as JS extension

Directive naming mirrors component rules with single difference: target folder is directives instead of components .

All directives must be created as СoreJS extensions in new format.

JS main file content:

/**
* @package local
* @subpackage demo
* @copyright 2001-2022 Bitrix
*/

/* 
	Example of usage:
	...
*/

import {SomeClassForDirectiveLogic} from './logic'; // if needed

const directiveName = {
	created(element, bindings)
	{
		...
		SomeClassForDirectiveLogic::method(element);
		...
	}
};

Inside the file, you need to indicate an example of directive use, or a link to documentation in the format JsDoc.

When complex logic is required, you can move it outside of directive limits.

Variable name for export must start with lower case character.

Example of user directive in format Bitrix Core.js can be downloaded: here.

Interaction with Bitrix Framework

Global variable $Bitrix details

All integration methods are located inside a single variable $Bitrix that is available at any level of BitrixVue 3 component: in calculated property, function, life cycle hook or a template.

Access to the $Bitrix variable

The $Bitrix variable is built based in the calculated property. Thanks to this, it can be called in a customary notation in any component location:

In template

in text interpolation format (not available for all methods):

template: `
	{{ $Bitrix.Loc.getMessage('EXAMPLE_PHRASE') }}
`

Template elements:

template: `
	<div @click="$Bitrix.eventEmitter.emit('module:component:eventName')" :title="$Bitrix.Loc.getMessage('EXAMPLE_PHRASE')">Click me</div>
`

In component
The access is performed in the component in the same manner as in any other variable – via this.. However, there are specifics.

All component webhooks and methods are accessed via the variable this.$Bitrix:
```
created()
{
	this.$Bitrix.eventEmitter.subscribe('module:component:eventName', () => alert('catch!'));
}
```
```
computed:
{
	counter()
	{
		return this.$Bitrix.Log.getMessage('DEMO_COUNTER', {'#COUNTER#': this.counter}); 
    }
}
```
There is an exception: webhook beforeCreate. You need to query via this.$bitrix:
```
beforeCreate()
{
	this.$bitrix.Loc.setMessage({'DEMO_COUNTER': 'Counter: #COUNTER#'});
}
```
This exception has its roots from the integration method. Because the $Bitrix variable was created based on the calculated property, it's not yet available in the webhook beforeCreate. That's why its necessary to query the original property this.$bitrix.

Method list

this.$Bitrix.Application – for link forwarding to application (execution context)
this.$Bitrix.Loc – class for handling localizations
this.$Bitrix.eventEmitter – class for handling events at the app level
this.$Bitrix.Data – class for handling global data
this.$Bitrix.RestClient – class for handling REST-content
this.$Bitrix.PullClient – class for handling Pull client

Class for context forwarding

Class $Bitrix.Application

This class allows to forward an application link (execution context) and when app (controller) methods from the component of any nesting level.

You can also use an event-driven model. You can find more details in the article: Event-driven model.

Access to functions inside the component is performed in the same manner as in any other variable – via this.. There are, however, nuances of use in the hook beforeCreate that are detailed in the chapter description.

Methods $Bitrix.Application
$Bitrix.Application.set	Method sets link to application (execution context).
$Bitrix.Application.get	Method gets link to application (execution context).

$Bitrix.Application.set

Method saves link to application (execution context).

this.$Bitrix.Application.set(instance: Object): void

Parameters:

Parameter	Description
instance	Link to application object (for subsequent access).

Example:

import {BitrixVue} from 'ui.vue3';

class TaskManager
{
	...
	attachTemplate(): void
	{
		const context = this;

		this.#application = BitrixVue.createApp({
			name: 'TaskManager',
			components: {
				TaskManger
			},
			beforeCreate(): void
			{
				this.$bitrix.Application.set(context);
			},
			template: '<TaskManger/>'
		});
		this.#application.mount(this.rootNode)
	}
	...
}

$Bitrix.Application.get

Method gets link to application (execution context).

this.$Bitrix.Application.get(): Object

Result:

Object – link to application object, must be set when creating Vue application.

Example:

const Component = {
	...
	methods: 
	{
		close() 
		{
			this.$Bitrix.Application.get().closeWindow();
		}
	},
	// language=Vue
	template: `
		<div class="component">
		    ...
			<button @click="save">Save</button>
			<button @click="close">Close</button>
		</div>
	`
});

Other example with the context forwarding is overviewed in detail in the article: Example of completed Vue application.

Class for handling localizations

Class $Bitrix.Loc

Class allows to organize the handling of localizations in Vue components (in application, created via BitrixVue.createApp).

Методы $Bitrix.Loc
$Bitrix.Loc.getMessage	Method returns language phrase by ID.
$Bitrix.Loc.getMessages	Method gets all language phrases, available within Vue application.
$Bitrix.Loc.setMessage	This method can set language phrases for Vue application.

Also, the article describes the method BitrixVue.getFilteredPhrases that reads the object BX.message and selects only the phrases related to your Component to be used in the template (selection is performed by prefix).

$Bitrix.Loc.getMessage

Method returns language phrase by ID.

this.$Bitrix.Loc.getMessage(name: string, replacements?: {[key: string]: string}): string;

Parameters:

Parameter	Description
name	Phrase string ID.
replacements	Object with replacements. Allows to replace placeholders with required data (optional parameter, supports reactive properties).

Use inside template:

In text interpolation format:

template: `
	UserId is {{ $Bitrix.Loc.getMessage('USER_ID') }}
`

In template parameters:

template: `
	<div :title="$Bitrix.Loc.getMessage('FD_LAST_SEEN_MORE_YEAR')">Hover me</div>
`

Please note: function supports a second parameter with replacements. When use method in template or calculated property, replacements will be reactive:

const Counter = {
	data()
	{
		return {
			counter: 0
		}
	},
	created()
	{
		setInterval(() => this.counter++, 1000);
	},
	// language=Vue
	template: `
		{{$Bitrix.Loc.getMessage('DEMO_COUNTER', {'#COUNTER#': this.counter})}}
	`
};

Use in component:

Access to functions inside the component is performed in the same manner as in any other variable: via this.. There are nuances of use, however, in the hook beforeCreate and specifics of use are indicated in chapter description.

created()
{
	const message = this.$Bitrix.Loc.getMessage('EXAMPLE_PHRASE');
}

beforeCreate()
{
	const message = this.$bitrix.Loc.getMessage('EXAMPLE_PHRASE');
}

computed: {
	counter()
	{
	    return this.$Bitrix.Loc.getMessage('DEMO_COUNTER', {'#COUNTER#': this.couter});
    }
}

$Bitrix.Loc.getMessages

Method for getting all language phrases, available within Vue application.

this.$Bitrix.Loc.getMessages(): object

$Bitrix.Loc.setMessage

This method can set language phrases for Vue application.

Note: Language phrases from components are set automatically and you won't need to set them manually.

If your component operates not only inside Bitrix24 but also as an external widget (online forms, online chat widget), you have to use this method for Vue application to have access to language phrases.

this.$Bitrix.Loc.setMessage(id: string | {[key: string]: string}, value?: string): void;

Parameters:

Parameter	Description
id	Phrase string ID.
value	Phrase value (localization).

Possible variant for calling the method, when the function's first parameter passes the localization object in the format {key1: "value1", ...}

Example:

Access to functions inside the component is performed in the same manner as to any other variable - via this.. There are, however, nuances of use in the hook beforeCreate. You can find details in the chapter description.

beforeCreate()
{
    this.$bitrix.Loc.setMessage('DEMO_COUNTER', 'Counter: #COUNTER#');
	
    this.$bitrix.Loc.setMessage({
        DEMO_COUNTER: 'Счетчик: #COUNTER#',
        DEMO_PHRASE_2: 'Фраза 2',
    });
}

BitrixVue.getFilteredPhrases

The method BitrixVue.getFilteredPhrases reads the object BX.message and selects only the phrases related to your component (selected by prefix) for subsequent use in the template.

This method is rarely used. One of examples is described in the article: Handling localizations.

BitrixVue.getFilteredPhrases(phrasePrefix: string|Array<string>, phrases?: object|null): ReadonlyArray<any>;

Parameters:

Parameter	Description
phrasePrefix	Phrase prefix. All phrases, started from with this prefix will be returned in the result. In addition to the indicated string, there is no more option to handle array with prefixes, for example, `['PREFIX_1', 'PREFIX_2']`.
phrases	Arbitrary set of phrases, optional field. By default, uses the object BX.message. If you use the component as an external widget, then pass `this` to this parameter (vue component context).

Result:

ReadonlyArray – returns frozen (Object.freeze) localization object, filtered by specified prefix.

Example:

import {BitrixVue} from 'ui.vue3';

const Component = {
	...
	computed: 
	{
		localize()
		{
			return BitrixVue.getFilteredPhrases('PREFIX_');
		}
	},
	...
	
	template: `
		{{ localize.PREFIX_PHRASE_1 }}
	`
};

Class for handling app-level events

Class $Bitrix.eventEmitter

This class is created to organize events at the Vue application level.

You can find more details about event-driven model in this separate article.

Methods $Bitrix.eventEmitter

The variable $Bitrix.eventEmitter is an instance of class EventEmitter with specified namespace for current application.

Only key methods are described within this article:

Subscription to an event
```
this.$Bitrix.eventEmitter.subscribe(event: any, listener: (event: BaseEvent) => void): EventEmitter
```
Adds handler to an indicated event. The first parameter passes object type BaseEvent as the first parameter from the extensionmain.core.events to the handler.
One-time subscription to event
```
this.$Bitrix.eventEmitter.subscribeOnce(event: any, listener: (event: BaseEvent) => void): EventEmitter
```
Adds a handler of specified event, called only once. Passes the object type BaseEvent from extension main.core.events as the first parameter to the event handler.

Unsubscription from event

this.$Bitrix.eventEmitter.unsubscribe(event: any, listener: Function) => void): EventEmitter

Deletes event handler, installed previously.

Event publication
```
this.$Bitrix.eventEmitter.emit(eventName: any, event?: BaseEvent | {[key: string]: any}): EventEmitter
```
Sends event with specified event code.

We recommend to use name of event in the following format: module name, then component name and action name. Such format fully excludes conflict of names between different components.

Example: ui:textarea:insertText

Example

Let's overview example of interaction at the application level. Components are located at the same level and interact with each other.

Access to functions inside the component are performed in the same manner as to any other variable – via this.. There are, however, nuances of use in the hook beforeCreate. You can find more details in the chapter description.

import {BitrixVue} from 'ui.vue3';
import {BaseEvent} from "main.core.events";

const ComponentRecipient = {
	/**
	 * @bitrixEvents 'local:recipient:alert' {text: string} (application)
	 */
	data() {
		return {
			alertText: 'Wait text...'
		}
	},
	mounted()
	{
		this.$Bitrix.eventEmitter.subscribe('local:recipient:alert', this.onAlert);
	},
	beforeUnmount()
	{
		this.$Bitrix.eventEmitter.unsubscribe('local:recipient:alert', this.onAlert);
	},
	methods:
	{
		onAlert(event)
		{
			const {text} = event.getData();
			this.alertText = text;
		}
	},
	template: `
	  {{alertText}}
	`
};

const ComponentSender = {
	methods: {
		sendText1()
		{
			this.$Bitrix.eventEmitter.emit('local:recipient:alert', {text: 'Text from button number 1'});
		},
		sendText2()
		{
			this.$Bitrix.eventEmitter.emit('local:recipient:alert', {text: 'Text from button number 2'});
		}
	},
	template: `
		<button @click="sendText1">Text 1</button>
		<button @click="sendText2">Text 2</button>
	`
};

BitrixVue.createApp({
	components: {
		ComponentRecipient,
		ComponentSender
	},
	template: `
	  Component 1: <ComponentSender/> <br/>
	  Component 2: <ComponentRecipient/>
	`
}).mount('#application');

Note: $Bitrix.eventEmitter is not a replacement to standard events, but one of the options for additional interaction. Find more details in the article: Event-driven model.

Class for handling global data

Class $Bitrix.Data

Class allows to save arbitrary data in the context of Vue application and retrieve them from the component of any nesting level.

This class is not a replacement for reactive variables from objects props and data, as well as to Provide/Inject approach. It allows to organize interaction between components without complex sync system.

Методы $Bitrix.Data
$Bitrix.Data.set	Method to save data.
$Bitrix.Data.get	Method to get data.

$Bitrix.Data.set

Method to save data.

this.$Bitrix.Data.set(name: string, value: any): void

Parameters:

Parameter	Description
name	Variable name.
value	Variable value.

$Bitrix.Data.get

Method to get data.

this.$Bitrix.Data.get(name: string, defaultValue?:any): any

Parameters:

Parameter	Description
name	Variable name.
defaultValue	Default value. When not specified – `undefined`.

Result:

When data with the key name won't be found, returns their value. Otherwise, function returns defaultValue.

Example

For example, we want to implement an audioplayer feature. When several player components are located at the page, we need to start the playback of the record when audio record ends.

This can be done as follows:

import {BitrixVue} from 'ui.vue3';

const AudioPlayer = {
	...
	registerPlayer(id): void
	{
		let registry = this.$Bitrix.Data.get('ui-audioplayer-id', []);

		registry = [...new Set([...registry, id])]
			.filter(id => id !== this.registeredId)
			.sort((a, b) => a - b)
		;

		this.$Bitrix.Data.set('ui-audioplayer-id', registry);
		
		this.registeredId = id;
	},
	unregisterPlayer(): void
	{
		const registry = this.$Bitrix.Data.get('ui-audioplayer-id', []).filter(id => id !== this.registeredId);

		this.$Bitrix.Data.set('ui-audioplayer-id', registry);

		this.registeredId = 0;
	},
	playNext(): boolean
	{
		const nextId = this.$Bitrix.Data.get('ui-audioplayer-id', []).filter(id => id > this.registeredId).slice(0, 1)[0];
		if (nextId)
		{
			this.$Bitrix.eventEmitter.emit('ui:audioplayer:play', {id: nextId, start: true});
		}

		return true;
	}
	...
});

Full example can be viewed in the component bx-audioplayer, located in the [dw]file[/dw][di] Available from version ui 22.100.0. [/di] /bitrix/modules/ui/install/js/ui/vue3/components/audioplayer/src/audioplayer.js.

Access to functions inside the component is performed in the same manner as to any other variable - via this.. There are, however, nuances of use in the hook beforeCreate. You can find more details in the chapter description.

Class for handling REST client

Class $Bitrix.RestClient

Class allows to organize the handling of REST client from Bitrix Framework. If your component operates not only inside Bitrix24 but also as an external widget (online forms, online chat widget), you need to use this class. In the rest of cases, use the import of import {rest as Rest} from 'rest.client'.

Методы $Bitrix.RestClient
$Bitrix.RestClient.get	Method for getting current configured REST client for current application (for external third-party applications).
$Bitrix.RestClient.set	Method for installing a new REST client in the current Vue application.
$Bitrix.RestClient.isCustom	This method can be used to find out, if standard REST client was edited.

$Bitrix.RestClient.get

Method for getting current configured REST client for current application (for external third-party applications).

this.$Bitrix.RestClient.get(): RestClient

Result:

RestClient – configured REST client.

$Bitrix.RestClient.set

Method for setting new REST client in the current Vue application.

this.$Bitrix.RestClient.set(instance: RestClient): void

Parameters:

Parameter	Description
instance	RestClient - configured REST client.

Additionally:

When the method this.$Bitrix.RestClient.set was not called, uses the REST client by default: BX.rest. It won't be suitable resources and you need to initialize your own client when initializing Vue application. Example can be the function initRestClient, described in the file /bitrix/modules/imopenlines/install/js/imopenlines/component/widget/src/widget.js.

$Bitrix.RestClient.isCustom

Using this method can inform you if the standard REST client was edited.

this.$Bitrix.RestClient.isCustom(): boolean

Event BitrixVue.events.restClientChange

In case, you need to react to a REST client change, you can subscribe to an edit event:

import {BitrixVue} from 'ui.vue3';
this.$Bitrix.eventEmitter.subscribe(BitrixVue.events.restClientChange);

Examples

Setting a specialized REST client

import {BitrixVue} from 'ui.vue3';

class Widget
{
	...
	attachTemplate()
	{
		const restClient = this.restClient;
		        
		this.#application = BitrixVue.createApp({
			components: {
				Component	
			},
			beforeCreate() 
			{
				...
				this.$bitrix.RestClient.set(restClient);
			},
			template: '<Component/>'
		}).mount(this.rootNode);
	}
	...
}

Handling REST client

const Component = {
	...
	created(): void
	{
		this.#rest = this.$Bitrix.RestClient.get();
	},
    methods:
	{
		getProfile(): void
		{
		    this.#rest.callMethod('profile').then(result => {
                console.log(result.data());
            });
        }
    },
	...
});

Class for handling Pull client

Class $Bitrix.PullClient

Class allows to organize handling Pull client from Bitrix Framework. If your component works not only inside Bitrix24 but also as the external widget (online forms, online chat widget), you need to use this class. In all the rest of cases, use the import import {PULL as Pull} from 'pull.client'.

Methods $Bitrix.PullClient
$Bitrix.PullClient.get	Method for getting current configured Pull client for current application (for external applications).
$Bitrix.PullClient.set	Method for setting new Pull client into current Vue application.
$Bitrix.PullClient.isCustom	This method allows to find out if standard Pull client was edited.

$Bitrix.PullClient.get

Method for getting current configured Pull client for current application (for external third-party applications).

this.$Bitrix.PullClient.get(): PullClient

Result:

PullClient – configured Pull-client.

$Bitrix.PullClient.set

Method for setting new Pull client into current Vue application.

this.$Bitrix.PullClient.set(instance: PullClient): void

Parameters:

Parameter	Description
instance	PullClient - configured Pull client.

Additionally:

When the method this.$Bitrix.PullClient.set was not called, uses the default Pull client BX.PULL. It won't be suitable for external resources and you need to initialize your own client when initializing Vue application. Example can be the function initPullClient, described in the file /bitrix/modules/imopenlines/install/js/imopenlines/component/widget/src/widget.js.

$Bitrix.PullClient.isCustom

Using this method can get you the information if the standard Pull client.

this.$Bitrix.PullClient.isCustom(): boolean

Event BitrixVue.events.pullClientChange

When you need to react to a Pull client update, you can subscribe to a change event:

import {BitrixVue} from 'ui.vue3';
this.$Bitrix.eventEmitter.subscribe(BitrixVue.events.pullClientChange);

Examples

Access to functions inside the component is performed in the same manner as to any other variable – via this.. There are, however, nuances of use in the hook beforeCreate. You can find more details in the < a href="/support/training/course/index.php?COURSE_ID=68&CHAPTER_ID=024720#interpolation" target="_blank"> chapter description .

Setting a specialized Pull client

import {BitrixVue} from 'ui.vue3';

class Widget
{
    ...
	attachTemplate()
	{
		const pullClient = this.pullClient;

		this.#application = BitrixVue.createApp({
			components: {
				Component
			},
            beforeCreate()
			{
			...
				this.$bitrix.PullClient.set(pullClient);
			},
			template: '<Component/>'
		}).mount(this.rootNode);
	}
    ...
}

Handling a Pull client

import {BitrixVue} from 'ui.vue3';

const Component = {
	...
    created(): void
	{
		this.#pull = this.$Bitrix.PullClient.get();
	},
	created()
	{
		this.#pull.subscribe({
			moduleId: 'im',
			command: 'messageChat',
			callback: (params, extra, command) => {
				console.warn('Receive message:', params.message.text)
			}
		});
	},
	...
});

Best practices

This chapter describes principles and actions that will help most effectively solve various tasks.

Localizations handling – how to display localization phrase in template (two approaches, different in performance characteristics);
Event-driven model – three levels of event-base model: when to use each of such levels;
Performance – creating an unmodifiable object; indicating the key :key when using the cycle v-for;
Tips and tricks – clickable variables inside the template; use of focus and animation.

Localization handling

All JS components within Bitrix Framework (as well as php-enabled components) have an integrated localization support. BitrixVue 3 components are not an exception.

To show localization in the template, use the method $Bitrix.Loc.getMessage.

template: `
	{{ $Bitrix.Loc.getMessage('EXAMPLE_PHRASE') }}
`

More examples for handling localizations can be found in the article Localization class.

Performance

Such format to access localizations is sufficiently quick. However, it has specific overeheads: you need an additional 1ms during template rendering for a 1000 phrases during re-drawing (in actuality, time can be less, because not all blocks in Vue component require re-drawing).

When its significant for your app (for example, number of phrases is multi-fold larger) – use the approach with employed method BitrixVue.getFilteredPhrases. This method creates a calculated property which allows querying phrases as a static property (in contrast to $Bitrix.Loc.getMessage, where each call is processed by function).

Event-driven model

BitrixVue 3 applications allows you to work with three levels of event-driven model:

Component-level events (standard Vue events)
Application-level events ($Bitrix.eventEmitter)
Site-level events (Global EventEmitter)

Let's overview all three types and define cases when need to use each.

Component-level events
Vue application standard events: Vue user events. This level of events shall be used for interaction between component and its parent.

Such approach is very convenient to use, when you need to throw an event up one level. But, if you need to throw event to several levels or to a neighbouring component at the same level – such task doesn't look so simple anymore. For this purpose, there is a special format: Application-level events.
Application-level events
Application-level events can be useful, when you need to throw an event to several levels up or at the same level as your component. Such events won't be caught and processed by other Vue applications at this page.

Within Vue 3 you cannot organize events at the app level. According to developer recommendation an external event-driven model must be used in the current version.

In BitrixVue 3 we have introduced integration with our standard EventEmitter from Bitrix Framework. The variable $Bitrix.eventEmitter is an instance of EventEmitter class with specified namespace for current application. YOu can find extra details about the setup layout and view examples in the following article: Class for handling app-level events.
Site-level events
When you need to interact with other system elements outside the current Vue application, you need to use global Event.EventEmitter from the Core.js library (extension main.core.events).

Such mechanism will be suitable for passing events between two different Vue applications within a single page or for interacting with other Bitrix Framework interfaces.

Event description in component (JSDoc)

Events from all three levels of event-driven model shall be described inside components. You can find mode details on how to do it in the article: Component property formatting and order.

Performance

Object.freeze

When data doesn't require a reactive behavior (i. e., for constants or language phrases), you need to create an unmodifiable object. This helps save resources of your app.

computed: 
{
	applicationConstants(state)
	{
		return Object.freeze({
			const1: 'value 1',
			const2: 'value 2'
		})
	}
}

v-for and element key

When using the cycles v-for, always indicate the :key. This allows template engine to correctly perform animations and optimizes DOM tree rendering when updating the data. Read more details in the article Use of Key in lists.

<template v-for="operator in operators" :key="operator.id">
	<div class="imopenlines-user">
		<div class="imopenlines-user-name">{{operator.name}}</div>
	</div>
</template>

Tips and tricks

Clickable variables in template

For your template to be not just an HTML text and have an operational semantic highlighting in PhpStorm - indicate a special tag before the template:

// language=Vue
template: `
	...
`

Focus and animations

When you use fade-in animation (content appears outside area of visibility), do not use autofocus commands, because browser will immediately focus on the element outside the visibility area and animation will look not as intended.

directives:
{
	focus:
	{
		inserted(element, params)
		{
			element.focus();
		}
	}
},

DevTools setup

By default, BitrixVue 3 is launched in the production mode without hints.

To switch to development mode you need to add the following constant to /bitrix/php_interface/init.php:

define('VUEJS_DEBUG', true);

In case you need to disable localizations in Vue application (and show codes for localization phrases), add one more constant:

define('VUEJS_LOCALIZATION_DEBUG', true);

Vue Devtools for browser

To effectively debug your app, you need to install the plugin Vue.js devtools from Google Chrome or Mozilla Firefox web store (all current links can be found at the Vue Devtools website).

In addition to component components debugging, you can view and manage Vuex storage status and use its features: "Time travel" and snapshot state import/export.

Centralized data storage

It's quite convenient to store a status in components when your application is not very large. As soon as your app expands and bulks up, you definitely will need either synchronize duplicate data or move data around, which may be a complex task for component-oriented data storage. You'll need to use an approach with centralized data storage.

There are two libraries in Vue 3 for resolving such issues: Pinia and Vuex. Both libraries are implemented by Flux architecture approach.

The main idea is when an action is performed, the view doesn't change source data independently upon an action. Instead, it passes its desire for an update to the storage. Storage changes the data, and the view automatically reacts to these changes.

Example

Let's start with an example, when this approach is not needed. Imagine, if there is a component that uses only the internal data. For example, component for smiley display:

This component consists of the list of all smileys and galleries. This data isn't going to be used anywhere else, only here. This means that it must be stored inside the Vue component (moving it to a separate external storage is excessive).

Now, lets switch to another example: messenger

Messenger consists of several autonomous components:

1 chat list

2 chat panel

3 message list

Each of these sections contain user avatar icons (blue blocks). Consequently, there are several issues:

How to get data in the most deeply-nested component?
How to change avatar image in all blocks when uploading an avatar image in a single block?
How to synchronize new data, received by different components?
What component is the main one?

In such an abovelisted cases, the better course of action is to move data to an external storage and access it from any section of application.

Extra tip: "data source" shouldn't know, where this data is used or how to organize an event system to update it. The data will be automatically synchronized in all components where it's used.

Note: You will have to configure the corresponding environment to employ "Time travel" and import/export status snapshots (you can find more details in DevTools setup).

Pinia

Pinia is sate manager and library for Vue.js applications. It servers as a centralized storage for all app components and ensures data change/mutation predictability according to specific rules.

You can find more about Pinia 4 and the state management pattern at Pinia website.

Starting from version Vue 3, Vue developers have declared that Pinia is a recommended storage solution.

If you have previously used Vuex, then you can switch to Pinia in few steps.

Advantages and disadvantages compared to Vuex

Advantages:

Simplified layout for handling storage model: instead of actions and mutations, only one type – actions.
Simple modular implementation:
- When you application requires a single or several storages, there is no need to register each module beforehand: registration is automatic as applicable.
- Direct use of storage in another storage and operation directly via specific function call, without proxy methods:
  Vuex: this.$store.dispatch('users/addUser', {...})
  Pinia: userStore().addUser({...})

Disadvantages:

New notation compared to Vuex.
Global module registration. Necessitates control of module naming within the complete project and extra data manipulations for several app copies.
You need pre-activate Pinia before launching the app to be able to handle storage outside the Vue application.
Minimal integration with VueDevTools, unavailable import/export and Time travel features.

Connecting and launching

Connecting Pinia and creating a storage

Connect the extension ui.vue3.pinia inside your own extension or at php page to start the operation.

Import createPinia from ui.vue3.pinia in your extension for Pinia storage to work in your extension:

import {createPinia} from 'ui.vue3.pinia';
import {BitrixVue} from 'ui.vue3';

const store = createPinia();

const application = BitrixVue.createApp({
	components: {
		Component
	},
	template: '<Component/>'
});
application.use(store);
application.mount('#application');

Use the namespace BX.Vue3.Pinia within a page and scripts without transpiling and or feature access (for example, for createPinia, its BX.Vue3.Pinia.createPinia).

How to create a storage (module)

import {defineStore} from 'ui.vue3.pinia';

const exampleStore = defineStore('example', {
    ...
});

State export (state/getters)

You need to use data storage in component template for this component to declare such values in template via calculated properties.

You can avoid writing all structure elements manually: use the helper function mapState (this function can be imported from ui.vue3.pinia):

computed: {
    ...mapState(counterStore, ['counter', 'double']),
},

The function allows importing variables in a free format:

computed: {
    ...mapState(counterStore, {
        myOwnName: 'counter',
        // you also write function that gets access to storage
        triple: store => store.counter * 3,
    }),
},

Or you can query the variable in a usual format:

computed: {
    counterStore: () => counterStore().counter,
},

Action (actions) export

The same approach is applicable to methods: you need to export functions inside the component using the function mapActions (function can be imported from ui.vue3.pinia):

methods: {
    ...mapActions(counterStore, ['increaseCounter', 'decreaseCounter']),
	// as in the previous approach with mapState, you can rename parameters
    ...mapActions(useCounterStore, { decrease: 'decreaseCounter' }),
},

Example

Now lets unify these two actions and launch the application.

Let's overview the action: place element with identifier application at your html-page:

<div id="application"></div>

Execute the following code in JS extension for associating html, Vue and Vuex (it creates a storage, registers component to handle the extension and launches Vue application):

import { BitrixVue } from 'ui.vue3';
import { createPinia, defineStore, mapState, mapActions } from 'ui.vue3.pinia';

// initialize Pinia
const store = createPinia();

// create a Counter storage: please note, its a unique name for all of page!
const counterStore = defineStore('counter', {
	state: () => ({
		counter: 0,
		changes: 0
	}),
	getters: {
		double()
		{
			return this.counter * 2;
		},
	},
	actions: {
        increaseCounter()
        {
            this.counter++;
        },
        decreaseCounter()
        {
            this.counter--;
        }
    },
});

// Create a component to work with a state from Pinia

const Component = {
	computed: {
        counterMessage()
        {
            return 'Counter: ' + this.counter;
        },
        doubleCounterMessage()
        {
            return 'Double counter:' + this.double;
        },
        ...mapState(counterStore, ['counter', 'double']),
    },
	methods: {
        ...mapActions(counterStore, ['increaseCounter', 'decreaseCounter']),
    },
	// language=Vue
	template: `
        <div>{{counterMessage}}</div>
        <div>{{doubleCounterMessage}}</div>
        <div>
            <button @click="increaseCounter">+</button>
            <button @click="decreaseCounter">-</button>
        </div>
    `
};

// Create an application, connect Pinia and render into the "#application" tag
const Application = BitrixVue.createApp({
	components: {
		Component
	},
	template: `
        <Component/>
    `
});
Application.use(store);
Application.mount('#application');

Important! Upon declaring storages, you need to very carefully choose names inside function defineStore – first parameter must be unique. This can cause issues, when you use the same storage for different Vue applications (for example, when two different widgets that must have identical storage structure, but with different data).

Handling multiple storages (modules)

Pinia was designed to work with several storages in a single application without extra operations.

The example below overviews a modular approach: create two storages and handle them in two different applications simultaneously.

For example, html code has elements with identifiers: application1 and application2. Accordingly, we can verify that data simultaneously will be updated in two applications. First application will show results and the second will change the data.

Important! Pay extra attention to naming in the function defineStore when declaring storages - first parameter must be unique. This can create issue when you are using the same storage for different Vue applications (for example, for two various widgets that must have identical storage structure but contain different data).

<div id="application1"></div>
<div id="application2"></div>

In JS extension:

import { BitrixVue } from 'ui.vue3';
import { createPinia, defineStore, mapState, mapActions } from 'ui.vue3.pinia';

const store = createPinia();

const counterStore = defineStore('counter', {
	state: () => ({
		counter: 0
	}),
	getters: {
        double()
        {
            return this.counter * 2;
        },
    },
	actions: {
        increaseCounter()
        {
            this.counter++;
        },
        decreaseCounter()
        {
            this.counter--;
        }
    },
});

const statusStore = defineStore('status', {
	state: () => ({
		lastAction: 'None'
	}),
	actions: {
        setAction(action)
        {
            this.lastAction = action.toString();
        },
    },
});

const Buttons = {
	methods: {
		increase() {
			this.increaseCounter();
			this.setAction('Plus');
		},
		decrease() {
			this.decreaseCounter();
			this.setAction('Minus');
		},
		...mapActions(counterStore, ['increaseCounter', 'decreaseCounter']),
		...mapActions(statusStore, ['setAction']),
	},
	// language=Vue
	template: `
        <button @click="increase">+</button>
        <button @click="decrease">-</button>
    `
};
BitrixVue.createApp({
	components: {
		Buttons
	},
	template: `
        <Buttons/>
    `
}).use(store).mount('#application1');

const Counter = {
	computed: {
        ...mapState(counterStore, ['counter']),
        ...mapState(statusStore, ['lastAction']),
    },
	template: `
        <div>Click counter — {{ counter }}</div>
        <div>Last action — {{ lastAction }}</div>
    `
};

BitrixVue.createApp({
	components: {
		Counter
	},
	template: `<Counter/>`
}).use(store).mount('#application2');

Example of application with Pinia storage

We have prepared an example of application with Pinia storage shown below:

application loader;
two storages with mutual interaction;
root component.

The following steps are performed for launching a demo app:

Download example pinia (utf8);
Unpack the archive at the address /<installation_path>/local/js/local/;

Create public page and connect the extension:

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
?>

<?
\Bitrix\Main\UI\Extension::load("local.pinia");
?>

<div id="application">Application launches after 5 seconds.</div>
<br>
<div>
	<div>Update counter from HTML:</div>
	<button onclick="counterStore().increaseCounter()">+1</button>
	<button onclick="counterStore().decreaseCounter()">-1</button>
</div>
<script type="text/javascript">
	const application = new BX.PiniaDemo('#application');

	application.initStorageBeforeStartApplication();
	const counterStore = application.getCounterStore();

	setTimeout(() => {
		BX.Dom.clean();
		application.start();
	}, 5000)
</script>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

Application is launched after 5 seconds (to demonstrate storage operation before initializing Vue application). To use the storage, activate Pinia storage:

application.initStorageBeforeStartApplication()
{
   setActivePinia(this.#store);
}

When you want to edit the component and add your own logic, don't forget to launch the transpiler:

Open the terminal;
Go to local extensions folder cd /<installation_path>/local/js/;
Launch the transpiler in the change track mode bitrix build -w. You'll see the following text upon launch:
```
 ✔ 13:33:38 Build extension local.pinia  js: 5 KB, css: 64 B
```
Refresh the page: now all updates are displayed;
Upon new changes, just repeat the item 4.

Vuex

Vuex is a state manager and library for Vue.js applications. Serves as a central data storage for all app components and ensures predictability of data changes according to specific rules. Additionally, Vuex is integrated with VueDevTools browser extension. This allows using such features, as Time travel or data state export/import.

You can find more details about Vuex 4 and management pattern for state at Vuex website.

Starting from Vue 3 version, Vue developers have declared that Vuex is no longer a default recommended storage (now recommended storage: Pinia). Nevertheless, Vuex support will continue.

Connecting and launch

To start working, first connect the extension ui.vue3.vuex in your extension or at the php-enabled page.

Import createStore from ui.vue3.vuex in your extension, create a storage and connect it via .use():

import {createStore} from 'ui.vue3.vuex';
import {BitrixVue} from 'ui.vue3';

const store = createStore({
	...
});

const application = BitrixVue.createApp({
    components: {
		Component
    },
	template: '<Component/>'
});
application.use(store);
application.mount('#application');

Use the namespace BX.Vue3.Vuex for function access and handling the page and scripts without transpiling (for example, for createStore its BX.Vue3.Vuex.createStore).

Example

Let's overview example of interaction. Place an element with identifier application in your html page:

<div id="application"></div>

Execute the following code in JS extension for associating html, Vue and Vuex (it creates a storage, registers component to handle the extension and launches Vue application):

import {createStore} from 'ui.vue3.vuex';
import {BitrixVue} from 'ui.vue3';

const counterStore = {
	state()
	{
		return {
			counter: 0
		}
	},
	actions: {
        increaseCounter: (store) => {
            store.commit('increaseCounter', {count: 1});
        },
        decreaseCounter: (store) => {
            store.commit('increaseCounter', {count: -1});
        }
    },
	mutations: {
        increaseCounter: (state, payload = {}) => {
            let {count = 1} = payload;

            state.counter += count;
        }
    }
};

const store = createStore(counterStore);

const Component = {
	data()
	{
		return {
			clicks: 0
		}
	},
	computed: {
		counter()
		{
			return `Quantity: ${this.$store.state.counter}`;
		}
	},
	methods: {
		increase()
		{
			this.clicks += 1;

			this.$store.dispatch('increaseCounter').then(() => {
				console.log('+');
			});
		},
		decrease()
		{
			this.clicks += 1;

			this.$store.dispatch('decreaseCounter').then(() => {
				console.log('-');
			});
		}
	},
	// language=Vue
	template: `
        {{counter}}
        <button @click="increase">+</button>
        <button @click="decrease">-</button>
        (нажатий: {{clicks}})
    `
};

const Application = BitrixVue.createApp({
	components: {
		Component
	},
	template: `
        <Component/>
    `
})
Application.use(store);
Application.mount('#application');

Handling multiple storages (modules)

When you need to work with several storages within a single application, use the modular system. This mode changes syntax for storage declaration and call actions.

The example below uses the storage with two modules that work within two different Vue applications.

Place elements with identifiers application1 and application2 in the html code: this way we can check for data simultaneously updated in two applications.

First application will show results and second app will change the data.

<div id="application1"></div>
<div id="application2"></div>

In JS extension:

import {createStore, mapState} from 'ui.vue3.vuex';
import {BitrixVue} from 'ui.vue3';

const counterStore = {
	namespaced: true,
	state() {
		return {
			counter: 0
		}
	},
	actions: {
		increaseCounter: (store) => {
			store.commit('increaseCounter', {count: 1});
		},
		decreaseCounter: (store) => {
			store.commit('increaseCounter', {count: -1});
		}
	},
	mutations: {
		increaseCounter: (state, payload = {}) => {
			let {count = 1} = payload;
			state.counter += count;
		}
	}
};

const statusStore = {
	namespaced: true,
	state() {
		return {
			lastAction: 'None'
		}
	},
	actions: {
		setAction(store, payload) {
			const action = payload.toString();
			store.commit('setAction', action);
		},
	},
	mutations: {
		setAction(state, action) {
			state.lastAction = action;
		}
	}
};

const store = new createStore({
	modules: {
		counterStore,
		statusStore,
	}
});

const Buttons = {
	methods: {
		increase() {
			this.$store.dispatch('counterStore/increaseCounter').then(() => {
				this.$store.dispatch('statusStore/setAction', 'Plus');
			});
		},
		decrease() {
			this.$store.dispatch('counterStore/decreaseCounter').then(() => {
				this.$store.dispatch('statusStore/setAction', 'Minus');
			});
		}
	},
	// language=Vue
	template: `
        <button @click="increase">+</button>
        <button @click="decrease">-</button>
    `
};

BitrixVue.createApp({
	components: {
		Buttons
	},
	template: `
        <Buttons/>
    `
}).use(store).mount('#application1');

const Counter = {
	computed: {
		counter() {
			return this.counterStore.counter+' шт.';
		},
		...mapState({
			counterStore: state => state.counterStore,
			statusStore: state => state.statusStore
		})
	},
	template: `
        <div>Click counter — {{ counter }}</div>
        <div>Last action — {{ statusStore.lastAction }}</div>
    `
};

BitrixVue.createApp({
	components: {
		Counter
	},
	template: `<Counter/>`
}).use(store).mount('#application2');

There are several differences when using modular system:

Special parameter must be added to parameters when declaring storage:
```
namespaced: true, 
```
Upon initializing the storage, you need to list all nested storages in the object modules:
```
const store = new createStore({
	modules: {
		counterStore,
		statusStore,
	}
});
```

Method and action calls are also a little bit different:

When executing actions, instead of standard call:

store.dispatch('setAction', 'Plus');

indicate action jointly with namespace:

store.dispatch('statusStore/setAction', 'Plus');

Replace standard call when editing data (mutation):
```
store.commit('setAction', 'Plus');
```
with mutation jointly with namespace:
```
store.commit('statusStore/setAction', 'Plus');
```

To use storage data in component template, the component must declare use of these values in template via calculated properties.

Also, use helper function mapState to avoid manually writing all structure elements:

computed: {
    ...mapState({
        counterStore: state => state.counterStore,
        statusStore: state => state.statusStore
    })
},

Example of application with Vuex storage

We have prepared an example of application with Vuex storage shown below:

application loader;
two storages with mutual interaction;
root component.

The following steps are performed for launching a demo app:

Download example for vuex (utf8);
Unpack the archive at the address /<installation_path>/local/js/local/;

Create public page and connect the extension:

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
?>

<?
\Bitrix\Main\UI\Extension::load("local.vuex");
?>
<div id="application">Application launches after 5 seconds.</div>
<br>
<div>
	<div>Update counter from HTML:</div>
	<button onclick="store.dispatch('counterStore/increaseCounter')">+1</button>
	<button onclick="store.dispatch('counterStore/decreaseCounter')">-1</button>
</div>
<script type="text/javascript">
	const application = new BX.VuexDemo('#application');
	const store = application.getStore();

	setTimeout(() => {
		BX.Dom.clean();
		application.start();
	}, 5000)
</script>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

Application is launched after 5 seconds (to demonstrate storage operation before initializing Vue application).

When you want to edit the component and add your own logic, don't forget to launch the transpiler:

Open the terminal;
Go to local extensions folder cd /<installation_path>/local/js/;
Launch the transpiler in the change track mode bitrix build -w. You'll see the following text upon launch:
```
 ✔ 12:45:55 Build extension local.vuex  js: 6 KB, css: 64 B
```
Refresh the page: now all updates are displayed;
Upon new changes, just repeat the item 4.

Update from Vuex 3 to Vuex 4

Differences between Vuex versions are few, let's overview them in this article. You can find details on transitioning from earlier version to a newer at the official website.

List of updates:

Approach to storage creation has changed: now uses createStore({...}) instead new Store({...}).
Storage attribution changed: now uses the method .use(store) instead of variable store in Vue parameters.

Storage connection

Was:

import {Vue} from 'vue';
import {Vuex} from 'vuex';

const store = new Vuex.Store({
    ...
});

Vue.create({
	el: '#application',
    store: store,
	template: '<Component/>'
});

import {Vue} from 'ui.vue';
import {Vuex} from 'ui.vue.vuex';

const store = Vuex.createStore({
	...
});

Vue.create({
	el: '#application',
    store: store,
	template: '<Component/>'
});

Now:

import {BitrixVue} from 'ui.vue3';
import {createStore} from 'ui.vue3.vuex';

const store = createStore({
	...
});

const application = BitrixVue.createApp({
	template: '<Component/>'
})
application.use(store);
application.mount('#application');

Additional information

This chapter provides additional information related regarding Vue operation:

Access to original Vue 3 methods – access to original Vue 3 methods using simple import; connecting Bitrix Framework integration plugin ($Bitrix); using the namespace BX.Vue3 for working within inline scripts at the standard page and in scripts without transpiling;
Moving portion of template outside Vue application (Teleport) – example of [dw]Teleport[/dw][di] Teleport is an integrated component allowing to move portion of component template to an arbitrary DOM node outside Vue application. [/di];
Routing for third-party sites (VueRouter) – stipulates how to connect and launch routing library [dw]VueRouter[/dw][di] VueRouter – official routing library for Vue.js. Its deeply integrated with the core Vue.js, which allows easily create SPA applications. [/di].

Access to original Vue 3 methods

If you need to get access to original Vue 3 methods (for example, to createApp), you can do that using standard import:

import {createApp} from "ui.vue3";

createApp({
	data()
	{
		return {
			counter: 0
		}
	},
	mounted()
	{
		setInterval(() => {
			this.counter++
		}, 1000)
	},
	// language=Vue
	template: `
		Counter: {{ counter }}
	`
}).mount('#application');

When you need to connect Bitrix Framework integration plugin ($Bitrix): it can be done using .use(BitrixVue):

import {createApp, BitrixVue} from "ui.vue3";

const application = createApp({
	// language=Vue
	template: `
		Current UserID: {{ $Bitrix.Loc.getMessage('USER_ID') }}
	`
})
application.use(BitrixVue);
application.mount('#application');

Use the namespace BX.Vue3 for working within inline scripts at the standard page and in scripts without transpiling:

const application = BX.Vue3.createApp({
	// language=Vue
	template: `
		Current UserID: {{ $Bitrix.Loc.getMessage('USER_ID') }}
	`
})
application.use(BX.Vue3.BitrixVue);
application.mount('#application');

Moving portion of template outside Vue application (Teleport)

Teleport is an integrated component allowing to move portion of component template to an arbitrary DOM node outside Vue application. The most widespread example is a created popup-dialog or model window.

You can find additional details in the Teleport documentation.

Example

Insert the following html code at the page:

<div id="application"></div>
<div style="border: 1px solid red; padding: 5px 10px; margin-top: 20px">
	Outside Vue application
	<div id="outside-content"></div>
</div>

The application block will contain your Vue application, and the block outside-content - location for future teleport landing.

Add the following code in your JS extension:

import {BitrixVue} from 'ui.vue3';

BitrixVue.createApp({
    data: () => ({
        disabled: false,
    }),
    template: `
        <div style="border: 1px solid green; min-height: 5px; padding: 5px 10px">
            <div>Inside the Vue application</div>
            <button @click="disabled = !disabled">Teleport</button> Teleport enabled: {{disabled? 'No': 'Yes'}}
            <div>
                Content below this paragraph is visualized in an external (red) container 
                using the function <b>Vue3 Teleport</b> if teleport is enabled.<br>
                Otherwise is shown here as needed.
                
                <teleport to="#outside-content" :disabled="disabled" >
                    <p style="border: 1px solid #000; padding: 2px 10px">This is content from Vue.</p>
                </teleport>
            </div>
        </div>
    `
}).mount('#application');

Routing for external sites (VueRouter)

What is VueRouter

VueRouter – official routing library for Vue.js. It's closely integrated with Vue.js core, which allows to easily create SPA applications.

VueRouter includes the following features:

Embedded routes/views
Router modular configuration
Access to the route parameters, query, wildcards
Transition animations for Vue.js based views
Convenient navigation management
Automatic inserting of active CSS class for links
HTML5 history work modes
Configurable page scrolling behavior

You can read more about the library at the official website.

Connecting and launching

To start the work, connect the extension ui.vue3.router in your extension or php-enabled page.

Import createRouter and other necessary functions to your extension. For example, import createWebHashHistory from ui.vue3.router:

import {BitrixVue} from 'ui.vue3';
import {createRouter, createWebHashHistory} from 'ui.vue3.router';

const router = createRouter({
    ...
});

const application = BitrixVue.createApp({
    components: {
		Component
    },
    template: `
        <Component/>
    `
});
application.use(router);
application.mount('#application');

Use the namespace BX.Vue3.VueRouter for function access and handling the page and scripts without transpiling (for example, for createRouter its BX.Vue3.VueRouter.createRouter).

Example

import {BitrixVue} from 'ui.vue3';
import {createRouter, createWebHashHistory} from 'ui.vue3.router';

// 1. Define components for routes.
// They can be imported from other files
const Foo = { template: '<div>Page1</div>' };
const Bar = { template: '<div>Page2</div>' };

// 2. Define several routes
const routes = [
  { path: '/foo', component: Foo },
  { path: '/bar', component: Bar }
];

// 3. Create a router instance and pass routes to the `routes` options
const router = createRouter({
	history: createWebHashHistory(),
	routes,
});

// 4. Create and mount the app's root instance.
const application = BitrixVue.createApp({
    template: `
        <div>
            <h3>VueRouter</h3>
            <div>
                <router-link to="/foo">Go to Page1</router-link> -
                <router-link to="/bar">Go to Page2</router-link>
            </div>
            <router-view></router-view>
        </div>
    `
});
application.use(router);
application.mount('#application');

Integration with Dexie (IndexedDB)

Inetgration with Dexie

The UI module contains the extension ui.dexie, allowing to interact with local IndexedDB database.

Starting from version ui 22.500.0 you can use the Dexie integration with Vue 3.

You can learn more about this library at the official website.

Establishing a connection

Connect the extensions ui.dexie and ui.vue3 in your extension or at a PHP page.

Import into the extension the liveQuery from ui.dexie and useObservable from ui.vue3 respectively.

To work within a page and in scripts without compiling, use the namespaces BX.Dexie3 and BX.Vue3 for access to functions (for example, for liveQuery its BX.Dexie3.liveQuery).

Example

In the example below, the Vue application shows the content of local database.

The variable items will actively store all items of the items table, with names starting with an English letter "A".

import {BitrixVue, useObservable} from 'ui.vue3';
import {Dexie, liveQuery} from 'ui.dexie';

const db = new Dexie("vuedbsample");
db.version(1).stores({
	items: "++id, name"
});

const DBItems = {
	data() {
		return {
			db,
			items: useObservable(
				liveQuery(() => db.items.where("name").startsWithAnyOf("A", "a").sortBy('id'))
			),
		}
	},
	methods: {
		addUser()
		{
			const name = prompt('Specify the element starting with the letter "A":')
			this.db.items.add({ name });
		},
		clear()
		{
			this.db.items.clear();
		}
	},
	template: `
		<h2>Dexie integration (IndexedDB)</h2>

		<!-- Mutation examples -->
		<button @click="addUser">Add item</button>
		<button @click="clear">Clear items</button>
		
		<!-- Render the result of the query -->
		<ul>
		  <li v-for="item in items" :key="item.id">
			{{ item.id }}, {{ item.name }}
		  </li>
		</ul>
	`
};

const application = BitrixVue.createApp({
	components: {
		DBItems
	},
	template: `
		<DBItems/>
	`
});
application.mount('#application');

External libraries

Currently, you cannot connect modules within Bitrix Framework using [ds]npm[/ds][di] npm — node package manager, included into Node.js.

Learn more...[/di] (folder node_modules), presently this feature is under development and will be available at a later date. Now, if you want to use external libraries, you need to collect them in the Bitrix format of [ds]JS Extension[/ds][di] Extensions is method for organizing JS and CSS code in Bitrix24 products.

Learn more...[/di].

This way, to integrate a third-party library, you need to find a suitable version of [ds]ESM[/ds][di] ESM (or ECMAScript modules) - module format, created as part of standard ECMAScript. It was standartized in the ECMAScript version ES6. ES Modules are designed to solve a very important JavaScript issue: missing method for code exchange between scenarios[/di], and then "wrap" into Bitrix JS Extension (extension) with clear export.

Let's examine vue-router (available in the supplied source code for delivery in the folder /bitrix/modules/ui/install/js/ui/vue3/router/).

The algorithm is as follows:

Find the version of ESM (ECMAScript Modules). For example, take a version of router here. Define it as basic extension script.
Delete all the redundant imports and add dependencies, if required.
Execute export.

Example vue-router.js is sourced from folder /bitrix/modules/ui/install/js/ui/vue3/router/src/:

/*!
  * vue-router v4.0.12
  * (c) 2021 Eduardo San Martin Morote
  * @license MIT
  *
  * @source: https://unpkg.com/vue-router@4.0.12/dist/vue-router.esm-browser.js
  */

/**
 * Modify list for integration with Bitrix Framework:
 * - remove import '@vue/devtools-api', add function setupDevtoolsPlugin
 */

import { getCurrentInstance, inject, onUnmounted, onDeactivated, onActivated, computed, unref, 
watchEffect, defineComponent, reactive, h, provide, ref, watch, shallowRef, nextTick } from 'ui.vue3';

function getDevtoolsGlobalHook() {
  return getTarget().__VUE_DEVTOOLS_GLOBAL_HOOK__;
}
function getTarget() {
  // @ts-ignore
  return typeof navigator !== 'undefined'
    ? window
    : typeof global !== 'undefined'
      ? global
      : {};
}

const HOOK_SETUP = 'devtools-plugin:setup';

function setupDevtoolsPlugin(pluginDescriptor, setupFn) {
  const hook = getDevtoolsGlobalHook();
  if (hook) {
    hook.emit(HOOK_SETUP, pluginDescriptor, setupFn);
  }
  else {
    const target = getTarget();
    const list = target.__VUE_DEVTOOLS_PLUGINS__ = target.__VUE_DEVTOOLS_PLUGINS__ || [];
    list.push({
      pluginDescriptor,
      setupFn
    });
  }
}

// origin-start

[... original library code is here ...]

export { NavigationFailureType, RouterLink, RouterView, START_LOCATION_NORMALIZED as START_LOCATION, 
createMemoryHistory, createRouter, createRouterMatcher, createWebHashHistory, createWebHistory, 
isNavigationFailure, matchedRouteKey, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, 
routeLocationKey, routerKey, routerViewLocationKey, stringifyQuery, useLink, useRoute, useRouter, 
viewDepthKey };
// origin-end

Note: There are two blocks at the file's start:

@source – link to source file (suitable version of ESM);
Modify list – list of updates, introduced to original file to work within BitrixFramework.

After the abovementioned actions, this extension will be used inside Bitrix Framework.

Transition from Vue 2 to BitrixVue 3

Note: This chapter describes migration from Vue 2 to BitrixVue 3. For additional details regarding Bitrix Framework and BitrixVue 3, please refer to the following documentation.

To migrate from Vue 2 to BitrixVue 3, you have to follow the recommendations, described in the article dedicated to migration from Vue 2 to Vue 3.

Key migration highlights are overviewed in this chapter. However, if your application fails to start and you still have questions related to reviewed changes, please read the official migration guide.

Creating new app (instance)

Transition from Vue 3 to BitrixVue 3

Such transition will be maximally simple, because you don't have to update original Vue framework code to implement the complete BitrixVue 3 functionality. And it also means that 100% compatibility is preserved with any code, written previously for Vue 3.

The only difference – is the method to create an application. Now creating function has changed: now it's BitrixVue.createApp instead of createApp.

Before:

import {createApp} from 'vue';

createApp({
	components: {
		Component
	},
	template: '<Component/>'
}).mount('#application');

Now:

import {BitrixVue} from 'ui.vue3';

const application = BitrixVue.createApp({
	components: {
		Component
	},
	template: '<Component/>'
});
application.mount('#application');

More details can be found in the chapter Creating Vue application.

You can find extra details on how to get access to original methods in corresponding lesson.

Transition from Vue 2 to BitrixVue 3

Creating new Vue application

Before:

import {Vue} from 'vue';

new Vue({
	components: {
		Component
	},
	template: '<Component/>'
}).$mount('#application');

import {Vue} from 'ui.vue';

Vue.create({
	el: '#application',
    components: {
		Component
    },
	template: '<Component/>'
})

Now:

import {BitrixVue} from 'ui.vue3';

const application = BitrixVue.createApp({
	components: {
		Component
	},
	template: '<Component/>'
});
application.mount('#application');

List of changes:

Creating function changed: now it's BitrixVue.createApp instead of new Vue, Vue.create.
Element binding changed: now it's mount() instead of el or method $mount().

FInd more details in the chapter Creating Vue application.

Global methods

Changes introduced to Vue application methods:

Vue.component() => application.component()
Vue.directive() => application.directive()
Vue.mixin() => application.mixin()
Vue.config() => application.config()
Vue.use() => application.use() (learn more in Vue documentation)
Vue.extend() => is no longer supported

Changes in Vue global methods:

Vue.nextTick => nextTick
Vue.observable => reactive
and etc.

Previously you can notice in examples, that now you are exporting a function you require instead of a Vue class during import.

Let's overview the example with nextTick:

Before:

import { Vue } from 'vue';

Vue.nextTick(() => {
  ...
});

Now:

import { nextTick } from 'ui.vue3';

nextTick(() => {
  ...
});

You can find more details in the migration guide.

Template directives

attribute use :key
It's no longer required to indicate a key for instructions v-if/v-else/v-else-if – Vue does it automatically.

You won't be able to indicate keys manually, but each key must have a unique name.

When using the tag <template> with iterator v-for, the key must be located on this tag instead of its children, as before.

Before:
```
<template v-for="item in list">
  <div :key="'heading-' + item.id">...</div>
  <span :key="'content-' + item.id">...</span>
</template>
```
Now:
```
<template v-for="item in list" :key="item.id">
	<div>...</div>
	<span>...</span>
</template>
```
You can read more about such this update in the migration guide.
using instruction v-if jointly with v-for
Now v-if has the priority when using v-if jointly with v-for at a single element.
using instruction v-model
If you have used the instruction v-model, you must read the article about the key changes in the migration guide.

Transitions

Transition classes
Transition class v-enter is renamed to v-enter-from and v-leave – to v-leave-from.

Before:
```
.v-enter {
    opacity: 0;
}
.v-leave {
    opacity: 1;
}
```
Now:
```
.v-enter-from {
    opacity: 0;
}
.v-leave-from {
    opacity: 1;
}
```
Learn more on this change in the migration guide.
Transitions in root element
Vue 3 handles transitions at the root element in a different format. You can find details in these articles:
- Transition at the root element
- Element group transition in the root element

Logic for joint watch parameter and array

Using the parameter watch to observe the array triggers the callback only when fully replacing the array. If for your callback is required to trigger upon an update as well - indicate the parameter deep:

watch: {
    listElements: {
        handler(currentValue, previousValue) 
        {
            console.log('array is changed');
        },
        deep: true,
    },
}

You can find more details in the migration guide.

Keystroke tracking

If you have previously employed tracking by key codes, you'll have to change this practice, because it's no longer supported.

Before:

<input v-on:keyup.13="submit" />
<input v-on:keyup.34="nextPage" />
<input v-on:keyup.81="quit" />

Now:

<input v-on:keyup.enter="submit" />
<input v-on:keyup.page-down="nextPage">
<input v-on:keypress.q="quit">

Note: In addition to this change, the construction v-on.native modifier was deleted.

Directive creating

Vue 3 have re-designed directive life cycle hooks: now they have become more similar to the component life cycle hooks. All these events are described in the documentation section: User directives.

List of changes:

Wasn't used => created
bind => beforeMount
inserted => mounted
Wasn't used => beforeUpdate
update => removed
componentUpdated => updated
Wasn't used => beforeUnmount
unbind => unmounted

You can find more details on reasons for renaming in the migration guide.

Global component

Vue 3 no longer has a global component in a classic sense.

Global registration has remained, but it registers component globally only within the application, but not for the site, as previously.

In such format, there are almost no specific advantages, with decreased visual clarity, compared to local components.

We recommend to consider the option of moving all your components to a local format.

Before:

import {Vue} from 'ui.vue';

Vue.component('component', {
	...
});

Now:

export const Component = {
	...
};

If you require global registration specifically, you can find more details on how to get it in the documentation.

Event-driven model

When you have used app-level events:
```
this.$root.$on(...)
this.$root.$off(...)
this.$root.$emit(...)
```
You need to rollback to BitrixVue 3 integrated EventEmitter:
```
this.$Bitrix.eventEmitter.subscribe(...)
this.$Bitrix.eventEmitter.unsubscribe(...)
this.$Bitrix.eventEmitter.emit(...)
```
You can find more details on integrated EventEmitter in this article: Event-driven model (App-level events).
If you have used global event bus (EventBus)
Such pattern was used previously in BitrixVue 2 within Bitrix Framework in earlier versions, for communications between different Vue applications at a single page.

Such approach isn't applicable in BitrixVue 3, that's why you need to replace old calls with new ones. For this purpose, use global EventEmitter from Core.js library within the extension main.core.events.

Before:
```
Vue.event.$on(...)
Vue.event.$off(...)
Vue.event.$emit(...)
```
Now:
```
EventEmitter.subscribe(...)
EventEmitter.unsubscribe(...)
EventEmitter.emit(...)
```
You can find more details about the basic EventEmitter in the article: Event-driven model (Site-level events).

Localizations

Using localization in template ({{localize.CODE}})

BitrixVue 3 new version have the option to use localization inside components and template without preliminary prepared calculated property localize.

Before:

template: `
    <div>{{localize.CODE}}</div>
`

Now:

template: `
    <div>{{$Bitrix.Loc.getMessage('CODE')}}</div>
`

You can find more details about localizations and the method $Bitrix.Loc.getMessage in the article: Class for handling localizations.

Using BitrixVue.getFilteredPhrases

Now this method is very rarely required. The case when it's required, is described in the article: Handling localizations.

If you still need it, some modifications are needed.

Before:

Vue.getFilteredPhrases('PREFIX_', this.$root.$bitrixMessages);
BitrixVue.getFilteredPhrases('PREFIX_1', this.$root.$bitrixMessages);
BitrixVue.getFilteredPhrases(['PREFIX_1_', 'PREFIX_2_'], this);

Now:

BitrixVue.getFilteredPhrases(this, 'PREFIX_1');
BitrixVue.getFilteredPhrases(this, ['PREFIX_1_', 'PREFIX_2_']);

List of changes:

Set of parameters changed.
Now you need to indicate just this when calling a method instead of global variable this.$root.$bitrixMessages. Current component context within computed of property localize is understood under this. Such format was used for external integrations (for example, widgets).

Setting external localizations (in $root component)

Previously, specifying external localizations (for external integrations) used the approach with indicating localizations in the global variable this.$root.$bitrixMessages:

import {Vue} from 'ui.vue';

class TaskManager
{
	...
	attachTemplate()
	{
		const context = this;
		this.vm = new Vue({
		    el: this.rootNode,
			beforeCreate() 
			{
				this.$bitrixApplication = context;
				
				this.$bitrixMessages.PREFIX_CODE_1 = 'Message 1'; 

                this.$bitrixMessages = {
                   'PREFIX_CODE_1': 'Message 1',
                   'PREFIX_CODE_2': 'Message 2',
                };
			},
			template: '<module-component/>'
		})
	}
	...
}

But now you have to use the class $Bitrix.Loc:

import {BitrixVue} from 'ui.vue3';

class TaskManager
{
	...
	attachTemplate()
	{
		const context = this;
		        
		this.#application = BitrixVue.createApp({
			beforeCreate() 
			{
				this.$bitrix.Application.set(context);
				
				this.$bitrix.Loc.setMessage('PREFIX_CODE_1', 'Message 1');

                this.$bitrix.Loc.setMessage({
                   'PREFIX_CODE_1': 'Message 1',
                   'PREFIX_CODE_2': 'Message 2',
                });
			},
            components: {
				Component,
			},
			template: '<Component/>'
		});
		this.#application.mount(this.#rootNode);
	}
	...
}

Find more details on the new approach in the article: Class for handling localizations.

Forwarding of execution context link to Vue application

Sometimes Vue applications require access to the launch context (managing script). Previously, such access was implemented via registration of global variable when initializating Vue application.

Before:

import {Vue} from 'ui.vue';

class TaskManager
{
	...
	attachTemplate()
	{
		const context = this;
		        
		this.vm = new Vue({
		    el: this.rootNode,
			beforeCreate() 
			{
				this.$bitrixApplication = context;
			},
			template: '<module-component/>'
		})
	}
	...
}

Now you need to use the class $Bitrix.Application:

import {BitrixVue} from 'ui.vue3';

class TaskManager
{
	...
	attachTemplate()
	{
		const context = this;

		this.#application = BitrixVue.createApp({
			beforeCreate() 
			{
				this.$bitrix.Application.set(context);
			},
            components: {
				Component,
            },
			template: '<Component/>'
		});
        this.#application.mount(this.#rootNode);
	}
	...
}

This method is responsible for accessing the context:

this.$Bitrix.Application.get();

You can find more details on methods operation in the article: Class app link (context) forwarding.

Data storage in application

If you have used global variables within your components (often when initializing Vue application), now you have a specialized class $Bitrix.Data.
Before:
```
this.$root.$variable = 'xyz';
console.log(this.$root.$variable);
```
Now:
```
this.$Bitrix.Data.set('variale', 'xyz');
this.$Bitrix.Data.get('variale');
```

If you have previously retrieved a value, and indicated the default value if its unavailable - now your call can be simplified.

Before:

let variable;
if (typeof this.$root.$variable !== 'undefined')
{
	variable = this.$root.$variable;
}
else
{
	variable = 'defaultValue';
}

Now:

this.$Bitrix.Data.get('variable', 'defaultValue');

You can find more details on the class $Bitrix.Data in the article: Class for handling global data.

REST and Pull clients

When your application have operated outside the current site (in widget format) and employed a special client - you need to update the format of registration and use.

Before:

import {Vue} from 'ui.vue';

class TaskManager
{
	...
	attachTemplate()
	{
		const context = this;
		const restClient = this.restClient;
		const pullClient = this.pullClient;
		        
		this.vm = new Vue({
		    el: this.rootNode,
			beforeCreate() 
			{
				this.$bitrixApplication = context;
				
				this.$bitrixRestClient = restClient;
				this.$bitrixPullClient = pullClient;
			},
			template: '<module-component/>'
		})
	}
	...
}

Now:

import {BitrixVue} from 'ui.vue3';

class TaskManager
{
	...
	
	attachTemplate()
	{
		const context = this;
		const restClient = this.#restClient;
		const pullClient = this.#pullClient;
		        
		this.#application = BitrixVue.createApp({
			beforeCreate() 
			{
				this.$bitrix.Application.set(context);
				
				this.$bitrix.RestClient.set(restClient);
				this.$bitrix.PullClient.set(pullClient);
			},
            components: {
				Component,
			},
			template: '<Component/>'
		});
		this.#application.mount(this.#rootNode);
	}
	...
}

For access to client inside components:

Before:

this.$root.$bitrixRestClient
this.$root.$bitrixPullClient

Now:

this.$Bitrix.RestClient.get()
this.$Bitrix.PullClient.get()

Note: Getters will operate even without installing special clients. In this case, uses the default clients specifically for current site.

Find more details in articles: Class for handling REST client and Class for handling Pull client.

Changes in Vuex 4 operation

Creating new storage

Before:

import {Vuex} from 'ui.vue.vuex';

const store = new Vuex.Store({
	...
});

import {Vuex} from 'ui.vue.vuex';

const store = Vuex.createStore({
	...
});

Now:

import {createStore} from 'ui.vue3.vuex';

const store = createStore({
	...
});

Storage creation format has been updated. We are using Vuex 4-similar approach Vuex.createStore instead of classic new Vuex.Store for more smooth transition to future versions.

Find more details in the article: Working with Vuex 4.

Interface of the Control Panel Toolbar as Seen by a Developer

Panel Connection

After authorization on a website, the Control Panel becomes available at the top of the page for a user with the appropriate rights. This panel can be used toо:

Manage parameters of the current section;
Go to editing of the current page and connectable areas;
Add and change the menu of the current section;
Set up component parameters;
Quickly go to the administrative section of the website;
And much more.

Note: A detailed description of the panel interface is provided in the training course System administration.

The administrative panel connection code shall be introduced in the service area of the website design template immediately after the <body> tag before the beginning of the first table.

<?
$APPLICATION->ShowPanel();
?>

Note: The panel will not be displayed for a user with insufficient rights.

The panel can also be displayed for a specific group or separate users. To do so, use the option Always show toolbar for users in the settings of the Kernel module, tab Settings.

In this case, the panel will be displayed, but a set of its buttons will depend on the user’s rights.

Adding Buttons to the Control Panel

When creating own projects, it may become necessary to create new buttons on the Control Panel. Buttons can be added to the Control Panel as follows:

<?$APPLICATION->AddPanelButton(
	Array(
		"ID" => "Button ID", //Defines the uniqueness of the button
		"TEXT" => "Name of the button",
		"TYPE" => "BIG", //BIG – a big button, otherwise it will be a small button
		"MAIN_SORT" => 100, //sorting index for a group of buttons
		"SORT" => 10, //sorting inside the group
		"HREF" => "Goto URL", //or javascript:MyJSFunction())
		"ICON" => "icon-class", //name of CSS class with a button icon
		"SRC" => "button icon path",
		"ALT" => "Prompt text", //old variant
		"HINT" => array( //tool type of the button
			"TITLE" => "Tool type header",
			"TEXT" => "Tool type tex" //HTML is allowed
		),
		"HINT_MENU" => array( //Tool type for a context menu button
			"TITLE" => "Tool type header",
			"TEXT" => "Tool type text" //HTML is allowed
		),
		"MENU" => Array(
			Array( //array of context menu options
				"TEXT" => "Name of the option",
				"TITLE" => "Option prompt",
				"SORT" => 10, //Option sorting index
				"ICON" => "", //Option icon
				"ACTION" => "Javascript code",
				"SEPARATOR" => true, //determines a separating point
				"DEFAULT" => true, //default option?
				"MENU" => Array() //submenu array
				)
			)
		),
	$bReplace = false //replace the existing button with new data?
);	
?>

There are several options to add a button from:

In a component
On a page
In a website template
In the even OnBeforeProlog

Adding Context Menu

Use the following code in order to add context menu options to any panel button:

$APPLICATION -> AddPanelButtonMenu($btnId, $arMenuItem)

where:

$btnId is the button identifier;
$arMenuItem is the array of options.

Note: пthe options can be resorted according to a sorting index using the following structure:

"RESORT_MENU" => true

Component Toolbar

Use the following code in order to display the component toolbar:

$this->AddIncludeAreaIcons(
	Array( //array of buttons of the toolbar
		Array(
			"ID" => "Button identifier",
			"TEXT" => "Name of the button of the toolbar",
			"URL" => "Goto link" //or javascript^MyJSFunction ()
			"ICON" => "menu-delete", //CSS class with an icon
			"MENU" => Array(
				//array of options of a context men
			),
			"HINT" => array( //button tool type
				"TITLE" => "Tool type header",
				"TEXT" => "Tool type text" //HTML is allowed
			),
			"HINT_MENU" => array ( //Tool type of the context menu button
				"TITLE" => "Tool type header",
				"TEXT" => "Tool type text" //HTML is allowed
			),
			"IN_PARAMS_MENU" => true //show in the context menu
			"IN_MENU" => true //show in the component submenu
		)
	)
);

//Is the editing mode on?
if ($APPLICATION->GetShowIncludeAreas())
{
	$this->AddIncludeAreaIcons(Array(
		//Arrays of the buttons of the toolbar
	));
}

Context Menu of the List Items

Set the HTML attribute id for a block tag:

<div id="<?=$this->GetEditAreaID("area_identifier")?>">
	<!-- block contents -->
</div>

Determine context menu buttons in compote_epilog.php using the method:
```
    $APPLICATION->SetEditArea($areaId, $arIcons);
```
where:
- $areaId is an area identifier with the context menu;
- $arIcons is an array of context menu icons.

The method adds a button that opens the indicated URL in a pop-up window:

$this->AddEditAction(
	"Area_identifie",
	"URL of the page to be opened in a pop-up window",
	"Name of the button in the toolbar",
	Array(
		"WINDOW" => array("wight"=>780, "height"=>500),
		"ICON" => "bx-content-toolbar-edit-icon",
		"SRC" => "/bitrix/images/myicon.gif"
	)
);

The method adds the button that deletes an element:

$this->AddDeleteAction(
	"Area_identifier",
	"URL of the page deleting the specified element",
	"Name of the button",
	Array(
		"CONFIRM" => "Do you really want to delete this element?",

	)
);

Administrative Pages in the Public Section

The method generates JavaScript which opens a URL in a pop-up window:

$APPLICATION->GetPopupLink(Array(
	"URL"=> "URL of the page to be opened in a pop-up window",
	"PARAMS" => Array(
		"wight" => 780,
		"height" => 570,
		"resizable" => true,
		"min_wight" => 780,
		"min_height" => 400
	)
);

The method generates element control and infoblock section buttons:

CIBlock::GetPanelButtons(
	$IBLOCK_ID = 0, //infoblock ID
	$ELEMENT_ID = 0, //infoblock element ID
	$SECTION_ID = 0, //infoblock section ID
	$arOptions = Array(
		"SECTION_BUTTONS" => true, //generate buttons for control of sections
		"SESSID" => false, //add a link into the authorized token
		"RETURN_URL" => "",
		"LABELS" => Array() //button labels; by default they are taken from infoblock settings
	)
);

New Buffering Methods

Enhanced template buffering methods permit not to use EndViewTarget() any longer because the end of a template automatically terminates buffering.

Now, there is a standard caching support in components.

template.php:

<?$this->SetViewTarget("sidebar");?>

	<div class="element-filter">
		<!--filter display -->
	</div>

<?$this->EndViewTarget();?>

<div class="element-list">
	<!--list display -->
</div>

header.php:

<div id="sidebar">
	<?$APPLICATION->ShowViewContent("sidebar")?>
</div>

Methods available in a template (through &this)

CBitrixComponentTemplate::SetViewTarget($view, $pos)
CBitrixComponentTemplate::EndViewTarget()

$APPLICATION global object methods

Cmain::AddViewContent($view, $content, $pos)
Cmain::ShowViewContent($view)

where:

$view is the buffered area identifier;

$content is the buffered content;

$pos is the sorting of the displayed contents.

Note: Several buffers may correspond to one $view identifiers. The $pos sorting determines the sequence of the content display.

Some Theory

In this chapter we will give you recommendations on writing a PHP source code. Also, we will set standards for code writing in Bitrix Framework.

Notes on $arParams and $arResult

$arParams

$arParams is a variable redefined for a component which consists of the input parameters of a component. In this array, the names of parameters are the keys, and parameter values are the array values.

Before connecting a component to all parameter values, the function htmlspecialcharsEx is applied. The source values of the parameters are stored in the same array with the same keys but with the prefix ~. For example, $arParams["NAME"] is an input parameter to which the function htmlspecialcharsEx, and $arParams["~NAME"] is a source input parameter.

The variable $arParams is a reference for a component class member. That is why all the changes in this variable are also reflected on such a class member. In the beginning of the component code input parameters must be checked, non-set parameters must be initialized, and adjustment to a required type must be performed (e.g., IntVal()). All these changes in the input parameters will also be available in the template. I.e. parameters in the template will be already checked and as safe as possible. Duplicating parameter preparation in the component template is not required.

$arResult

$arResult is a preset variable for a component to which the component work result is collected for subsequent submission to the template. Before connecting a component file, this variable is initialized by the empty array array().

The $arResult variable is a reference for a component class member. That is why all changes in this variable are also reflected on such a class member. It means that there is no need to submit this variable to the template, since internal mechanisms of the component class will do it.

References in PHP

References in PHP are necessary so that the same data could be accessed using different names. If the variables $arParams and $arResult are somehow changed in the component code, they will be updated and available in the template, too.

At the same time, the following aspects shall be taken into account:

If the following code is written in the component:
$arParams = & $arSomeArray;
the variable $arParams will be detached from the component class member and attached to the array $arSomeArray.In this case, further changes in $arParams will not get to the component template.
If the following, the code is written in the component:
unset($arParams);
it will also break the connection between $arParams and the relevant component class member.

HTTP POST Queries

If the option ErrorDocument (ErrorDocument 404 /404.php) is used on the website to process non-existent pages, then upon sending a HTTP POST query to a non-existent page the data of the POST query will be lost. That is why such queries must be sent to the scripts that exist physically.

One of the ways to organize SEF in components 2.0 consists in using the ErrorDocument option. There is a standard solution for components 2.0 which permits not to worry about the option used for SEF support, be it ErrorDocument or mod_rewrite.

When writing forms in component templates which send data using the POST method the constant POST_FORM_ACTION_URI must be indicated as action:

<form method="post" action="<?=POST_FORM_ACTION_URI?>">
	* * *
</form>

In this case, when working with the ErrorDocument option, a POST query will be sent to a script that exists physically, and in other cases – to a current address. It will make no difference for a component as to whether it was called by a POST or a GET query. All the required variables will be set up accordingly.

Code Writing Rules

Properly written source code is one of the major factors from which the quality of software stems. In its turn, the crucial factors of the quality source code are readability and comprehensibility. To make your source code readable to other developers, a set or formal rules is required.

The source code formatting rules must be adhered to throughout the whole project files. If there are multiple projects that may possibly have interconnections, the rules must apply to these projects with no exception.

Source Code Formatting
Naming Conventions

General Provisions
Variable Names
Method Names
Variable Prefixes
Class Names
Class Member Access Control
Constants

Comments
Idioms
- General Provisions
- Examples Of Idioms
SQL Queries

1. Source Code Formatting

1.1. Text Structure Rules

1.1.1. Line Length

Avoid typing lines whose length exceeds 120 characters. If a line spans beyond that limit, use the line wrapping rules described below.

1.1.2. Line Wrapping Rules

If a line length exceeds 120 characters, the following wrapping rules apply:

wrap lines after the comma or before the operator;
the wrapped line must be indented by one tab;
use UNIX line ends.

Example 1: The code

$arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD, $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

needs to be wrapped as follows:

$arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD,
     $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

Example 2: The code

if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&$TYPE
=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))

needs to be wrapped as follows:

if (COption::GetOptionString("main", "new_user_registration", "N") == "Y"
     && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
     && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true)

1.1.3. Spaces And Tabs

Use tabs for indentation. Using spaces for indentation is forbidden for the following reasons:

with tabs, any developer can configure his or her text editor to show the desired tab length;
using tabs makes file size smaller;
if both tabs and spaces are used for indentation, the originally intended text formatting is likely to be damaged if a different tab size is used in a text editor.

1.1.4. Scopes And Code Blocks

The code block contents must be indented by one tab. The code block contents must not be on the same line as the controlling statement.

function func()
{
     if (condition)
     {
          while (condition2)
          {

          }
      }
}

1.1.5.Rules for placing braces

Opening braces must be place under a corresponding operator and on the same indent with it. Closing braces must be placed under the corresponding opening braces.

Example:

if ($condition)
{
   ...
}

1.1.6. Using the ternary operator "?:"

Example:

(condition ? funct1() : func2());

1.2. Expressions And Statements

1.2.1. Expressions

One line must contain only one expression.

Example. This expression is formatted incorrectly:

$a = $b; $b = $c; $c = $a;

Rewrite it like this:

$a = $b;
$b = $c;
$c = $a;

1.2.2. The statements if, else, while etc.

Use one of the following two formatting rules depending on the statement length.

if a controlled code block contains only one statement, use the following form:

if (expression)
     statement 1;
else
     statement 2;

if at least one controlled code block contains multiple statements, use braces:

if (expression)
{
     statement 1;
}
else
{
      statement 2; 
      statement 3;
}

The rule “Scopes And Code Blocks” must be obeyed when writing multiple statements: they must be indented by one tab off the controlling statement. The braces must exist on new lines on the same level as the controlling statement.

Example. This code:

if ($a == 0) $a = 10;
else{
$a = 5;
$b = 10;}

must be reformatted like this:

if ($a == 0)
{
  $a = 10;
}
else
{
  $a = 5;
  $b = 10;
}

1.2.3. Compound Expressions

Compound expressions must be split in multiple lines according to rules described in “The statements if, else, while etc.”.

For example, consider the following code:

 if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&
     $TYPE=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))

Make it readable by sticking to the formatting rules:

if (COption::GetOptionString("main", "new_user_registration", "N") == "Y"
     && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
     && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true))
{
}

It is recommended that you split an extremely complex expression into several simple lines of code.

For example, the code

if((!(defined("STATISTIC_ONLY") && STATISTIC_ONLY && substr($APPLICATION->GetCurPage(), 0,
     strlen(BX_ROOT."/admin/"))!=BX_ROOT."/admin/")) && COption::GetOptionString("main", "include_charset", "Y")=="Y"
     && strlen(LANG_CHARSET)>0)

is definitely more readable when written like this:

$publicStatisticOnly = False;
if (defined("STATISTIC_ONLY")
  && STATISTIC_ONLY
  && substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) != BX_ROOT."/admin/")
{
     $publicStatisticOnly = True;
}
if (!$publicStatisticOnly && strlen(LANG_CHARSET) > 0
     && COption::GetOptionString("main", "include_charset", "Y") == "Y")
{
}

or like this:

if (!defined("STATISTIC_ONLY") || ! STATISTIC_ONLY
  || substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) == BX_ROOT."/admin/")
{
  if (strlen(LANG_CHARSET) > 0 && COption::GetOptionString("main", "include_charset", "Y") == "Y")
  {
  }
}

1.2.4. Arrays

The arrays consisting of multiple lines of code should be formatted like this:

$arFilter = array(
  "key1" => "value1",
  "key2" => array(
      "key21" => "value21",
      "key22" => "value22",
  )
);

1.3. Empty Lines And Spaces

1.3.1. Empty Lines

It is recommended to add a comment before a logical or functional section (see Comments).

1.3.2. Spaces

Use Cases

The following example shows how a space is used after the commas, but not before the parenthesis:
```
TestMethod($a, $b, $c);
```
These two code fragments are formatted incorrectly:
```
TestMethod($a,$b,$c);
```
and
```
TestMethod( $a, $b, $c );
```
The following example shows to use spaces to properly separate the operators:
```
$a = $b * $c / $d;
```
as opposed to the same code formatted incorrectly:
```
$a=$b*$c/$d;
```
Use spaces to format the “for” statements:
```
for ($i = 0; $i < 10; $i++)
```
Do not merge operators and expressions like this:
```
for($i=0;$i<10;$i++)
```
Note that using tabs to format expressions inside statements is not allowed.
The following formatting should not be made a common practice:
```
$arArray = array(
  "key1" => "value1",
  "key2" => "value2",
);
```
There is no special rule regarding the use of the space, or lack thereof, after the “if” statement.

1.4. Other regulations

Use parentheses to group operators in complex expressions regardless of operator precedence for better readability.

$r = $a + ($b * $c);

2. Naming Conventions

2.1. General Provisions

Do not use underscores in the identifier names because it makes them longer and less readable. Use such names that can describe the identifier purpose and meaning in an unambiguous fashion.

At the same time, try to make your identifier shorter (but they still must be well readable).

If the name contains an abbreviation, it is better to capitalize only the first letter, not all of them, and write the remaining letters in lower case. I.e. it is better to set the name as getHtmlStatistic and not getHTMLStatistic.

2.2. Variable Names

Start with a lowercase character and use uppercase character as separators (camelCase). Variable names can have prefixes if a variable type must be indicated explicitly: ar for arrays, db for data set from database, etc.

For example: $testCounter, $userPassword.

2.3. Method Names

Start with a uppercase character and use uppercase character as separators (Pascal style).

For example: CountVariable, ChangeUserPassword.

2.4. Variable Prefixes

PHP is a loosely typed language. It has only three type groups that are distinguished specifically: scalars, arrays and objects.

Array names should begin with the ar prefix and start other words with an uppercase character. For example: $arResult, $arModifiedUsers.

Object names should begin with the ob prefix and start other words with an uppercase character. For example: $obElement, $obUser.

Objects of the CDBResult type should begin with the db prefix and start other words with an uppercase character. For example: $dbResult.

Variables of scalar types may be prepended with a prefix only if their type is exact and fixed.

For example, in the following code:

$userID = $_REQUEST["var"];
$userID = IntVal($userID);

the variable $userID has no prefix because its type may change at runtime.

However, in the code:

$bFlag = (($aaa > 0)? True : False);

the variable $bFlag has the b prefix because its type is known and is unlikely to be changed.

2.5. Class Names

Class names must begin with the C character. If the class is a part of a module, the next parts of the name should uniquely identify the module. Use uppercase character as separators.

For example: CIBlockElement, CIBlockType, CSaleAffiliate.

If a class is a base class that has specializations for different databases, the base class must begin with CAll.

For example: CAllSaleAffiliate.

2.6. Class Member Access Control

Because PHP does not provide any class member access control mechanism, the developers should stick to the following rules.

Private member variables and methods which must not be accessed by anyone (neither by the public section calls nor by the other modules), should begin with the two underscores. For example: __CheckEmail, __arData. Such members are never described in the documentation and may be changed or deleted disregarding backward compatibility.
Internal member variables and methods which can be accessed by the other modules but must not be accessed by the public section, should begin with one underscore. For example: _CheckEmail, _arData. Such members are not described in the public documentation (but can be described internally), and may be changed or deleted disregarding backward compatibility with prior notification sent to all affected developers.
Other methods and variables are public; they should be described in the public documentation and cannot be changed without providing backward compatibility.

2.7. Constants

Constants must be in uppercase and begin with the BX_ prefix.

For example: BX_ROOT, BX_FILE_PERMISSIONS.

3. Comments

Put a comment before the class or method declaration to describe the purpose of the latter.

Avoid obvious comments like:

$i = $i + 1; // increment i

Add comments to every public class and method.

If you divide the code into logical sections, add comments to each section and describe its purpose.

All comments must be in English.

4. Idioms

4.1. General Provisions

Any programming language has idioms specific to that particular language. An idiom can be a commonly used expression, an iteration technique etc. For example, some of the PHP idioms are the array iteration which is usually written as:

for ($i = 0, $cnt = count($arArray); $i < $cnt; $i++)
{
}

or as:

foreach ($arArray as $key => $value)
{
}

The use of idioms helps other developers skip obvious patterns while concentrating on the important chunks of code, or find the required code fragments by typical patterns (idioms).

To summarize, use widely used patterns and idioms instead of reinventing the wheel.

For example, the following code:

reset($arHashLink);
while(list($hash, $arData)=each($arHashLink))
{
}

should be rewritten as:

foreach ($arHashLink as $hash => $arData)
{
}

4.2. Examples Of Idioms

Conditional operator idiom "?":

$res = ($bTrue? "True" : "False");

5. SQL Queries

Each of the queries: SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING should begin at a new line.

Use the same new line rule as in PHP code: a new line and a tab.

Security

In this chapter, we will review some security issues which should be taken into account for programming in Bitrix Framework.

Sanitizer

Sanitizer is a tool that analyzes the html code introduced by a user. The main task of the sanitizer consists in preventing the implementation/display of a potentially hazardous code in HTML.

The sanitizer comes handy where the user introduces arbitrary html. E.g., in a visual editor or when copying a text from MS Word. In addition to the control of the introduced code, the sanitizer also partially monitors layout validity. In particular, it closes unclosed tags.

How to Filter a Text

If a text (containing HTML tags) typed by the user must be filtered from undesirable HTML tags using the sanitizer, it can be achieved as follows:

$Sanitizer = new CBXSanitizer;

$Sanitizer->AddTags( array (
                  'a' = > array('href','id','style','alt'...),
                  'br' => array(),
                     .... ));

$pureHtml = $Sanitizer->SanitizeHtml($html);

The sanitizer will filter out all tags and attributes which are not contained in the “white” list generated by the function AddTags().

The sanitizer includes 3 preset filtration levels:

SECURE_LEVEL_HIGH (high level) includes the following list:

$arTags = array(
                        'b'        => array(),
                        'br'        => array(),
                        'big'        => array(),
                        'blockquote'    => array(),
                        'code'        => array(),
                        'del'        => array(),
                        'dt'        => array(),
                        'dd'        => array(),
                        'font'        => array(),
                        'h1'        => array(),
                        'h2'        => array(),
                        'h3'        => array(),
                        'h4'        => array(),
                        'h5'        => array(),
                        'h6'        => array(),
                        'hr'        => array(),
                        'i'        => array(),
                        'ins'        => array(),
                        'li'        => array(),
                        'ol'        => array(),
                        'p'        => array(),
                        'small'        => array(),
                        's'        => array(),
                        'sub'        => array(),
                        'sup'        => array(),
                        'strong'    => array(),
                        'pre'        => array(),
                        'u'        => array(),
                        'ul'        => array()
                    );

SECURE_LEVEL_MIDDLE (middle level) includes:

$arTags = array(
                        'a'        => array('href', 'title','name','alt'),
                        'b'        => array(),
                        'br'        => array(),
                        'big'        => array(),
                        'blockquote'    => array('title'),
                        'code'        => array(),
                        'caption'    => array(),
                        'del'        => array('title'),
                        'dt'        => array(),
                        'dd'        => array(),
                        'font'        => array('color','size'),
                        'color'        => array(),
                        'h1'        => array(),
                        'h2'        => array(),
                        'h3'        => array(),
                        'h4'        => array(),
                        'h5'        => array(),
                        'h6'        => array(),
                        'hr'        => array(),
                        'i'        => array(),
                        'img'        => array('src','alt','height','width','title'),
                        'ins'        => array('title'),
                        'li'        => array(),
                        'ol'        => array(),
                        'p'        => array(),
                        'pre'        => array(),
                        's'        => array(),
                        'small'        => array(),
                        'strong'    => array(),
                        'sub'        => array(),
                        'sup'        => array(),
                        'table'        => array('border','width'),
                        'tbody'        => array('align','valign'),
                        'td'        => array('width','height','align','valign'),
                        'tfoot'        => array('align','valign'),
                        'th'        => array('width','height'),
                        'thead'        => array('align','valign'),
                        'tr'        => array('align','valign'),
                        'u'        => array(),
                        'ul'        => array()
                    );

SECURE_LEVEL_LOW (low level) includes:

$arTags = array(
                        'a'        => array('href', 'title','name','style','id','class','shape','coords','alt','target'),
                        'b'        => array('style','id','class'),
                        'br'        => array('style','id','class'),
                        'big'        => array('style','id','class'),
                        'blockquote'    => array('title','style','id','class'),
                        'caption'    => array('style','id','class'),
                        'code'        => array('style','id','class'),
                        'del'        => array('title','style','id','class'),
                        'div'        => array('title','style','id','class','align'),
                        'dt'        => array('style','id','class'),
                        'dd'        => array('style','id','class'),
                        'font'        => array('color','size','face','style','id','class'),
                        'h1'        => array('style','id','class','align'),
                        'h2'        => array('style','id','class','align'),
                        'h3'        => array('style','id','class','align'),
                        'h4'        => array('style','id','class','align'),
                        'h5'        => array('style','id','class','align'),
                        'h6'        => array('style','id','class','align'),
                        'hr'        => array('style','id','class'),
                        'i'        => array('style','id','class'),
                        'img'        => array('src','alt','height','width','title'),
                        'ins'        => array('title','style','id','class'),
                        'li'        => array('style','id','class'),
                        'map'        => array('shape','coords','href','alt','title','style','id','class','name'),
                        'ol'        => array('style','id','class'),
                        'p'        => array('style','id','class','align'),
                        'pre'        => array('style','id','class'),
                        's'        => array('style','id','class'),
                        'small'        => array('style','id','class'),
                        'strong'    => array('style','id','class'),
                        'span'        => array('title','style','id','class','align'),
                        'sub'        => array('style','id','class'),
                        'sup'        => array('style','id','class'),
                        'table'        => array('border','width','style','id','class','cellspacing','cellpadding'),
                        'tbody'        => array('align','valign','style','id','class'),
                        'td'        => array('width','height','style','id','class','align','valign','colspan','rowspan'),
                        'tfoot'        => array('align','valign','style','id','class','align','valign'),
                        'th'        => array('width','height','style','id','class','colspan','rowspan'),
                        'thead'        => array('align','valign','style','id','class'),
                        'tr'        => array('align','valign','style','id','class'),
                        'u'        => array('style','id','class'),
                        'ul'        => array('style','id','class')
                    );

The sanitizer can be used together with a preset level as follows:

$Sanitizer = new CBXSanitizer;

$Sanitizer->SetLevel(CBXSanitizer::SECURE_LEVEL_MIDDLE);

$pureHtml = $Sanitizer->SanitizeHtml($html);

The CBXSanitizer class functions are available for working with sanitizer.

Anti-Frame Protection

The limits on the frame work can be activated/deactivated on the page Anti-frame protection (Settings > Proactive Protection > Anti-frame protection).

The prohibition to use of cross-domain frames referring to resource pages is introduced by setting the header X-Frame-Options to the value SAMEORIGIN.

X-Frame-Options

This header indicates to the browser if website pages can be loaded through <frame>/<iframe>.

The DENY value will prohibit loading through frames, the SAMEORIGIN value will permit loading through frames, provided that both the frame and the page that loads such frame are located on the same domain (Same Origin Policy).

The main function of this protection consists in preventing click-jacking. As an additional advantage, it will permit you to prevent the attack described by Ben Schmidt.

If necessary you can add your page to the exceptions by defining the constant B_SECURITY_FRAME as false before connecting the core.

Anti-frame protection in Bitrix24 On-premise editions using BitrixVM

Both Bitrix24 On-premise editions and Bitrix Virtual Appliance have anti-frame protection available inside Bitrix24 control panels. You will find header for anti-frame protection in the nginx config file at /etc/nginx/bx/conf/general-add_header.conf. Such entry looks as follows:

add_header X-Frame-Options SAMEORIGIN;

The same header is added when you enable anti-frame protection using the proactive protection module. And, you can configure exceptions, if such header is not required, for different Internet metrics and analytics services.

BitrixVM with standard settings can have a situation, when nginx config overlaps the general system anti-frame protection setup. In this case, header will be always available, even if disabled in the control panel settings. But, with anti-frame protection enabled, header will be duplicated and sites added as exceptions to anti-frame protection - won't work correctly.

A solution for such situation is to use only a single tool. It's recommended to use Anti-frame protection feature available in Bitrix24 to avoid necessity of regular updates for server config files. You can comment out the header once in the file /etc/nginx/bx/conf/general-add_header.conf for BitrixVM:

#add_header X-Frame-Options SAMEORIGIN;

And then you can enable anti-frame protection via Proactive protection > Anti-frame protection.

Now X-Frame-Options header will be written correctly and you can add exceptions via control panel, without changes to server configuration files.

Examples, tricks, and advice

This chapter is dedicated to advice and examples that may help developers to learn and work with Bitrix Framework.

The Use of Page Navigation for Data Arrays

An example of selection from several infoblocks using page navigation and sorting.

Task

Select a list of elements fr om several infoblocks and display it as a table;
Have the possibility to sort the elements;
Page navigation must work.

Solution

This example can be used if the number of selected elements is not so big (up to 100). Naturally, cache shall be used.

Let us collect all the data into an associative array, such as this one:

[ITEAM] => Array
        (
            [0] => Array
                (
                    [CITY_NAME] => value
                    [CITY_DETAIL_URL] => value
                    [OBJECT_NAME] => value
                    [OBJECT_ID] => 2487
                    [DATE_CREATE] => 02.07.2006
                    [STATUS] => Y
                    [PAID_STATUS] => Y
                    [DATEIL_OBJECT_URL] => value
                )

            [1] => Array
                (
                    [CITY_NAME] => value
                    [CITY_DETAIL_URL] => value
                    [OBJECT_NAME] => value
                    [OBJECT_ID] => 2489
                    [DATE_CREATE] => 02.07.2006
                    [STATUS] => Y
                    [PAID_STATUS] => N
                    [DATEIL_OBJECT_URL] => value
                )

Now, the array $arResult['ITEAM'] must be sorted; for this, we describe the following class:

class CCabinet_SortObject {

	function __cmp_ValueOf($a, $b, $name, $order) {
		if(is_set($a[$name]) && is_set($b[$name])) {
			if($order == 'ASC')
				return ($a[$name]<$b[$name])?true:false;
 			elseif($order == 'DESC')
 				return ($b[$name]>$a[$name])?false:true;
		}
	}

	function cmp_STATUS_ASC($a, $b) {
		return CCabinet_SortObject::__cmp_ValueOf($a, $b, "STATUS", "ASC");
	}

	function cmp_STATUS_DESC($a, $b) {
		return CCabinet_SortObject::__cmp_ValueOf($a, $b, "STATUS", "DESC");
	}

	function cmp_NAME_ASC($a, $b) {
		return CCabinet_SortObject::__cmp_ValueOf($a, $b, "OBJECT_NAME", "ASC");
	}

	function cmp_NAME_DESC($a, $b) {
		return CCabinet_SortObject::__cmp_ValueOf($a, $b, "OBJECT_NAME", "DESC");
	}

	function cmp_CITY_ASC($a, $b) {
		return CCabinet_SortObject::__cmp_ValueOf($a, $b, "CITY_NAME", "ASC");
	}

	function cmp_CITY_DESC($a, $b) {
		return CCabinet_SortObject::__cmp_ValueOf($a, $b, "CITY_NAME", "DESC");
	}

	function cmp_DATE_DESC($a, $b) {
		if ($a["DATE_CREATE"] == $b["DATE_CREATE"]) {
        	return 0;
	    }
	    return ($a["DATE_CREATE"] > $b["DATE_CREATE"]) ? -1 : 1;
	}

	function cmp_DATE_ASC($a, $b) {
		if ($a["DATE_CREATE"] == $b["DATE_CREATE"]) {
        	return 0;
	    }
	    return ($a["DATE_CREATE"] < $b["DATE_CREATE"]) ? -1 : 1;
	}

}

Example of class application:

usort($arResult['ITEAM'], array("CCabinet_SortObject", "cmp_".$arParams['SORT_BY']."_".$arParams['SORT_ORDER']));

After that, we have to break down the array by pages using API:

$rs_ObjectList = new CDBResult;
$rs_ObjectList->InitFromArray($arResult['ITEAM']);
$rs_ObjectList->NavStart(10, false);
$arResult["NAV_STRING"] = $rs_ObjectList->GetPageNavString("", 'komka.cabinet');
$arResult["PAGE_START"] = $rs_ObjectList->SelectedRowsCount() - ($rs_ObjectList->NavPageNomer - 1) * $rs_ObjectList->NavPageSize;
while($ar_Field = $rs_ObjectList->Fetch())
{
$arResult['_ITEAM'][] = $ar_Field;
}

Use of Agents

You are already familiar with the Theory of agents. Now, let us consider some examples and details of this technique.

Example of Agents

Example of an Agent Creation

If you have to add agents dynamically, use API agents. If you have to add one or two agents, it is easier to add them manually.

An agent is created using the button Add an Agent on the page Settings > System settings > Agents:

Some comments on the parameters which meanings may be unclear from the name:

Date of the last run - if the agent is periodical, the time of the last run will be displayed when editing the agent;
Date and time of the next run – the work start time of the agent; if the agent is non-periodical, it will be executed once at this time;
Module - this module will be connected automatically when the agent is executed (in particular, the file /bitrix/modules/module ID/include.php will be connected) making it possible to use the functions of this module in the agent;
Agent function - name of the function that will be executed when the agent is launched (in our example, testAgent());
User ID – the agent will be launched following the hit of a specific user;

The function itself will look as follows:

function testAgent()
{
        mail('mail@gmail.com', 'Agent', 'Agent');
        return "testAgent();";
}

The function should be added to the file /bitrix/php_interface/init.php.

Simple Examples of Agents

<?
// add the agent of the module “Statistics”
CAgent::AddAgent(
    "CStatistic::CleanUpStatistics_2();", // function name
    "statistic",                          // module identifier
    "N",                                  // the agent is not critical to the amount of launches
    86400,                                // launch interval - 1 day
    "07.04.2005 20:03:26",                // the date of first check for launch
    "Y",                                  // the agent is active
    "07.04.2005 20:03:26",                // the date of first launch
    30);
?>

<?
// add the agent of the module “Technical Support”
CAgent::AddAgent(
    "CTicket::AutoClose();",  // function name
    "support",                // module identifier
    "N",                      // the agent is not critical to the amount of launches
    86400,                    // launch interval - 1 day
    "",                       // the date of first check - current
    "Y",                      // the agent is active
    "",                       // the date of first launch - current
    30);
?>

<?
// add arbitrary agent which does not belong to an module
CAgent::AddAgent("My_Agent_Function();");
?>

<?
// file /bitrix/php_interface/init.php

function My_Agent_Function()
{
   // perform any actions
   return "My_Agent_Function();";
}
?>

<?
// add an arbitrary agent belonging to the module
// with the identifier my_module

CAgent::AddAgent(
   "CMyModule::Agent007(1)", 
   "my_module", 
   "Y", 
    86400);
?>

<?
// this agent will be launched exactly 7 times with a frequency of once per 24 hours
// after that it will be deleted from the table of agents.

Class CMyModule
{
   function Agent007($cnt=1)
   {
      echo "Hello!";
      if($cnt>=7)
         return "";
      return "CMyModule::Agent007(".($cnt+1).")";
   }
}
?>

Launching of Agents from Cron

It is quite often the case that some especially heavy agents have to be transferred to cron in order to be executed.

Launching Mechanism

Go to the page Settings > Tools > PHP command line and execute the following code:

COption::SetOptionString("main", "agents_use_crontab", "Y");
echo COption::GetOptionString("main", "agents_use_crontab", "N");

The code execution must result in the “Y” meaning that only periodic agents will be executed on the cron.

Go to the page Settings > System settings > Agents and make sure the column Periodical (for control). Now, edit the agents that you need by checking the box Periodical.

Add the following command to the cron:

/usr/bin/php -f /var/www/bitrix/modules/main/tools/cron_events.php

Set periodicity, for example: */10 * * * * - which means once per ten minutes.

Note: The agent launching procedure tries to cancel the limit immediately before performing the task:

@set_time_limit(0);
ignore_user_abort(true);

If set_time_limit is allowed, the execution time may exceed the value indicated in the settings of the file php.ini.

But do not forget that there are limits on the part of the host: for the amount of memory, execution time, launch periodicity, etc.

General Solution for Execution of All Agents from Cron

To begin with, we disable the execution of the agents prompted by hits. To do so, we perform the following command in the php console:

COption::SetOptionString("main", "agents_use_crontab", "N"); 
echo COption::GetOptionString("main", "agents_use_crontab", "N"); 

COption::SetOptionString("main", "check_agents", "N"); 
echo COption::GetOptionString("main", "check_agents", "Y");

The result of the execution must be "NN".

After this, we will remove the definition of the following constants from the file /bitrix/php_interface/dbconn.php:

define("BX_CRONTAB_SUPPORT", true);
define("BX_CRONTAB", true);

And add the following string in this file:

if(!(defined("CHK_EVENT") && CHK_EVENT===true))
   define("BX_CRONTAB_SUPPORT", true);

We create a file for the agent checking and sending of system messages /bitrix/php_interface/cron_events.php:

<?
$_SERVER["DOCUMENT_ROOT"] = realpath(dirname(__FILE__)."/../..");
$DOCUMENT_ROOT = $_SERVER["DOCUMENT_ROOT"];

define("NO_KEEP_STATISTIC", true);
define("NOT_CHECK_PERMISSIONS",true); 
define('CHK_EVENT', true);

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

@set_time_limit(0);
@ignore_user_abort(true);

CAgent::CheckAgents();
define("BX_CRONTAB_SUPPORT", true);
define("BX_CRONTAB", true);
CEvent::CheckEvents();

if (CModule::IncludeModule("subscribe";))
{
      $cPosting = new CPosting;
      $cPosting->AutoSend();
} 
?>

And add the following script to cron:

*/5 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/php_interface/cron_events.php

After that, all agents and system message sending will be processed from cron once every 5 minutes.

Note: The execution time can be adjusted according to the project. Also, there is the possibility to “speed up” the delivery of mail notices by setting a bigger value for mail_event_bulk. This delay will be unnoticeable for users if you set up checking once per minute together with sending 100 messages at a time.

To prevent the mail message sending queue from growing it is recommended that the parameter responding for the number of mail events processed at a time be changed. To do this, perform the following command in the php console:

COption::SetOptionString("main", "mail_event_bulk", "20"); 
echo COption::GetOptionString("main", "mail_event_bulk", "5");

If the next launch of cron_events.php occurs before the completion of the previously launched scripts, no agents will be launched, and the script will complete its operation (because the agents are blocked for the time of the execution). In this case, the handling will be the same as hit handling, and a new hit may occur at the time when previous hit agents are still being executed.

Another Example

Below is a standard script code launched from cron:

#!/usr/bin/php 
<?php 
$_SERVER["DOCUMENT_ROOT"] = "/home/hosting/www"; 
$DOCUMENT_ROOT = $_SERVER["DOCUMENT_ROOT"]; 
define("NO_KEEP_STATISTIC", true); 
define("NOT_CHECK_PERMISSIONS", true); 
set_time_limit(0); 
define("LANG", "ru"); 
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php"); 

//your code... 

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_after.php"); 
?>

Use of Events

This chapter describes some examples of work with events.

System actions mainly deal with three types of events:

OnBefore;
On;
OnAfter.

It is important to know which type should be used in your specific case. OnBefore events are executed in any case. But OnAfter events are executed only when data entered have been verified (consistency of password, e-mail, etc.). Accordingly, if something is wrong with the data, the event will not be executed.

How to Write an Event Handler

Let us set an abstract problem: for example, we want to add the information that no bad language is allowed for each workgroup to be created and establish that a certain user is forbidden to create groups at all.

Event Raising Analysis

To begin with, let us take a closer look at these events. You are already familiar with the theory; let us consider a real-world example.

Handlers are always called using the same procedure, only variables and response handling logic change. Source code shall be referred to for analysis. It can be done by reviewing system files or, better still, using the script Live API.

Let us review the event OnBeforeSocNetGroupAdd as an example:

Number of variables. This event contains only one variable ($arFields). You will have to call exactly the same number of variables in our handler. There may be two or more variables. For example, in the event OnSocNetGroupAdd:

Redefinition of variables. If one of the variables is preceded by &, it means it can be redefined (it is called “pass by reference”).

Action cancellation. In our case, it is possible for the event OnBeforeSocNetGroupAdd if we provide for return false in our handler, no group will be created. However, for example OnSocNetGroupAdd does not offer the possibility to cancel an action. That is because the action has already been performed.

Creating Event Handler

Let us recall the theory: you have to use RegisterModuleDependences to handle events in your modules and AddEventHandler to handle in other cases.

We know the module name (socialnetwork) and the event name (OnBeforeSocNetGroupAdd). So we write a function/method taking into account the following:

Number of variables
Redefinition possibility
Action cancellation

How to learn the contents of variables, array keys, etc.?

Display variables completing the operation in the body of function:

echo ''; print_r($arFields); echo '
'; die();

Cancelling actions

Cancel an action and submit an error to the system:

if ($GLOBALS['USER']->GetID() == 2) {
   $GLOBALS['APPLICATION']->throwException('You cannot create groups.');
   return false;
}

Result

We have built an abstract handler which adds a rule to the group description and prohibits the user with the ID=2 from creating groups at all.

AddEventHandler('socialnetwork', 'OnBeforeSocNetGroupAdd', 'TestHandler');
function TestHandler(&$arFields) {
   $arFields['DESCRIPTION'] .= ' It is forbidden to use foul language!';
   if ($GLOBALS['USER']->GetID() == 2) {
      $GLOBALS['APPLICATION']->throwException('You cannot create groups.');
      return false;
   }
}

Additional Information

Question: Can the function AddEventHandler be called several times for the same event?

Response: You can call the function AddEventHandler with the same first two parameters several times. There are very few cases when you cannot do that (only one handler per event is permitted). It is advisable to indicate the fourth parameter when re-calling the function. This parameter is responsible for handler call priority. If this parameter is not indicated, the handlers will be called following the order of their addition.

How does the event handler “know” what event it is handling?

A function is an even handler for modules. A function does not “know” which modules and which events, but it must perform different actions depending on the event that has occurred.

Question: How does the event handler “know” which event it is handling?

The solution depends on the initialization.

AddEventHandler - add a layer.

function OnAdd()
{
      RealHandler("add");
}

function OnUpdate()
{
      RealHandler("update");
}

RegisterModuleDependences - add an argument at the registration stage.

$TO_METHOD_ARG = Array("argument"=>"OnUserDelete");
RegisterModuleDependences("main", "OnUserDelete", "forum", "CForum", "OnUserDelete", $sort, $TO_PATH, $TO_METHOD_ARG);

function Handler($arguments, &$arFields)
{
   // code
}

SQL Query and PHP Prompt

SQL Query

The form SQL quer (Control Panel > Settings > Tools > SQL query) is intended for the execution of SQL database queries. It is possible to execute any SQL queries.

Important! The system does not establish any limits on SQL queries, so be extremely careful when executing queries such as UPDATE, DELETE, DROP etc.

PHP Command Line

Sometimes a specific code calling Bitrix Framework API functions must be executed quickly without creating new pages on website. In this case, a convenient and simple tool PHP command line will come handy. It permits executing arbitrary PHP code with the invocation of functions.

The tool is located in the administrative part of the website at: Control Panel > Settings > Tools > PHP command line and has the address /bitrix/admin/php_command_line.php.

The execution result of the code using the functions of the class CUser of the Kernel module is provided below:

Sorting in the components news.list and catalog.section

In order to perform sorting the parameters ELEMENT_SORT_FIELD and ELEMENT_SORT_ORDER must be submitted to the component news.list or catalog.section.

The sorting can be made by standard fields. To do so, use the list provided below:

id - element ID;
sort - sorting index;
timestamp_x - modification date;
name - name;
active_from or date_active_from - element start date;
active_to or date_active_to - element end date;
status - code of the element status in the document flow;
code - mnemonic code of the element;
iblock_id - numerical code of the information block;
modified_by - code of the last modifying user;
active - indicator of activity of an element;
show_counter - number of shows of an element (recorded by the function CIBlockElement::CounterInc);
show_counter_start - time of first show of an element (recorded by the function CIBlockElement::CounterInc);
shows - averaged number of shows (number of shows/duration of a show);
rand - random order;
xml_id or external_id - external code;
tags - tags;
created - creation time;
created_date - creation date with no regard to the time;
cnt - number of elements (only if grouping parameters are set).

Note: The fields active_from and active_to are out of date.

You can also sort by the properties that you create for an information block element:

property_<PROPERTY_CODE> - by the value of the property with a numeric or mnemonic code PROPERTY_CODE (e.g., PROPERTY_123 or PROPERTY_NEWS_SOURCE).
propertysort_<PROPERTY_CODE> - by the sorting index of the property value option. Only for List properties.
catalog_<CATALOG_FIELD>_<PRICE_TYPE> - by the field CATALOG_FIELD (may be PRICE or CURRENCY) from the price with the format PRICE_TYPE (e.g., catalog_PRICE_1 or CATALOG_CURRENCY_3). Sorting must have the following format: CATALOG_(PRICE or CURRENCY)_type-of-price-ID.
catalog_QUANTITY - sorting by quantity.
PROPERTY_<PROPERTY_CODE>.<FIELD> - by field value of the element indicated as binding. PROPERTY_CODE - a mnemonic or symbol property code of the type element binding. FIELD can take the following values:
- ID
- TIMESTAMP_X
- MODIFIED_BY
- CREATED
- CREATED_DATE
- CREATED_BY
- IBLOCK_ID
- ACTIVE
- ACTIVE_FROM
- ACTIVE_TO
- SORT
- NAME
- SHOW_COUNTER
- SHOW_COUNTER_START
- CODE
- TAGS
- XML_ID
- STATUS
PROPERTY_<PROPERTY_CODE>.PROPERTY_<PROPERTY_CODE2> - by the property value of the element indicated as binding. PROPERTY_CODE - mnemonic or symbol property code of the type element binding. PROPERTY_CODE2 - property code of the related elements.
HAS_PREVIEW_PICTURE and HAS_DETAIL_PICTURE - sorting by picture availability.

Note: The catalog properties are available only if the module Commercial catalog is in place.

The sorting type is indicated according to the list:

asc - in ascending order;
nulls,asc - in ascending order with empty values in the beginning of the selection;
asc,nulls - in ascending order with empty values in the end of the selection;
desc - in descending order;
nulls,desc - in descending order with empty values in the beginning of the selection;
desc,nulls - in descending order with empty values in the end of the selection.

The simplest way to submit new sorting parameters to a component consists in using the query $_GET and transmission of the relevant variables.

Also you can use $_SESSION and enter variables into array of variables of the session. For example, you have to make links or buttons (name, price, bestseller, and/or delivery date) to sort the goods in a catalog section (we use the compound component catalog). After we have copied the template, we open the file section.php and make the following modifications to it before connecting the component bitrix:catalog.section:

<?if ($_GET["sort"] == "name" || 
              $_GET["sort"] == "catalog_PRICE_3" ||
              $_GET["sort"] == "property_PRODUCT_TYPE" ||
              $_GET["sort"] == "timestamp_x"){
		$arParams["ELEMENT_SORT_FIELD"] = $_GET["sort"];
		$arParams["ELEMENT_SORT_ORDER"] = $_GET["method"];
	}else{}?>

This code is required to change the sorting parameters in a component. Next, open the file template.php of the component catalog.section and add sorting management references:

<p class="sort">Sorting:
	<a <?if ($_GET["sort"] == "name"):?> class="active" <?endif;?> href="<?=$arResult["SECTION_PAGE_URL"]?>?sort=name&method=asc">title</a> 
	<a <?if ($_GET["sort"] == "catalog_PRICE_3"):?> class="active" <?endif;?> href="<?=$arResult["SECTION_PAGE_URL"]?>?sort=catalog_PRICE_3&method=asc">price</a> 
	<a <?if ($_GET["sort"] == "property_PRODUCT_TYPE"):?> class="active" <?endif;?> href="<?=$arResult["SECTION_PAGE_URL"]?>?sort=property_PRODUCT_TYPE&method=desc">bestseller</a> 
	<a <?if ($_GET["sort"] == "timestamp_x"):?> class="active" <?endif;?> href="<?=$arResult["SECTION_PAGE_URL"]?>?sort=timestamp_x&method=desc">delivery date<</a>
</p>

This sorting can be executed without reloading the page by using jQuery.

Custom Fields

Custom field - is a system functionality that permits adding fields that are not included in the standard functionality to system objects.

It is important to distinguis Custom Fields in system modules and properties used in infoblocks, although the term custom fields is used in system forms (a user set up/editing form, infoblock section set up/editing form, and others).

Custom fields is an entity:

more multi-purposed, because the fields can be set up for various objects of the system compared to the infoblock properties,
more limited in options because this entity admits a small number of data types.

An unlimited number of custom fields can be created for each object. When choosing any type of a custom field, additional setup fields become available for each chosen type.

The application of custom fields in the system to any module is set up using the objects which must be indicated when creating a field. Not all modules have objects for custom fields by default. A developer can create own objects taking into account that GetList methods support only system objects:

Built-in custom field objects
Module	Object	Description
Kernel	USER	User
Blogs	BLOG_BLOG	Blog
	BLOG_POST	Blog post
	BLOG_COMMENT	Message comment
Tasks	TASKS_TASK	Tasks
	TASKS_SCRUM_ITEM	Drive files link
	TASKS_TASK_TEMPLATE_CHECKLIST	Checklist in templates
	TASKS_TASK_CHECKLIST	Checklist in tasks
	TASKS_TASK_TEMPLATE	Templates
Information blocks	IBLOCK_N_SECTION	iblock sections with ID = N
Information blocks	IBLOCK_N	iblock with ID = N
Calendar	CALENDAR_EVENT	Calendar events
Training	LEARN_ATTEMPT	Test runs
Social network	SONET_GROUP	Social network groups
	SONET_COMMENT	Comments
	SONET_LOG	Logs
Document library	WEBDAV	Document library
Forum	FORUM_MESSAGE	Forum messages
Highload blocks	HLBLOCK_N	Highload block with ID=N
Commercial catalog	PRODUCT *	Products
	CAT_STORE	Warehouses
	[ICO_NEW data-adding-timestamp="1702552810"]CAT_STORE_DOCUMENT_A[/ICO_NEW]	"Stock receipt" inventory object
	[ICO_NEW data-adding-timestamp="1702552810"]CAT_STORE_DOCUMENT_S[/ICO_NEW]	"Stock adjustment" inventory object
	[ICO_NEW data-adding-timestamp="1702552810"]CAT_STORE_DOCUMENT_M[/ICO_NEW]	"Stock transfer" inventory object
	[ICO_NEW data-adding-timestamp="1702552810"]CAT_STORE_DOCUMENT_R[/ICO_NEW]	"Return" inventory object
	[ICO_NEW data-adding-timestamp="1702552810"]CAT_STORE_DOCUMENT_D[/ICO_NEW]	"Write off" inventory object
	[ICO_NEW data-adding-timestamp="1702552810"]CAT_STORE_DOCUMENT_U[/ICO_NEW]	"Cancel reservation" inventory object
Shopping cart	RECYCLEBIN_DISK	Shopping cart items
CRM	CRM_MAIL_TEMPLATE	Email templates
	CRM_TIMELINE	Timeline
	CRM_LEAD	Leads
	CRM_DEAL	Deals
	CRM_COMPANY	Companies
	CRM_CONTACT	Contacts
	CRM_ORDER	Orders
	CRM_INVOICE	Invoices
	CRM_(смарт-процесс)	SPA
	CRM_ACTIVITY	workflow activities
	CRM_QUOTE	Estimates
	CRM_LEAD_SPD	Leads with binding to shopping cart items
	CRM_DEAL_SPD	Deals with binding to shopping cart items
	CRM_COMPANY_SPD	Companies with binding to shopping cart items
	CRM_CONTACT_SPD	Contacts with binding to shopping cart items
	CRM_ORDER_SPD	Orders with binding to shopping cart items
	CRM_INVOICE_SPD	invoices with binding to shopping cart items
	CRM_(SPA)_SPD	SPAs with binding to sopping cart items
	CRM_ACTIVITY_SPD	Workflow activities with binding to shopping cart items
	CRM_QUOTE_SPD	Estimates with binding to shopping cart items
Robotic Process Automation (RPA)	RPA_(process id)	Automation rule
Robotic Process Automation (RPA)	RPA_COMMENT	Comments to automation rule

* — supports custom fields only.

Note: The modules using information blocks can work with objects of custom fields of the Information blocks module.

Creating Fields

Custom fields can often be created on the page Control Panel >Settings > System settings > Custom fields or, preferable, using the link Add user property in the system forms which provide for the standard adding of custom properties:

A form to add/edit a user;
A form to add/edit a section of an information block;
A form to add/edit a blog.

The page Custom fields can be used if the developer knows exactly which object type identifier they require.

Custom fields can be created with various data types. By default, the system provides for the following types:

Integer
True/False
Video
Template
List
Text
Date/Time
Bind to highload information block elements
Link to information block sections
Bind to Information block elements
Bind to CRM elements
Bind to CRM dictionaries
File
Number
Document from Library
Link to Employee
Revision history file in Document Library
Poll

Events can be used for working with custom fields.

Kernel module events used during work with custom fields:

Event	Is called	Method
OnUserTypeBuildList	When the list of custom fields is being built	CUserTypeManager::GetUserType
OnUserTypeRightsCheck	When verifying the rights of access to custom fields	GetRights
OnAfterFetch	When the list of custom fields is being built

Work examples

Filtering

Custom fields of sections can participate in filtering.

$sec_Filter= array(  
   "IBLOCK_ID" => $IBLOCK_ID, 
   "DEPTH_LEVEL" => "2", 
   "!UF_ARC_PAGES" => ""
);

Note: Filtering by custom fields work only provided that IBLOCK_ID filter is available.

All sections with the property UF_ARC_PAGES set will be selected.

Filtering by value of a custom property:

$arSFilter ['=UF_USERS_PROPERTY'] =$users_property_value;

Sorting

Sorting by custom fields of sections:

    $arSort = array(
       "UF_RATING"=>"asc",
       "sort"=>"asc"
      
   );

Obtaining Values

The method GetList of the appropriate class is used to obtain the value of a custom field.

The value of a custom field for the user with ID=2 can be obtained as follows:

$rsUser = CUser::GetByID($user);
$arUser = $rsUser->Fetch();
$required value = $arUser['custom field code'];

In order to obtain a value of a custom field of a specific user, where the field type is a line, the method GetList of the class CUser should be used. In this case, an array with the key SELECT must be submitted as a fourth argument. The values of this key are the list of codes of the custom properties we are looking for.

global $USER;
$arFilter = array("ID" => $USER->GetID());
$arParams["SELECT"] = array("UF_USER_CARD_CODE");
$arRes = CUser::GetList($by,$desc,$arFilter,$arParams);
    if ($res = $arRes->Fetch()) {
        echo $res["UF_USER_CARD_CODE"];
    }

If the type of a custom field is a list, then the method GetList of the class CUserFieldEnum should be used to obtain the value (or values, if a multiple choice is possible).

global $USER;
$arFilter = array("ID" => $USER->GetID());
$arParams["SELECT"] = array("UF_LIST_TASK");
$arRes = CUser::GetList($by,$desc,$arFilter,$arParams);
    if ($res = $arRes->Fetch()) {
        foreach ($res["UF_LIST_TASK "] as $id) {
                $rsRes= CUserFieldEnum::GetList(array(), array(
                    "ID" => $id,
                ));
                if($arResult = $rsRes->GetNext())
                    echo $arGender["VALUE"];
            }   
}

If a list of all the values of the custom field of a list-type USER object, the following code should be used:

global $USER_FIELD_MANAGER;
$arFields = $USER_FIELD_MANAGER->GetUserFields("USER");
$obEnum = new CUserFieldEnum;
$rsEnum = $obEnum->GetList(array(), array("USER_FIELD_ID" => $arFields["UF_LIST_TASK "]["ID"]));
while($arEnum = $rsEnum->GetNext()){
   echo $arEnum["VALUE"];
}

To select a value of a custom field from a section of the information block, the method CIBlockSection:GetList can be used:

	
$aSection   = CIBlockSection::GetList( array(), array(
    'IBLOCK_ID'         => 3,
    'CODE'          => 'test_section',
), false, array( 'UF_DEV2DAY_FIELD' ) )->Fetch();

Note: Infoblock identifier (IBLOCK_ID) must be submitted without fail; otherwise, no custom properties will be selected.

Obtaining a value of a file-type custom field of a specific section of the infoblock:

$rsResult = CIBlockSection::GetList(array("SORT" => "ASC"), array("IBLOCK_ID" => "1"), false, $arSelect = array("UF_*"));
while ($arResult = $rsResult -> GetNext())
{
print "" . print_r($arResult, true) . "";
}

Since custom fields can be used with sections of an information block as well as any other entities, the class CUserTypeManager shall be used to select values by entity identifier. An instance of this class is already located in the global variable $USER_FIELD_MANAGER.

	
global $USER_FIELD_MANAGER;
 
$aSection   = CIBlockSection::GetList( array(), array(
    'IBLOCK_CODE'   => 'shop_news',
    'CODE'          => 'test_section',
) )->Fetch();
 
if( !$aSection ) {
    throw new Exception( 'The section is not found' );
}
 
$aUserField = $USER_FIELD_MANAGER->GetUserFields(
'IBLOCK_3_SECTION',
$aSection['ID']
); // array

As a result, we will obtain an array containing all the information about the field and its value for a specific object.

Note: In order to obtain all the values of custom fields, Array("UF_*") shall be indicated in the parameter arSelect.

Adding, editing, and deleting custom properties and their values

The class CUserTypeEntity is in charge of work with custom fields.

An example of adding a String-type custom property

/**
 * Adding a custom property
 */
$oUserTypeEntity    = new CUserTypeEntity();
 
$aUserFields    = array(
/*
* Identifier of an entity to which the property will be bound.
* The following format is used for a section - IBLOCK_{IBLOCK_ID}_SECTION
*/
    'ENTITY_ID'         => 'IBLOCK_3_SECTION',
/* Field code. It must always begin with UF_ */
    'FIELD_NAME'        => 'UF_DEV2DAY_FIELD',
    /* Indicate that the type of the new custom property is string */
    'USER_TYPE_ID'      => 'string',
/*
* XML_ID of the custom property.
* To be used during uploading as a field name
*/
'XML_ID'            => 'XML_ID_DEV2DAY_FIELD',
/* Sorting */
'SORT'              => 500,
/* Whether the field is multiple or not */
'MULTIPLE'          => 'N',
/* Whether the property is mandatory or not */
    'MANDATORY'         => 'N',
/*
* Show in the list filter. Possible values:
* Do not show = N, exact match = I,
* mask search = E, substring search = S
*/
    'SHOW_FILTER'       => 'N',
/*
* Do not show in the list. 
*/
    'SHOW_IN_LIST'      => '',
/*
* Do not permit editing by users.
*/
    'EDIT_IN_LIST'      => '',
    /* Field values participate in the search */
    'IS_SEARCHABLE'     => 'N',
    /*
* Additional field settings (depend on the type).
* In our case, for the string type
*/
    'SETTINGS'          => array(
        /* Default value */
        'DEFAULT_VALUE' => '',
        /* Entry field size for display */
        'SIZE'          => '20',
/* Number of rows in the entry field */
        'ROWS'          => '1',
        /* Minimum length of the line (0 – do not verify) */
        'MIN_LENGTH'    => '0',
/* Maximum length of the line (0 – do not verify) */
        'MAX_LENGTH'    => '0',
        /* A regular expression for verification */
        'REGEXP'        => '',
),
/* Edit form label */
    'EDIT_FORM_LABEL'   => array(
        'en'    => 'User field',
    ),
/* List label */
    'LIST_COLUMN_LABEL' => array(
        'en'    => 'User field',
    ),
/* List filter label */
    'LIST_FILTER_LABEL' => array(
'en'    => 'User field',
),
/* Error message (optional) */
    'ERROR_MESSAGE'     => array(
        'en'    => 'An error in completing the user field',
),
/* Help */
    'HELP_MESSAGE'      => array(
'en'    => '',
    ),
);
 
$iUserFieldId   = $oUserTypeEntity->Add( $aUserFields ); // int

If a correct property is added to the variable $iUserFieldId, the identifier of the new custom property will be returned.

In order to create custom fields of other types, replace the value of USER_TYPE_ID:

enumeration - List
double - Number
integer - Integral number
boolean - Yes/No
string - String
file - File
video - Video
datetime - Date/Time
iblock_section - Binding to infoblock sections
iblock_element - Binding to infoblock elements
string_formatted - Template
crm - Binding to CRM elements
crm_status - Binding to CRM reference tables

Custom Property Update

When updating a custom property, the changes in its type (USER_TYPE_ID), object to be bound (ENTITY_ID), and field code (FIELD_NAME) are restricted. It is connected with possible errors in linking values and entities. If one of these fields is to be changed, first of all a new custom property must be created, with all the values bound to it. That done, the old property must be deleted.

An example of a custom property update:

$oUserTypeEntity->Update( $iUserFieldId, array(
    'MANDATORY' => 'Y',
) ); // boolean;

The example establishes that the field is mandatory.

Custom Field Removal

The identifier of a custom field must be submitted:

	
$oUserTypeEntity->Delete( $iUserFieldId );   // CDBResult

Adding and Updating Values of Custom Fields

Adding and updating is also implemented through the CUserTypeManager and the Update method.

global $USER_FIELD_MANAGER;
 
$aSection   = CIBlockSection::GetList( array(), array(
    'IBLOCK_CODE'   => 'shop_news',
    'CODE'          => 'test_section',
) )->Fetch();
 
if( !$aSection ) {
    throw new Exception( 'No section is found' );
}
 
$USER_FIELD_MANAGER->Update( 'IBLOCK_3_SECTION', $aSection['ID'], array(
    'UF_DEV2DAY_FIELD'  => 'updated value'
) ); // boolean

If the update is successful, the method will return true.

Adding a Custom Property to an Infoblock Section

If a custom property is to be added to an infoblock section using the Bitrix-API mechanism, the following code with variations must be used:

$arFields = Array(
"ENTITY_ID" => "IBLOCK_2_SECTION",
"FIELD_NAME" => "UF_TITLE",
"USER_TYPE_ID" => "string",
"EDIT_FORM_LABEL" => Array("en"=>"title")
);
$obUserField  = new CUserTypeEntity;
$obUserField->Add($arFields);

Fields to Nonstandard Objects and New Objects

Creating a Custom Field to Nonstandard Objects

Sometimes custom fields have to be created for the objects which do not support custom fields by default. In this case, a custom property for such object must be created independently.

Let us consider this situation by taking blog comments as an example. For example, each comment must have the Raiting property. We create a custom property of the required type in the administrative part (Control Panel >Settings > System settings > Custom fields) and complete all the fields. In the field Entity we indicate any name for the object. The most important thing is that the name must be unique. In our case, let us write BLOG_RATING. The following functions must be used to read and write values of custom properties:

function SetUserField ($entity_id, $value_id, $uf_id, $uf_value) //value write
{
return $GLOBALS["USER_FIELD_MANAGER"]->Update ($entity_id, $value_id,
Array ($uf_id => $uf_value));
}
 
function GetUserField ($entity_id, $value_id, $uf_id) //value read
{
$arUF = $GLOBALS["USER_FIELD_MANAGER"]->GetUserFields ($entity_id, $value_id);
return $arUF[$uf_id]["VALUE"];
}
 
// $entity_id - object name (in our case, "BLOG_RATING")
// $value_id - element identifier which property we save or obtain. In our case, it is a comment ID
// $uf_id - customer property name (in our case, UF_RATING)
// $uf_value - a value we save

Example:

SetUserField ("BLOG_RATING", $CommentID, "UF_RATING", $Rating);
echo "Comment’s rating: ".GetUserField ("BLOG_RATING", $CommentID, "UF_RATING");

Creating custom fields manually is not very convenient compared to the use of GetList functions for objects supporting custom properties by default. However, it permits you to use custom properties for arbitrary objects fast and easy.

Creating Own Object

It is possible to create any object and work with it as you like. Example:

$GLOBALS["USER_FIELD_MANAGER"]->Update("GRADEBOOK_RESULT", $ID, Array("UF_TEACHERS"=>$arValue));

$arUserFields = $GLOBALS["USER_FIELD_MANAGER"]->GetUserFields("GRADEBOOK_RESULT", $ID);

Gadgets

Gadget – is a special software component that is used in order to display specific data.

For more information about existing gadgets, their setup and controls, please refer to the manual Personal Dashboard and Gadgets

The Personal Dashboard (desktop) is used to display the gadgets. This one-page component permits the creation of a customizable desktop that uses gadgets. Gadgets are installed with the kernel module of the system. Developers can create own gadgets. The component will see them if they are located in the folder /bitrix/gadgets/. System gadgets are located in the subfolder/bitrix/.

Attention! Customization of system gadgets is strongly discouraged.

Gadget Structure

.description.php - description file;
.parameters.php - file with settings;
the file index.php contains an executable code which implements the gadget’s task;
language files in the folder /lang/.

Gadgets and components have a similar structure and purpose, however:

Gadgets do not use templates. HTML code is embedded in the file index.php, unlike the components where the representation and logic are separated.
Gadgets can “remember” settings for each user, unlike components which are only capable of displaying or not displaying information depending on the access rights.
Gadget settings are divided into 2 groups: general settings, for gadgets of the same type (e.g., for all News gadgets within one Desktop) and also settings of each specific gadget. General settings are set in the Desktop component. Individual settings are set in the context menu of each specific gadget.

In terms of mobility, gadgets are superior to components and are a very interesting tool both for developers and website users.

Related links:

How to create a custom gadget inside the Portal Dashboard: A Step-by-Step Guide (blog).

Project Testing

The checklist method is the most appropriate for website testing. The checklist contains the list of operations to be performed without fail.

A checklist is the list of factors, properties, parameters, aspects, components, criteria, or tasks specially structured in order to achieve set goals.

Testing covers a lot of important details which are repeated in every project. Programmers often say that they remember them, but experience shows that they do not, as they miss important aspects and tend to repeat the same errors over and over again. It is not in vain that good project managers close stages/releases only provided that checklist reports executed by designated employees are in place – from layout designers to system administrators.

Checklists are normally drawn up by experienced employees. Checklists are developed and improved according to the growth of the company’s knowledge base. The idea is simple: save time and money by preventing employees from involuntarily (and sometimes voluntarily) repeat the same errors twice or more.

We recommend that you also draw up your own checklist for project delivery. The contents of the list may differ, but, as community experience shows, such a list must contain the following points:

Search. If a search form is used on the website, it should be tested first. Make sure the search result links are not dead. If several infoblocks with dynamic information are used on the website, make search queries to find elements of different infoblocks separately and make sure the search result links work properly.
F5. In all forms where users are permitted to introduce any data (e.g., comments) make sure such data are not resent upon pressing the F5 button in the browser.
Users and access rights. Test the website in three conditions: as an unauthorized user, as an authorized user, and as an administrator. It often occurs that creating an infoblock as an administrator, required access rights are not set for the infoblock, and it remains accessible only to administrators.
Website map. The standard component Site map is not always suitable for this page. If the main information of the website consists of the catalog of goods (made using the module Information Blocks) it will be logical to display catalog sections and not just website sections.
Default templates. Make sure default templates are not used anywhere on the website. It may occur that, for example, if a user tries to recover their password, they will receive an email with a link to the website, and, following the link, see a sample Bitrix website instead of the website design familiar to the user.
Styles in visual editor. Using a visual editor, the content manager should see the text that resembles the text to be displayed on the website as close as possible. I.e. paragraphs, headers, etc. require their own font size, color, etc.
Dynamic information in the included areas. If an included area contains any dynamic information, it may become cached and it will most likely lead to an undesirable result. It is recommended not to use any dynamic information in the included area.
Backup copy, update. Update Bitrix to the current version, make a backup copy of the website, and save it to the local computer.
Cache. Make sure autocache is on. If not, activate it and repeat all testing from the beginning.
System kernel. Check kernel operation and make sure it is consistent with the original (the kernel was not customized); generate a report.
Unused files. Make sure the website contains no spare outdated contents and images.
Third party connections. Different partner programs are often connected to the website: banners, scripts, etc. for monetizing purposes. Make sure all of these functionalities are safe and not vulnerable (access to editing, kernel access, possibility of code injection or saving through connectable file module).

If you do not have sufficient experience to prepare your own checklist, use the standard tool Project Quality Control.

Project Quality Control

Web project is a complex product. It is different from traditional software because a website is the result of the interaction of three participants: a client, a partner, and a platform developer. Implementation quality problem occurs as a result of lack of understanding among these three parties.

The Project Quality Control tool is created to solve this problem. It permits solving the task of a transparent and flexible process of delivery of a web project to the client at the same time increasing the level of guaranteed result and reducing general risks.

Project Quality Control is a quality assurance tool to be used for a completed project before its delivery to the client.

Project Quality Control is:

Structured methodology to manage implementation quality;
System of tests for web developers, a set of recommendations for clients;
Consists of 26 mandatory tests and 39 optional;
Includes 12 automatic check.

Project Quality Control gives additional possibilities both to developers and clients:

For developers

Systematization of the testing procedure;
Improvement of Internet project quality using production systematization;
Formalization of relations with the client both at the delivery stage and at the support stage.

For clients

Risk reduction: the earlier a problem is found, the cheaper it can be removed;
Systematization of project acceptance and its launching into operation: the steps are defined, the details can be focused on;
Formalization and simplification of interaction with developer at the project support and development stage;
Reduction of expenses to obtain a quality result;
High production and safety of a web solution.

Tests are shown in the form of a tree organized according to stages of a standard implementation. However, you can run the tests in any order you want. There are mandatory and optional tests. Some tests can be automatized. Complex and routine checks are automatized.

Mandatory test has a critical importance for the quality of a web solution. It may be omitted, provided that the developer has left their comment on it. These tests are marked in black in the general list.

Optional test has no critical importance, but it is recommended for loaded, complex, and big projects. These tests are marked in gray in the general list.

Mandatory tests must be passed successfully in order to deliver a project according to the checklist. Optional tests are intended to significantly increase the quality of the solution and reduce risks.

Automatized test is a test for which the data are collected by the system. Anyway, the final decision is up to the developer. An automatized test can be re-executed.

Project Delivery

Project is delivered on the page Project Quality Control (Control Panel > Settings > Tools > Project Quality Control). Please refer to the blog for more details.

Use

There are various options available for using Project Quality Control.

Checklist Basic Testing

A partner/developer organizes the testing of a completed integration according to the checklist and acts as a tester. After that, such partner/developer submits to the client a success report available in the administrative interface in the section Control Panel > Settings > Tools > Project Quality Control where all the mandatory tests are passed successfully.

In-Depth Checklist Testing

The Developer and the client agree on the need to perform an in-depth checklist testing of quality of a highly loaded project. The partner acts as a tester and makes sure all (the majority of) checklist tests and the partner’s own tests are passed successfully. The client pays attention to the number of available tests and the number of tests passed successfully when viewing testing report in the report archive.

Internal Development

The client integrates the solution using their own development team. The client’s test team acts as a tester. One structural subdivision of the client delivers the project to another subdivision, and all the work is coordinated by the project manager.

Low-Risk Iterative Development

The partner provides the client with a service on the improvement of the functionality of an operating web project which was initially integrated using the Project Quality Control. The partner delivers the works by generating a test report. The client checks the test report and makes sure all the improvements to the web project are recorded in the report archive.

Modification of Tests

The system permits test modification according to the developer’s requirements using the standard Events mechanism of Bitrix Framework.

If necessary, developers can add their own tests and sections to the Project Quality Control.

Also, the tool can be adapted according to a specific task by creating own sections and tests. For example:

SEO optimization tests;
CodeStyle test;
Test to check the proper operation of billing under load;
And others.

How to Expand the Set of Standard Tests

First, own tests and their sections must be described. To do so, we create onCheckListGet, an event handler of the Kernel module. The event is called in the creator CCheckList with the argument $arCheckList of the following type:

array(2) {
  ["CATEGORIES"]=>
  array(10) {
    ["QDESIGN"]=>
    array(0) {
    }
    ["DESIGN"]=>
    array(1) {
      ["PARENT"]=>
      string(7) "QDESIGN"
    }
    ["MODEL"]=>
    array(1) {
      ["PARENT"]=>
      string(7) "QDESIGN"
    }
    ["STANDART"]=>
    array(1) {
      ["PARENT"]=>
      string(7) "QDESIGN"
    }
  }
  ["POINTS"]=>
  array(65) {
    ["QD0010"]=>
    array(2) {
      ["PARENT"]=>
      string(6) "DESIGN"
      ["REQUIRE"]=>
      string(1) "Y"
    }
    ["QD0020"]=>
    array(5) {
      ["REQUIRE"]=>
      string(1) "Y"
      ["PARENT"]=>
      string(6) "DESIGN"
      ["AUTO"]=>
      string(1) "Y"
      ["CLASS_NAME"]=>
      string(10) "CAutoCheck"
      ["METHOD_NAME"]=>
      string(14) "CheckTemplates"
    }
)

As you might have noticed, CATEGORIES contain the list of checklist sections which may be nested, and POINTS contain the tests proper.

The key of the CATEGORIES array is the section ID, and its value is the parameter array:

NAME - section name;
LINKS;
PARENT - parent section.

Example of section description:

$checkList['CATEGORIES']['ITC_QC'] = array(
    'NAME' => 'Corporate Quality Test ITConstruct',
    'LINKS' => ''
);

The key of the POINTS elements is the symbol identifier of the test, and the value is an array of the following parameters:

NAME - name of the test;
DESC - short description of the test (tab Description, block Description);
HOWTO - a text explaining what will be checked (tab Description, block How to perform the test);
LINKS - the same as sections;
PARENT - section ID, mandatory;
REQUIRE - indicator whether the test is mandatory (Y/N);
AUTO - "Y" if it is an autotest;
CLASS_NAME - test class name (for autotest);
METHOD_NAME - test method name (for autotest);
FILE_PATH - connection of a test file if such file is made as a separate script (for autotest). Path – from the website root DOCUMENT_ROOT;
PARAMS - an array of additional parameters submitted by the first argument when calling the autotest method.

Note: Such keys as NAME, DESC and LINKS can be left undefined in the test description. They depend on language, and if you provide for their strict definition directly in the handler it will make localization impossible.

It will be enough to connect own language file similar to the following:

$MESS["CL_ITC_QC_FAVICON_NAME"] = 'Availability of favicon'; 
$MESS["CL_ITC_QC_FAVICON_DESC"] = 'Check the availability of favicon – a website icon'; 
$MESS["CL_ITC_QC_FAVICON_LINKS"] ='';

Thus these language phrases will be substituted in the test fields NAME, DESC and LINKS with the code ITC_QC_FAVICON. It will also apply to HOWTO, but for now it can be defined only in the point description array.

Example:

$checkList['POINTS']['ITC_QC_FAVICON'] = array(
    'PARENT' => 'ITC_QC',
    'REQUIRE' => 'Y',
    'AUTO' => 'Y',
    'CLASS_NAME' => __CLASS__,
    'METHOD_NAME' => 'checkFavicon',
    'NAME' => 'Availability of favicon',
    'DESC' => 'Check the availability of favicon – a website icon reflected in the tab header and search systems',
    'HOWTO' => 'Home page of the website is checked for availability of the relevant meta tag. 
                If the tag is announced, the availability of icon is checked at the indicated URL. 
                If not, the availability of favicon.ico in the website root is checked',
    'LINKS' => 'links'
);

Event handler can return both changed $arCheckList and a new array with sections and tests. If a category/test with a certain ID already exists, it will not be replaced, i.e. you will not be able to adjust system tests.

Now a method for autotest must be announced:

$check = file_exists($_SERVER['DOCUMENT_ROOT'] . '/favicon.ico')

The check must return an array. Autotest may contain one or more steps. If the test contains several steps and current iteration is not final, the following array must be returned:

$arResult = array(
    'IN_PROGRESS' => 'Y',
    'PERCENT' => '42',
);

PERCENT serves only for the visualization of progress on the page and is not saved in any place for subsequent use. You have to save intermediate data for the identification of a step progress yourself – in a session, temporary file, and base (depending on data volume and other conditions).

If the test is completed, the status shall be notified with an array containing the following keys:

STATUS - test result; true if the test is passed, and something other if the test is a fail. It is checked as follows in the code:
if ($result['STATUS'] == "true")
MESSAGE - explanation of the result:
- PREVIEW - summary of the result;
- DETAIL - expanded explanation open in a pop-up window.

The ready method of the test for favicon.ico availability is as follows:

static public function checkFavicon($arParams)
{
    $arResult = array('STATUS' => 'F');
    $check = file_exists($_SERVER['DOCUMENT_ROOT'] . '/favicon.ico');

    if ($check === true) {
        $arResult = array(
            'STATUS' => true,
            'MESSAGE' => array(
                'PREVIEW' => 'Favicon is found - ' . '/favicon.ico',
            ),
        );
    } else {
        $arResult = array(
            'STATUS' => false,
            'MESSAGE' => array(
                'PREVIEW' => 'Favicon is not found',
                'DETAIL' => 'Failed to find favicon.ico',
            ),
        );
    }

    return $arResult;
}

Result

Test in the Project Quality Control:

Reference information about test:

Code

Code of the handler and entire tests:

AddEventHandler('main', 'OnCheckListGet', array('CItcCheckListTests', 'onCheckListGet'));

class CItcCheckListTests
{
    static public function onCheckListGet($arCheckList)
    {
        $checkList = array('CATEGORIES' => array(), 'POINTS' => array());

        $checkList['CATEGORIES']['ITC_QC'] = array(
            'NAME' => 'Corporate Quality Test ITConstruct',
            'LINKS' => ''
        );

        $checkList['POINTS']['ITC_QC_FAVICON'] = array(
            'PARENT' => 'ITC_QC',
            'REQUIRE' => 'Y',
            'AUTO' => 'Y',
            'CLASS_NAME' => __CLASS__,
            'METHOD_NAME' => 'checkFavicon',
            'NAME' => 'Availability of favicon',
            'DESC' => 'Check the availability of favicon – a website icon reflected in the tab header and search systems',
            'HOWTO' => 'Home page of the website is checked for availability of the relevant meta tag. 
                        If the tag is announced, the availability of icon is checked at the indicated URL. 
                        If not, the availability of favicon.ico in the website root is checked',
            'LINKS' => 'links'
        );

        $checkList['POINTS']['ITC_QC_DENY_DEV'] = array(
            'PARENT' => 'ITC_QC',
            'REQUIRE' => 'N',
            'AUTO' => 'N',
            'NAME' => 'Closing external access to dev server',
            'DESC' => 'Agree with the manager on closing access to internal server from the outside world',
            'HOWTO' => 'Ping from telephone after DNS update',
        );

        return $checkList;
    }

    static public function checkFavicon($arParams)
    {
        $arResult = array('STATUS' => 'F');
        $check = file_exists($_SERVER['DOCUMENT_ROOT'] . '/favicon.ico');

        if ($check === true) {
            $arResult = array(
                'STATUS' => true,
                'MESSAGE' => array(
                    'PREVIEW' => 'Favicon is found - ' . '/favicon.ico',
                ),
            );
        } else {
            $arResult = array(
                'STATUS' => false,
                'MESSAGE' => array(
                    'PREVIEW' => 'Favicon is not found',
                    'DETAIL' => 'Failed to find favicon.ico',
                ),
            );
        }

        return $arResult;
    }
}

Debugging Web Applications

var_dump – option

The simplest option consists in using the var_dump(): obtaining the composition of the variable, even if it is an object or an array. If we wrap up the output of this operator in <pre>, the result will be readable.

irePHP – option

There is a more sophisticated and eventually more convenient way to view the contents of variables. You will need the FireFox browser, FireBug extension, and FirePHP extension installed.

Download from this site the latest version of class to work with the FirePHP extension and connect this class to your motor:

Copy the file fb.php to the folder /bitrix/php_interface/
Add the following string to the file /bitrix/php_inteface/init.php:
```
require_once(‘FirePHPCore/fb.php’);
```

Now you can use logging in the FireBug console. In its simplest form, it is made as follows: fb($var), to set a label use: fb($var, ‘Label’);

Push and Pull module

Push & Pull

You can find more details on Pull and Pull module handling and operation in a corresponding [ds]section[/ds][di]Push notifications are small pop-up windows that appear on screens of mobile phones and desktops, informing on important events and updates.

Learn more...[/di] of Bitrix24 Self-hosted For Advanced Users learning course.

Mode of operation

Push & Pull module operates in two modes:

continuous connection to a special Queue server;
in server polling mode (60-20-10).

First mode is recommended, you'll get a significant degree of interactivity, but you will have to configure the Queue server or use a complete preconfigured Bitrix Virtual Appliance.

Second mode is used when first mode is unavailable. In this case, the module will query the server each 60 seconds and check, if data is available. When data is available, a hit occurs each 10 seconds. In case of no available data, a hit initially occurs after 20 seconds and then after each 60 seconds.

In both cases (queue server or server polling), module handling remains the same (except for a main channel).

Note: be advised that establishing connection with Push and Pull server requires ports 8893-8895 to be opened, they are necessary for push and pull server operation. If a situation with failed connection persists, provide SSH access to the server.

The API is split to PHP and JS portions. Principles for managing it are presented below.

PHP and JS

Connect the module to start the operation:

if (!CModule::IncludeModule('pull'))
   return false;

and register dependency to the PULL module. Register dependency handler:

RegisterModuleDependences("pull", "OnGetDependentModule", "your_module", "CYourModulePullSchema", "OnGetDependentModule" );

Then, create your own class. Class ID

class CYourModulePullSchema
{
    public static function OnGetDependentModule()
    {
        return Array(
            'MODULE_ID' => "your_module",
            'USE' => Array("PUBLIC_SECTION")
     );
     }
}

If your code works in public section, specify the following:

'USE' => Array("PUBLIC_SECTION")

When in addition, administrative section is required as well, specify the following:

'USE' => Array("PUBLIC_SECTION", "ADMIN_SECTION")

Before using the code, check the connection using the methods of a class CPullOptions.

Then, you can use API classes:

Server-side (PHP)
CPullStack	Sending the data.
CPullWatch	Sending data to subscribed users.
CPushManager	Sending push notifications.

JS methods

Client side (JS)
Event BX.addCustomEvent	"Trap" for Push & Pull commands.
BX.PULL.extendWatch	Subscription extension.

Example

Code for handling the above mentioned PHP methods

BX.addCustomEvent("onPullEvent", function(module_id,command,params) {
    if (module_id == "test" && command == 'check')
    {
        console.log('Work!');
    }
});

We subscribe to the command retrieval event (onPullEvent), and get module_id, command, params in the function; these parameters were specified when sending the command from PHP.

Example of component that handles the most complex subscription method BX.PULL.extendWatch.

Optimizing number of server queries

When project is located on a separate server, you need to configure path settings within the Push & Pull module, allowing modern browsers to access queue server directly.

Before this option became available in version 15.5.1, queries had to be proxied. (Query was sent to site server, because old browsers doesn't support direct AJAX queries to other domains, and then query is forwarded from there to a queue server via internal rules). This manoeuvre created load and excessive traffic.

Now all new browsers directly query servers. However, due to Bitrix24-related technical specifics of JS and server interaction, such browsers have to additionally execute a query to each OPTIONS connection. To avoid this, server configuration files must be updated.

Open the file bx/conf/im_subscrider.conf, and within the location location ^~ /bitrix/sub {, check is your have the condition as follows:

if ($arg_time) {
    push_stream_last_received_message_time "$arg_time";
}

If not, add such condition. It should look approximately as follows:

push_stream_subscriber            long-polling;
 push_stream_allowed_origins "*";
 push_stream_channels_path        $arg_CHANNEL_ID;
 push_stream_last_received_message_tag    $arg_tag;
 if ($arg_time) {
    push_stream_last_received_message_time "$arg_time";
 }

Next, use the method COption::SetOptionString:

COption::SetOptionString("pull", "nginx_headers", "N");

After that, when connecting, all users will generate a one server query less (it will occur not immediately, but during JS code updating at the clients side and page reload).

Push & Pull module for guests

You can launch Push & Pull module for guests, but you need to assign a session to a specific guest. Unique numeric ID is required as well: without it, the same channel address cannot be issued to a guest and personalized commands cannot be sent to this guest. Starting from Push & Pull module version 15.5.1 such guest option is now available.

Developer must implement guest identification methods and assign an internal numeric ID for such guest. For example, guest ID is defined as 1. To avoid confusing authorized and non-authorized users, this ID can be passed into the Push & Pull module with a minus sign:

$guestId = -1;

CModule::IncludeModule('pull');
CPullStack::AddByUser($guestId, Array(
   'module_id' => 'test',
   'command' => 'check',
   'params' => Array(),
));

The method that defines the ID must be implemented and executed in prolog, before initializing Push & Pull module. To do it, register the following dependency:

RegisterModuleDependences("main", "OnProlog", "main", "", "", 2, "local/scripts/pull_hit.php");

You need to specify your own defining logic and constant PULL_USER_ID within the specified file, used for correctly generated channel for a guest. Each guest must have its own unique ID!

$guestId = -1; // your function must return this digit, determining an ID for a guest define('PULL_USER_ID', $guestId);

After that, your guests can get Push & Pull commands equally to the authorized users.

For debugging purposes, you can use the following JS commands:

Command JS
BX.PULL.getDebugInfo();	This command displays P&P server connection status;
BX.PULL.capturePullEvent();	This command logs all incoming commands for this user;

Subscription to module events

Subscription

Starting from pull version 18.5.7 (for desktop computers) and mobile 18.5.10 (for mobile devices) developers can connect to Push & Pull module events using the method BX.PULL.subscribe. Directions on how to handle this method are provided below.

Connecting the library

Check if Push & Pull module is available for components used only in browser. Connect the library pull.client:

Indicate CoreJS pull.client dependency in description of your extension or call \Bitrix\Main\UI\Extension::load('pull.client');

Connect the required dependencies for your context within components used in a mobile application.

For the web page, indicate CoreJS mobile.pull.client dependency in the description for extension or call \Bitrix\Main\UI\Extension::load('mobile.pull.client');
For JaNative component, indicate the dependency pull/client/events in the file deps.php.
For Offline WebComponent indicate the dependency pull/client/events in the file config.php in "deps" section.

Within mobile extension, use the methods:
BX.PULL.subscribe(...),
BX.PULL.extendWatch(...),
BX.PULL.clearWatch(...),
BX.PULL.capturePullEvent(),
BX.PULL.getDebugInfo().

There are three formats for subscription, you can select a suitable format depending on your tasks.

Single command

Subscription for a single command:

BX.PULL.subscribe({
	type: BX.PullClient.SubscriptionType.Server,
	moduleId: 'im',
	command: 'messageChat',
	callback: function (params, extra, command) {
		console.warn('Receive message:', params.message.text)
	}.bind(this)
});

Where:
type - subscription type (Server, Client, Online) - may be skipped, Server type is set by default,
moduleId - module that sent the command
command - subscribed command
callback - handler function.

The following parameters for the method called upon event:

params - object, command parameters,
extra - object, additional data, such as module version, server name and time, time elapsed since sent command,
command - string, command name.

Method result is the function that can be used to unsubscribe from specified command in the future:

let unsubscibe = BX.PULL.subscribe({...}); // subscription
unsubscibe(); // unsubscription

Several commands

Subscription to multiple commands via router function:

BX.PULL.subscribe({
	type: BX.PullClient.SubscriptionType.Server,
	moduleId: 'im',
	callback: function (data) {
		if (data.command == 'messageAdd')
		{
			this.doSomething();
		}
	}.bind(this)
});

Where:
type - subscription type (Server, Client, Online) - may be skipped, Server type is set by default,
moduleId - module that sent the command
callback - handler function for all incoming commands.

The parameter data in the specified callback function will contain the following object:

{
	command: '...', // command name
	params: {...}, // command parameters
	extra: {...} // additional data, such as module version, server name and time, 
}

Method result is the function that can be used to unsubscribe from module commands in the future.

let unsubscibe = BX.PULL.subscribe({...}); // subscription
unsubscibe(); // отписка

Router class

Subscription via router class:

BX.PULL.subscribe(new CommandHandler(options));

You can pass the link to the objects you need in options, for example: for current context, to be able to call methods from your base class (if required) within handler class.

The router class itself looks as follows (please note: class is written in ES6; class applications in format ES5 is possible as well)

class CommandHandler
{
	constructor(options = {})
	{
	}

	getModuleId()
	{
		return 'im';
	}

	getSubscriptionType()
	{
		return BX.PullClient.SubscriptionType.Server;
	}
	
	getMap()
	{
		return {
			message: this.handleMessage.bind(this), 
			messageChat: this.handleMessageChat.bind(this),
			startCall: this.handleStartCall.bind(this),
		}; 
	}

	handleMessage(params, extra, command)
	{
		console.log('exec command - message', params);
	}

	handleMessageChat(params, extra, command)
	{
		console.log('exec command - messageChat', params);
	}

	handleStartCall(params, extra, command)
	{
		console.log('exec command - startCall', params);
	}
}

Method getModuleId() returns module ID, which commands must be processed by this class. (Required method).

Method getSubscriptionType() returns subscription type (Server, Client, Online). (Optional method, if not specified, sets as Server type)

Method getMap() returns map of command received from server and method that will process it.

Object formats

Possible object formats are returned by the function getMap().

The recommended function link format, i. e. IDE may quickly switch to function by just clicking on it:

{
	startCall: this.handleStartCall.bind(this),
}

The string format:

{
	startCall: 'handleStartCall',
}

In callback function format:

{
	startCall: function(params, extra, command) {
		console.log('exec command - startCall', params);
	}.bind(this),
}

Parameters for the method called upon triggered event are as follows:

params - object, command parameters
extra - object, additional data, such as module version, server name and time, time elapsed from sent command
command - string, command name

Simplified description variant

You can simplify class description by skipping getMap() method description. Then command processing methods must start from the word handle. After that, it must contain command name with first letter is the capital letter: for example, startCall command, and class must contain the method handleStartCall.

class CommandHandler
{
	constructor(options = {})
	{
	}

	getModuleId()
	{
		return 'im';
	}

	handleMessage(params, extra, command)
	{
		console.log('exec command - message', params);
	}

	handleMessageChat(params, extra, command)
	{
		console.log('exec command - messageChat', params);
	}

	handleStartCall(params, extra, command)
	{
		console.log('exec command - startCall', params);
	}
}

Method result is the function that can be used to unsubscribe from module commands in the future.

let unsubscibe = BX.PULL.subscribe({...}); // подписка
unsubscibe(); // отписка

Description hybrid variant

You can simultaneously use getMap() and methods governed by CommandHandler naming standards. Such variant will be suitable, if you want to make alias to the deprecated command format or if you are sending commands in the format that is impossible to describe in method name.

class CommandHandler
{
	constructor(options = {})
	{
	}

	getModuleId()
	{
		return 'im';
	}
	
	getMap()
	{
		return {
			'Application::send': this.handleApplicationSend.bind(this),
			messageChatAdd: this.handleMessageChat.bind(this) 
		}; 
	}

	handleMessage(params, extra, command)
	{
		console.log('exec command - message', params);
	}

	handleMessageChat(params, extra, command)
	{
		console.log('exec command - messageChat', params);
	}

	handleStartCall(params, extra, command)
	{
		console.log('exec command - startCall', params);
	}
	
	handleApplicationSend(params, extra, command)
	{
		console.log('exec command - applicationSend', params);
	}
}

Attention!. When command is described in getMap() and you have method for this command named by CommandHandler naming standards, then the priority will still be given to getMap().

Method result is the function that can be used to unsubscribe from module command in the future:

let unsubscibe = BX.PULL.subscribe({...}); // subscription
unsubscibe(); // unsubscription

Online Store customization

This chapter overviews Online Store customization.

Related links:

Products and CIBlockElement::GetList

CIBlockElement::GetList

Please, be advised, the method CIBlockElement::GetList of Information blocks module can handle product's data (if Commercial Catalog is available). This is detailed in the documentation and actively used in both public and administrative pages and scripts. However, due to system architectural specifics, this causes significant decrease of performance.

Let's make different calls of CIBlockElement::GetList and see, which queries will be executed at the end.

First, retrieve an empty selection of products from iblock with ID = 2:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Query, sent to the database:

SELECT  BE.ID as ID,BE.NAME as NAME,BE.IBLOCK_ID as IBLOCK_ID
FROM b_iblock B
INNER JOIN b_lang L ON B.LID=L.LID
INNER JOIN b_iblock_element BE ON BE.IBLOCK_ID = B.ID
WHERE 1=1 
   AND (
      ((((BE.IBLOCK_ID = '2'))))
   )
   AND (((BE.WF_STATUS_ID=1 AND BE.WF_PARENT_ELEMENT_ID IS NULL)))

Now, add filtering by the product availability to the fetch:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, 'CATALOG_AVAILABLE' => 'Y'),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

This leads to the query as follows:

SELECT  BE.ID as ID,BE.NAME as NAME,BE.IBLOCK_ID as IBLOCK_ID ,CAT_PR.QUANTITY as CATALOG_QUANTITY,
IF (CAT_PR.QUANTITY_TRACE = 'D', 'Y', CAT_PR.QUANTITY_TRACE) as CATALOG_QUANTITY_TRACE,
CAT_PR.QUANTITY_TRACE as CATALOG_QUANTITY_TRACE_ORIG, CAT_PR.WEIGHT as CATALOG_WEIGHT,
CAT_PR.VAT_ID as CATALOG_VAT_ID, CAT_PR.VAT_INCLUDED as CATALOG_VAT_INCLUDED,
IF (CAT_PR.CAN_BUY_ZERO = 'D', 'N', CAT_PR.CAN_BUY_ZERO) as CATALOG_CAN_BUY_ZERO,
CAT_PR.CAN_BUY_ZERO as CATALOG_CAN_BUY_ZERO_ORIG,
CAT_PR.PURCHASING_PRICE as CATALOG_PURCHASING_PRICE, CAT_PR.PURCHASING_CURRENCY as CATALOG_PURCHASING_CURRENCY,
CAT_PR.QUANTITY_RESERVED as CATALOG_QUANTITY_RESERVED,
IF (CAT_PR.SUBSCRIBE = 'D', 'Y', CAT_PR.SUBSCRIBE) as CATALOG_SUBSCRIBE, CAT_PR.SUBSCRIBE as CATALOG_SUBSCRIBE_ORIG,
CAT_PR.WIDTH as CATALOG_WIDTH, CAT_PR.LENGTH as CATALOG_LENGTH, CAT_PR.HEIGHT as CATALOG_HEIGHT,
CAT_PR.MEASURE as CATALOG_MEASURE, CAT_PR.TYPE as CATALOG_TYPE, CAT_PR.AVAILABLE as CATALOG_AVAILABLE,
CAT_PR.BUNDLE as CATALOG_BUNDLE, CAT_PR.PRICE_TYPE as CATALOG_PRICE_TYPE,
CAT_PR.RECUR_SCHEME_LENGTH as CATALOG_RECUR_SCHEME_LENGTH, CAT_PR.RECUR_SCHEME_TYPE as CATALOG_RECUR_SCHEME_TYPE,
CAT_PR.TRIAL_PRICE_ID as CATALOG_TRIAL_PRICE_ID, CAT_PR.WITHOUT_ORDER as CATALOG_WITHOUT_ORDER,
CAT_PR.SELECT_BEST_PRICE as CATALOG_SELECT_BEST_PRICE,
IF (CAT_PR.NEGATIVE_AMOUNT_TRACE = 'D', 'N', CAT_PR.NEGATIVE_AMOUNT_TRACE) as CATALOG_NEGATIVE_AMOUNT_TRACE,
CAT_PR.NEGATIVE_AMOUNT_TRACE as CATALOG_NEGATIVE_AMOUNT_TRACE_ORIG, CAT_VAT.RATE as CATALOG_VAT

   FROM b_iblock B
   INNER JOIN b_lang L ON B.LID=L.LID
   INNER JOIN b_iblock_element BE ON BE.IBLOCK_ID = B.ID

   left join b_catalog_product as CAT_PR on (CAT_PR.ID = BE.ID)
   left join b_catalog_iblock as CAT_IB on ((CAT_PR.VAT_ID IS NULL or CAT_PR.VAT_ID = 0) and CAT_IB.IBLOCK_ID = BE.IBLOCK_ID)
   left join b_catalog_vat as CAT_VAT on
         (CAT_VAT.ID = IF((CAT_PR.VAT_ID IS NULL OR CAT_PR.VAT_ID = 0), CAT_IB.VAT_ID, CAT_PR.VAT_ID))

   WHERE 1=1 
   AND (
      ((((BE.IBLOCK_ID = '2'))))
      AND ((((CAT_PR.AVAILABLE='Y'))))
   )
   AND (((BE.WF_STATUS_ID=1 AND BE.WF_PARENT_ELEMENT_ID IS NULL)))

This way, any query to product data (filtering, sorting, fetching a field) leads to join of three tables and selection of all product fields.

Remove filtration and select a one price type (price type ID - 1):

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID', 'CATALOG_CATALOG_GROUP_ID_1')
);

We'll see that situation became worse:

SELECT BE.ID as ID,BE.NAME as NAME,BE.IBLOCK_ID as IBLOCK_ID,
CAT_P1.CATALOG_GROUP_ID as CATALOG_GROUP_ID_1, CAT_P1.ID as CATALOG_PRICE_ID_1,
CAT_P1.PRICE as CATALOG_PRICE_1, CAT_P1.CURRENCY as CATALOG_CURRENCY_1,
CAT_P1.QUANTITY_FROM as CATALOG_QUANTITY_FROM_1, CAT_P1.QUANTITY_TO as CATALOG_QUANTITY_TO_1,
CAT_P1.EXTRA_ID as CATALOG_EXTRA_ID_1,
'Базовая цена' as CATALOG_GROUP_NAME_1, 'Y' as CATALOG_CAN_ACCESS_1, 'Y' as CATALOG_CAN_BUY_1,
CAT_PR.QUANTITY as CATALOG_QUANTITY, IF (CAT_PR.QUANTITY_TRACE = 'D', 'Y', CAT_PR.QUANTITY_TRACE) as CATALOG_QUANTITY_TRACE,
CAT_PR.QUANTITY_TRACE as CATALOG_QUANTITY_TRACE_ORIG, CAT_PR.WEIGHT as CATALOG_WEIGHT,
CAT_PR.VAT_ID as CATALOG_VAT_ID, CAT_PR.VAT_INCLUDED as CATALOG_VAT_INCLUDED,
IF (CAT_PR.CAN_BUY_ZERO = 'D', 'N', CAT_PR.CAN_BUY_ZERO) as CATALOG_CAN_BUY_ZERO,
CAT_PR.CAN_BUY_ZERO as CATALOG_CAN_BUY_ZERO_ORIG, CAT_PR.PURCHASING_PRICE as CATALOG_PURCHASING_PRICE,
CAT_PR.PURCHASING_CURRENCY as CATALOG_PURCHASING_CURRENCY, CAT_PR.QUANTITY_RESERVED as CATALOG_QUANTITY_RESERVED,
IF (CAT_PR.SUBSCRIBE = 'D', 'Y', CAT_PR.SUBSCRIBE) as CATALOG_SUBSCRIBE, CAT_PR.SUBSCRIBE as CATALOG_SUBSCRIBE_ORIG,
CAT_PR.WIDTH as CATALOG_WIDTH, CAT_PR.LENGTH as CATALOG_LENGTH, CAT_PR.HEIGHT as CATALOG_HEIGHT,
CAT_PR.MEASURE as CATALOG_MEASURE, CAT_PR.TYPE as CATALOG_TYPE, CAT_PR.AVAILABLE as CATALOG_AVAILABLE,
CAT_PR.BUNDLE as CATALOG_BUNDLE, CAT_PR.PRICE_TYPE as CATALOG_PRICE_TYPE,
CAT_PR.RECUR_SCHEME_LENGTH as CATALOG_RECUR_SCHEME_LENGTH, CAT_PR.RECUR_SCHEME_TYPE as CATALOG_RECUR_SCHEME_TYPE,
CAT_PR.TRIAL_PRICE_ID as CATALOG_TRIAL_PRICE_ID, CAT_PR.WITHOUT_ORDER as CATALOG_WITHOUT_ORDER,
CAT_PR.SELECT_BEST_PRICE as CATALOG_SELECT_BEST_PRICE,
IF (CAT_PR.NEGATIVE_AMOUNT_TRACE = 'D', 'N', CAT_PR.NEGATIVE_AMOUNT_TRACE) as CATALOG_NEGATIVE_AMOUNT_TRACE,
CAT_PR.NEGATIVE_AMOUNT_TRACE as CATALOG_NEGATIVE_AMOUNT_TRACE_ORIG, CAT_VAT.RATE as CATALOG_VAT
FR OM b_iblock B
INNER JOIN b_lang L ON B.LID=L.LID
INNER JOIN b_iblock_element BE ON BE.IBLOCK_ID = B.ID
left join b_catalog_price as CAT_P1 on (CAT_P1.PRODUCT_ID = BE.ID and CAT_P1.CATALOG_GROUP_ID = 1)
left join b_catalog_product as CAT_PR on (CAT_PR.ID = BE.ID)
left join b_catalog_iblock as CAT_IB on ((CAT_PR.VAT_ID IS NULL or CAT_PR.VAT_ID = 0) and CAT_IB.IBLOCK_ID = BE.IBLOCK_ID)
left join b_catalog_vat as CAT_VAT on (CAT_VAT.ID = IF((CAT_PR.VAT_ID IS NULL OR CAT_PR.VAT_ID = 0), CAT_IB.VAT_ID, CAT_PR.VAT_ID))
WH ERE 1=1
   AND (
      ((((BE.IBLOCK_ID = '2'))))
   )
   AND (((BE.WF_STATUS_ID=1 AND BE.WF_PARENT_ELEMENT_ID IS NULL)))

If we attempt to additionally retrieve warehouse data as well, the situation will be similar.

Let's highlight interim results:

You must strictly avoid retrieving prices and available warehouse stock in CIBlockElement::GetList (specifically, if sorting is used, no matter by which fields). This data must be retrieved using separate API calls. By the way, this can be done in standard components starting from version 17.0.
Filtering and sorting by product fields, prices, warehouses remains. Querying product fields by keys CATALOG_ gives an extra join of three tables. Querying N types of prices or warehouses - join N+3 tables. In addition to increased query time, you can get an error MySql "Too many tables; MySQL can only use 61 tables in a join".

Before the release of catalog 18.6.100 + iblock 18.6.200, all of the abovementioned is related to standard components and Iblock module admin lists (specifically, in the joint view mode for sections and elements, view the details below). New product handling features become available after the these updates are released in CIBlockElement::GetList.

Note: previously, we recommended to avoid using joint view mode for all large iblocks due to significant memory consumption. WIth the release of Information blocks module version 18.5.5, this issue has been resolved: this mode allows to display an iblock with 100 thousands elements in the administrative section (memory consumption is reduced approx. 2o times).

Startng from Catalog version 18.6.100 + iblock 18.6.200

Starting from iblock version 18.6.200, method keys are updated. You can filter, sort, get by all keys.

Product fields

Catalog 20.0.200 module version introduces product fields

Now calling method with filtration by availability looks as follows:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y'),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

and the query contains only requested data and only a single join:

   SELECT  BE.ID as ID,BE.NAME as NAME,BE.IBLOCK_ID as IBLOCK_ID

   FROM b_iblock B
   INNER JOIN b_lang L ON B.LID=L.LID
   INNER JOIN b_iblock_element BE ON BE.IBLOCK_ID = B.ID
   left join b_catalog_product as PRD on (PRD.ID = BE.ID)

   WHERE 1=1 
   AND (
      ((((BE.IBLOCK_ID = '2'))))
      AND ((((PRD.AVAILABLE='Y'))))
   )
   AND (((BE.WF_STATUS_ID=1 AND BE.WF_PARENT_ELEMENT_ID IS NULL)))

Retrieve selection of sizes and weight of available standard products:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID', 'WEIGHT', 'WIDTH', 'HEIGHT', 'LENGTH')
);

Query is as follows:

   SELECT  BE.ID as ID,BE.NAME as NAME,BE.IBLOCK_ID as IBLOCK_ID ,
   PRD.WEIGHT as WEIGHT, PRD.WIDTH as WIDTH, PRD.HEIGHT as HEIGHT, PRD.LENGTH as LENGTH

   FROM b_iblock B
   INNER JOIN b_lang L ON B.LID=L.LID
   INNER JOIN b_iblock_element BE ON BE.IBLOCK_ID = B.ID
   left join b_catalog_product as PRD on (PRD.ID = BE.ID)

   WHERE 1=1 
   AND (
      ((((BE.IBLOCK_ID = '2'))))
      AND ((((PRD.AVAILABLE='Y'))))
      AND ((((PRD.TYPE = '1'))))
   )
   AND (((BE.WF_STATUS_ID=1 AND BE.WF_PARENT_ELEMENT_ID IS NULL)))

Price fields (without binding to a specific price type)

Price fields (With indicated price type)

Warehouse fields

Examples

Filtering by price of any type:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1, '>PRICE' => 500),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID', 'WEIGHT', 'WIDTH', 'HEIGHT', 'LENGTH')
);

Filtering by price type with code 1 (usually it's a base price):

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1, '>PRICE' => 500, '=PRICE_TYPE' => 1),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID', 'WEIGHT', 'WIDTH', 'HEIGHT', 'LENGTH')
);

Or in variant as follows:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1, '>PRICE_1' => 500),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID', 'WEIGHT', 'WIDTH', 'HEIGHT', 'LENGTH')
);

Now you can set previously unavailable filters. Select all products with prices of any type from 500 to 1000:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1, '>=PRICE' => 500, '<=PRICE' => 1000),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Or only price types with code 1,4,5:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1, '>=PRICE' => 500, '<=PRICE' => 1000, '@PRICE_TYPE' => [1,4,5]),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Select all products with prices in any currency, equivalent to range from 100 to 200 USD:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '=AVAILABLE' => 'Y', '=TYPE' => 1, '>=PRICE' => 100, '<=PRICE' => 200, 'CURRENCY_FOR_SCALE' => 'USD'),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Select products with quantity stored at any warehouse not ore than 3:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '<=STORE_AMOUNT' => 3),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Select products, stored at 17th warehouse from 5 to 7:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '<=STORE_AMOUNT' => 7, '>=STORE_AMOUNT' => 5, 'STORE_NUMBER' => 17),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Or as follows:

$iterator = \CIBlockElement::GetList(
   array(),
   array('IBLOCK_ID' => 2, '<=STORE_AMOUNT_17' => 7, '>=STORE_AMOUNT_17' => 5),
   false,
   false,
   array('ID', 'NAME', 'IBLOCK_ID')
);

Product filtering by availability at specific warehouses:

if(!empty($arParams['STORES'])){ 
    $GLOBALS[$arParams['FILTER_NAME']]['@STORE_NUMBER'] => $arParams['STORES'];
   $GLOBALS[$arParams['FILTER_NAME']]['>STORE_AMOUNT'] = 0;
}

Other example of product filtering by availability at specific warehouses:

if(!empty($arParams['STORES'])){

$storesFilter = [
                     'LOGIC'=>'OR'
            ];
            foreach ($arParams['STORES'] as $store_id){
                $storesFilter[] = ['STORE_NUMBER' => intval($store_id),'>STORE_AMOUNT'=>0];
            }

  $GLOBALS[$arParams['FILTER_NAME']][] = $storesFilter;
        }

Conclusion

Upon installing updates catalog 18.6.100 + iblock 18.6.200, it's strongly recommended to transition your components and scripts to new keys. Performance increase is directly proportional to the number of products in catalog. Accordingly, test section with 1,5 thousand of products resulted in execution speed increase was 30%. Standard components ([comp include_62980]catalog.section[/comp], [comp include_62981]catalog.element[/comp], [comp include_62986]catalog.top[/comp]), as well as all descendant components \Bitrix\Iblock\Component\Base are moved to new filters.

Types of order custom properties

Custom property types

System have the following property types: String, Integer, Yes/No, Enumeration, File, Date and Location. However, you can add your own custom property types and individually determine their external appearance. This way, a value (that you have programmed) will be requested from the buyer during order checkout. To do that, you need to execute the following actions:

Inherit custom type class:

class MyType extends \Bitrix\Sale\Internals\Input\Base
{
	protected static function getEditHtmlSingle($name, array $input, $value){...} 
	protected static function getErrorSingle(array $input, $value){...}
	static function getSettings(array $input, $reload){...}
}

Connect property type to the system: type is connected on the event registerInputTypes:

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
	'sale',
	'registerInputTypes',
	'myFunction'
);

Register your own custom property type in the event handler using the method Manager::register, containing your handler class and name of your type:

public function myFunction(\Bitrix\Main\Event $event)
{
	\Bitrix\Sale\Internals\Input\Manager::register(
		"myType",
		array(
			'CLASS' => '\MyNamespace\MyType',
			'NAME' => 'My type',
		)	
	);
}

[ds]Describe JS class[/ds][di]Sometimes when developing a component, its template must be outfitted with JS functionality, events and other features.

Learn more...[/di] operate and [ds]connect[/ds][di]Before writing JS code, there is an issue: where to store it?

Learn more...[/di] the property:

BX.Sale.Input.Manager.MyType = MyType;
BX.Sale.Input.Utils.extend(MyType, BX.Sale.Input.BaseInput);
BX.Sale.Input.Manager.register('myType', MyType);

function MyType(name, settings, value, publicO)
{
    MyType.__super__.constructor.call(this, name, settings, value, publicO);
}

MyType.prototype.createEditorSingle = function (name, value)
{
    ...
};

MyType.prototype.afterEditorSingleInsert = function (item)
{
    ...
};

MyType.prototype.setValueSingle = function (item, value)
{
    ...
};

MyType.prototype.getValueSingle = function (item)
{
    ...
};

MyType.prototype.setDisabledSingle = function (item, disabled)
{
    ...
};

MyType.prototype.addEventSingle = function (item, name, action)
{
    ...
};

Important! myType type name must be unique within the complete system.

Now, an online store manager will be able to create a new order property with property type you created available among standard types.

Attention! You have to individually enable support for newly created custom property in the order checkout component sale.order.ajax.

Example of created String property type

Inherit the class, connect property type to the system and register it:

class StringInput extends \Bitrix\Sale\Internals\Input\Base 
{
	public static function getEditHtmlSingle($name, array $input, $value)
	{
		if ($input['MULTILINE'] == 'Y')
		{
			$attributes = static::extractAttributes($input,
				array('DISABLED'=>'', 'READONLY'=>'', 'AUTOFOCUS'=>'', 'REQUIRED'=>''),
				array('FORM'=>1, 'MAXLENGTH'=>1, 'PLACEHOLDER'=>1, 'DIRNAME'=>1, 'ROWS'=>1, 'COLS'=>1, 'WRAP'=>1));

			return '<textarea name="'.$name.'"'.$attributes.'>'.htmlspecialcharsbx($value).'</textarea>';
		}
		else
		{
			$attributes = static::extractAttributes($input,
				array('DISABLED'=>'', 'READONLY'=>'', 'AUTOFOCUS'=>'', 'REQUIRED'=>'', 'AUTOCOMPLETE'=>'on'),
				array('FORM'=>1, 'MAXLENGTH'=>1, 'PLACEHOLDER'=>1, 'DIRNAME'=>1, 'SIZE'=>1, 'LIST'=>1, 'PATTERN'=>1));

			return '<input type="text" name="'.$name.'" value="'.htmlspecialcharsbx($value).'"'.$attributes.'>';
		}
	}

	/**
	 * @param $name
	 * @param array $input
	 * @param $value
	 * @return string
	 */
	public static function getFilterEditHtml($name, array $input, $value)
	{
		return static::getEditHtmlSingle($name, $input, $value);
	}

	public static function getErrorSingle(array $input, $value)
	{
		$errors = array();

		$value = trim($value);

		if ($input['MINLENGTH'] && strlen($value) < $input['MINLENGTH'])
			$errors['MINLENGTH'] = Loc::getMessage('INPUT_STRING_MINLENGTH_ERROR', array("#NUM#" => $input['MINLENGTH']));

		if ($input['MAXLENGTH'] && strlen($value) > $input['MAXLENGTH'])
			$errors['MAXLENGTH'] = Loc::getMessage('INPUT_STRING_MAXLENGTH_ERROR', array("#NUM#" => $input['MAXLENGTH']));

		if ($input['PATTERN'] && !preg_match($input['PATTERN'], $value))
			$errors['PATTERN'] = Loc::getMessage('INPUT_STRING_PATTERN_ERROR');

		return $errors;
	}

	static function getSettings(array $input, $reload)
	{
		$settings = array(
			'MINLENGTH' => array('TYPE' => 'NUMBER', 'LABEL' => Loc::getMessage('INPUT_STRING_MINLENGTH'), 'MIN' => 0, 'STEP' => 1),
			'MAXLENGTH' => array('TYPE' => 'NUMBER', 'LABEL' => Loc::getMessage('INPUT_STRING_MAXLENGTH'), 'MIN' => 0, 'STEP' => 1),
			'PATTERN'   => array('TYPE' => 'STRING', 'LABEL' => Loc::getMessage('INPUT_STRING_PATTERN'  )),
			'MULTILINE' => array('TYPE' => 'Y/N'   , 'LABEL' => Loc::getMessage('INPUT_STRING_MULTILINE'), 'ONCLICK' => $reload),
		);

		if ($input['MULTILINE'] == 'Y')
		{
			$settings['COLS'] = array('TYPE' => 'NUMBER', 'LABEL' => Loc::getMessage('INPUT_STRING_SIZE'), 'MIN' => 0, 'STEP' => 1);
			$settings['ROWS'] = array('TYPE' => 'NUMBER', 'LABEL' => Loc::getMessage('INPUT_STRING_ROWS'), 'MIN' => 0, 'STEP' => 1);
		}
		else
		{
			$settings['SIZE'] = array('TYPE' => 'NUMBER', 'LABEL' => Loc::getMessage('INPUT_STRING_SIZE'), 'MIN' => 0, 'STEP' => 1);
		}

		return $settings;
	}
}

\Bitrix\Sale\Internals\Input\Manager::register('STRING', array(
	'CLASS' => '\StringInput',
	'NAME' => \Bitrix\Main\Localization\Loc::getMessage('INPUT_STRING'),
));

Describe and connect JS class:

BX.Sale.Input.Manager.StringInput = StringInput;
BX.Sale.Input.Utils.extend(StringInput, BX.Sale.Input.BaseInput);
BX.Sale.Input.Manager.register('STRING', StringInput);

function StringInput(name, settings, value, publicO)
{
	StringInput.__super__.constructor.call(this, name, settings, value, publicO);
}

StringInput.prototype.createEditorSingle = function (name, value)
{
	var s, size = 5, settings = this.settings;

	if ((s = settings.MIN) && s.toString().length > size)
		size = s;

	if ((s = settings.MAX) && s.toString().length > size)
		size = s;

	if ((s = settings.STEP) && s.toString().length > size)
		size = s;

	var element = document.createElement('input');
	element.type  = 'text';
	element.name  = name;
	element.value = value;
	element.size  = size;

	BX.Sale.Input.Utils.applyBooleanAttributesTo(element, settings, BX.Sale.Input.Utils.globalBooleanAttributes, {DISABLED:'', READONLY:'', AUTOFOCUS:'', REQUIRED:'', AUTOCOMPLETE:'on'});
	BX.Sale.Input.Utils.applyValueAttributesTo(element, settings, BX.Sale.Input.Utils.globalValueAttributes, {FORM:1, LIST:1, PLACEHOLDER:1});
	this.applyEventAttributesTo(element, settings, BX.Sale.Input.Utils.globalEventAttributes);

	return [element];
};

StringInput.prototype.afterEditorSingleInsert = function (item)
{
	item[0].focus();
};

StringInput.prototype.setValueSingle = function (item, value)
{
	item[0].value = value;
};

StringInput.prototype.getValueSingle = function (item)
{
	var element = item[0];
	return element.disabled ? null : element.value;
};

StringInput.prototype.setDisabledSingle = function (item, disabled)
{
	item[0].disabled = disabled;
};

StringInput.prototype.addEventSingle = function (item, name, action)
{
	BX.Sale.Input.Utils.addEventTo(item[0], name, action);
};

Adding restrictions

You can supplement the standard set of restrictions with your own. To do that, use the restriction initializing events as you see fit:

for delivery services onSaleDeliveryRestrictionsClassNamesBuildList:

Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'onSaleDeliveryRestrictionsClassNamesBuildList',
    'myDeliveryFunction'
);

for payment systems onSalePaySystemRestrictionsClassNamesBuildList:

Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'onSalePaySystemRestrictionsClassNamesBuildList',
    'myPayFunction'
);

for cash registers onSaleCashboxRestrictionsClassNamesBuildList:

Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'onSaleCashboxRestrictionsClassNamesBuildList',
    'myCashboxFunction'
);

for companies onSaleCompanyRulesClassNamesBuildList:

Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'onSaleCompanyRulesClassNamesBuildList',
    'myCompanyFunction'
);

Accordingly, you need to return your restriction class in the event handlers:

for delivery services:

function myDeliveryFunction()
{
    return new \Bitrix\Main\EventResult(
        \Bitrix\Main\EventResult::SUCCESS,
        array(
            '\MyDeliveryRestriction' => '/bitrix/php_interface/include/mydelrestriction.php',
        )
    );
}

for payment systems:

function myPayFunction()
{
    return new \Bitrix\Main\EventResult(
        \Bitrix\Main\EventResult::SUCCESS,
        array(
            '\MyPayRestriction' => '/bitrix/php_interface/include/mypayrestriction.php',
        )
    );
}

for cash registers:

function myCashboxFunction()
{
    return new \Bitrix\Main\EventResult(
        \Bitrix\Main\EventResult::SUCCESS,
        array(
            '\MyCashboxRestriction' => '/bitrix/php_interface/include/mycashboxrestriction.php',
        )
    );
}

for companies:

function myCompanyFunction()
{
    return new \Bitrix\Main\EventResult(
        \Bitrix\Main\EventResult::SUCCESS,
        array(
            '\MyCompanyRestriction' => '/bitrix/php_interface/include/mycompanyrestriction.php',
        )
    );
}

Next, by describing the restriction, you can introduce any rules of your choice. A restriction for delivery service availability on lunar days only is introduced in the example below:

use Bitrix\Sale\Delivery\Restrictions;
use Bitrix\Sale\Internals\Entity;

class MyDeliveryRestriction extends Restrictions\Base
{
    public static function getClassTitle()
    {
        return 'on lunar days';
    }

    public static function getClassDescription()
    {
        return 'delivery will be performed only within the indicated range of lunar days';
    }

public static function check($moonday, array $restrictionParams, $deliveryId = 0)
{
    if ($moonday < $restrictionParams['MIN_MOONDAY']
        || $moonday > $restrictionParams['MAX_MOONDAY'])
        return false;

    return true;
}
protected static function extractParams(Entity $shipment)
{
    $json = file_get_contents('http://moon-today.com/api/index.php?get=moonday');
    $res = json_decode($json, true);
    return !empty($res['moonday']) ? intval($res['moonday']) : 0;
}
public static function getParamsStructure($entityId = 0)
    {
        return array(
            "MIN_MOONDAY" => array(
                'TYPE' => 'NUMBER',
                'DEFAULT' => "1",
                'LABEL' => 'Minimum days'
            ),
            "MAX_MOONDAY" => array(
                'TYPE' => 'NUMBER',
                'DEFAULT' => "30",
                'LABEL' => 'Maximum days'
            )
        );
    }
}

Company user fields

You can supplement a standard set of company rules with your own rules. To do it, you need to use the event onSaleCompanyRulesClassNamesBuildList:

Bitrix\Main\EventManager::getInstance()->addEventHandler(
        "sale",
        "onSaleCompanyRulesClassNamesBuildList", 
        "myCompanyRulesFunction"
);

You need to return your class of rules in the event handler:

function myCompanyRulesFunction()
{
    return new \Bitrix\Main\EventResult(
        \Bitrix\Main\EventResult::SUCCESS,
        array(
            '\MyCompanyRules' => '/bitrix/php_interface/include/mycompanyrules.php',
        )
    );
}

By describing the rule itself, you can define your own conditions. For example, the rule for auto-assigning a company depending on lunar days is provided in the example below:

use Bitrix\Sale\Services\Base;
use Bitrix\Sale\Internals\Entity;

class MyCompanyRules extends Base\Restriction
{
    public static function getClassTitle()
    {
        return 'by lunar days';
    }

    public static function getClassDescription()
    {
        return 'company will be used only in the specified range of lunar days';
    }

public static function check($params, array $restrictionParams, $serviceId = 0)
{
    if ($params < $restrictionParams['MIN_MOONDAY']
        || $params > $restrictionParams['MAX_MOONDAY'])
        return false;

    return true;
}
protected static function extractParams(Entity $entity)
{
    $json = file_get_contents('http://moon-today.com/api/index.php?get=moonday');
    $res = json_decode($json, true);
    return !empty($res['moonday']) ? intval($res['moonday']) : 0;
}
public static function getParamsStructure($entityId = 0)
    {
        return array(
            "MIN_MOONDAY" => array(
                'TYPE' => 'NUMBER',
                'DEFAULT' => "1",
                'LABEL' => 'Minimum days'
            ),
            "MAX_MOONDAY" => array(
                'TYPE' => 'NUMBER',
                'DEFAULT' => "30",
                'LABEL' => 'Maximum days'
            )
        );
    }
}

Customizing types of additional services

You can add extra delivery services to the already available services, rendered to customers when delivering products. This way, for example, you can ask a customer, if a gift wrapping is required for this customer's order.

In case, you are not satisfied with standard types of additional services, you can add your own types of services. Use the event onSaleDeliveryExtraServicesClassNamesBuildList that registers custom types of services:

EventManager::getInstance()->addEventHandler(
	'sale',
	'onSaleDeliveryExtraServicesClassNamesBuildList',
	'myFunction'
);

class MyService extends \Bitrix\Sale\Delivery\ExtraServices\Base
{
	public function getClassTitle()
	{
			return "My service";
	}
	...
}

Event handler must return list of your classes for additional service types and paths to them:

public static function myFunction(Main\Event $event)
{
	return new Main\EventResult(
		Main\EventResult::SUCCESS,
		array(
			'MyService' = > 'folder/myservice.php',
		)
	);
}

As the result, your class becomes operational and implements interface for services according to your settings.

Class is inherited from Base, located in the directory: /bitrix/modules/sale/lib/delivery/extra_services.
Also, your can find examples of standard types of services.

Delivery services customization

Customization

System mechanisms allow customizing and adding your own delivery services. In this aspect, e-store in core D7 such services are represented by classes. Subsequently, you can use inheritance mechanism. To create your own delivery service you have to create a class - descendant of the base class \Bitrix\Sale\Delivery\Services\Base .

Example of inheriting for delivery services:

class SimpleHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    protected static $isCalculatePriceImmediately = true;
	protected static $whetherAdminExtraServiceShow = true;
	
	/**
	* @param array $initParams
	* @throws \Bitrix\Main\ArgumentTypeException
	*/
    
    public function __construct(array $initParams)
    {
        parent::__construct($initParams);
    }
}

System will search for handler in the following directories:

self::$handlersDirectories = array(
	'LOCAL' = > '/local/php_interface/include/sale_delivery',
	'CUSTOM' = > '/bitrix/php_interface/include/sale_delivery',
	'SYSTEM' = > '/bitrix/modules/sale/handlers/delivery'
)

You can limit the use of delivery service by specific parameters. For example, by limit by maximum weight or size. Apply standard restrictions for this purpose. When you need something specific, create your own types of restrictions.

Additionally, you can use the the event onSaleDeliveryServiceCalculate available for delivery services that can modify delivery price calculation (i. e. you can increase delivery price per 100 units):

EventManager::getInstance()->addEventHandler(
    'sale',
    'onSaleDeliveryServiceCalculate',
    'myCalc'
);

function myCalc(\Bitrix\Main\Event $event)
{
	/** @var Delivery\CalculationResult $baseResult */
	$baseResult = $event->getParameter('RESULT');
	$shipment = $event->getParameter('SHIPMENT');
	
	$price = $baseResult->getDeliveryPrice() + 100;
	$baseResult->setDeliveryPrice($price);
	
	$event->addResult(
		new EventResult(
			EventResult::SUCCESS, array('RESULT' => $baseResult)
		)
	);
}

Important! You need to consider that the site can have both both UTF-8 and CP-1251 encodings. When data exchange is performed with a delivery service, you need to correctly modify the encoding when sending and receiving data. The following method will be helpful for this purpose: \Bitrix\Main\Text\Encoding::convertEncoding().

Note: you can find more details on handling delivery services REST in a [ds]separate chapter[/ds][di] This section overviews delivery service REST principles:

Delivery service handler settings;
Delivery service settings;
Additional service setup for delivery service;
Handling shipment properties;
Standard scenario for delivery services REST: handling delivery in sales center.
Starting point for manager can be payment feature ("Accept
payment in deal") or creating a delivery activity.

Learn more...[/di].

Examples of delivery services

Take a look at the delivery service examples below:

\Sale\Handlers\Delivery\SimpleHandler (/bitrix/modules/sale/handlers/delivery/simple/handler.php) - simplest example of handlers.
\Sale\Handlers\Delivery\SpsrHandler (/bitrix/modules/sale/handlers/delivery/spsr/handler.php) - a little more complex variant with all features of current architecture fully employed.

There is an available mechanism of automatic tracking of dispatch IDs (tracking number) (i. e., as implemented for delivery service Spsr: \Sale\Handlers\Delivery\SpsrTracking).

Recommendations

It's recommended to use an integrated class \Bitrix\Main\Web\HttpClient for querying delivery services instead of third-party extensions. Optimal exchange format - json, due to the option of integrated class \Bitrix\Main\Web\Json.

Often, during data exchange with delivery services, you must send locations IDs. Matching online store location IDs with delivery service IDs - is a non-trivial task. For example, you can use \Sale\Handlers\Delivery\Spsr\Location::mapStepless().

To void creating redundant queries to delivery service, slowing down site operation, it's preferable to cache information, received from delivery services. However, you have to do it accurately to prevent undesirable side effects. Use \Sale\Handlers\Delivery\Spsr\Cache.

In case of errors, it's recommended to maintain a debugging log with records of events, associated with received information from delivery services. For this purpose, use the class \CEventLog.

Payment system customization

System features allow customizing and adding you own custom payment systems, represented in core D7 as classes. Accordingly, you can use mechanism of inheriting:

when you need to create payment system similar to the one included into the product distribution package, you can implement inheriting from the corresponding class;
when you need to write a payment system from zero, you can inherit from base class Bitrix\Sale\PaySystem\BaseServiceHandler or \Bitrix\Sale\PaySystem\ServiceHandler

Most frequently, the class \Bitrix\Sale\PaySystem\ServiceHandler (descendant of class Bitrix\Sale\PaySystem\BaseServiceHandler) is used for customization. The class \Bitrix\Sale\PaySystem\ServiceHandler supports methods that will enable processing response from payment system.

You can add your own payment system handler to the namespace \Sale\Handlers\PaySystem\, otherwise it won't be connected.

Example of inheriting payment systems:

class YahooHandler extends ServiceHandler implements IReturn, IHold
{
    public static function initiatePay(Payment $payment)
    {
        $params = array('URL' = > $this->getUrl($payment, 'pay'));
        $this->setExtraParams($params);
        
        return $this->showTemplate($payment, "template");
    }

    public static function getIndicativeFields()
    {
        return array('BX_HANDLER' => 'Yahoo');
    }
}

System will search for handler in the following directories:

protected static $handlerDirectories = array(
	'CUSTOM' =>  path is sourced from the option path2user_ps_files (by default "/php_interface/include/sale_payment/")
	'LOCAL' => '/local/php_interface/include/sale_payment/',
	'SYSTEM' => '/bitrix/modules/sale/handlers/paysystem/'
	'SYSTEM_OLD' => '/bitrix/modules/sale/payment/'
)

Important!

If you don't change the name when copying (keep /bitrix/php_interface/include/sale_payment/yahoo), you can use only a custom handler in the payment system settings. System handler (that was copied) won't be available: now custom handler replaces the system handler.

This leads to the following: when copying a system handler to its namespace, it's name changes and the class must be renamed. For example, if we have copied a system 'yahoo' to /bitrix/php_interface/include/sale_payment/yahoonew, the inheriting in the file handler.php must looks as follows:

class YahooNewHandler extends PaySystem\BaseServiceHandler

Attention! Handler folder name cannot contain the word "handler", because it's used in the class name inside the handler. The provided example indicates that in the name /bitrix/php_interface/include/sale_payment/yahoonew the final folder 'yahoonew' shall not contain the word 'handler'. Folder name must be in lower case.

Restrictions on payment system use

You may limit the use of payment system by specific parameters. For example, by delivery system. To do it, apply standard restrictions. When you need something specific, create your own types of restrictions.

Requirements to the .description.php file for payment system handler

Array structure with payment system handler settings is stored in the variable $data and looks as follows:

$data = array(
	'NAME' => 'payment_system_name',
	'SORT' => 500,
	'CODES' => array( // array with parameters, necessary for configuration
		"КОД_ПАРАМЕТРА" => array(
			"NAME" => 'PARAMETER_NAME',
			"DESCRIPTION" => 'PARAMETER_DESCRIPTION',
			'SORT' =>100,
			'GROUP' => 'GROUP_CODE',
			'DEFAULT' => array( // default value
				'PROVIDER_KEY' => 'KEY', // value type: (PAYMENT, ORDER, SHIPMENT, USER, COMPANY, VALUE)
				'PROVIDER_VALUE' => 'DATE_BILL' // value: field from specific entity or an arbitrary value
			)
		),
		...
	)
);

When showing the description when creating a handler, you have to declare the variable $description:

$description = array(
	'MAIN' => 'HANDLER DESCRIPTION'
);

Payment system template customization

The items, printed for user, in the form of all HTML generated by payment systems are segregated to an individual entity, similar to component templates. As the result, payment systems have some specific templates that you can change independently from payment systems. For example, if you do not like a standard invitation printed by a payment system, then you can re-define only this HTML and display your own invitation, without customizing the payment system handler itself.

You need to copy the template from payment system /bitrix/modules/sale/handlers/paysystem/<payment_system_name>/template/ to the site template /bitrix/templates/<site_template>/payment/<payment_system_name>/template/ and edit it as your require. The method \Bitrix\Sale\PaySystem\BaseServiceHandler::searchTemplate() is responsible for searching a HTML template.

Custom cash register handler

Standard cash register handler is not suitable for you? Use the product API and write your own handler. To do this, you need the following:

Inherit the class \Bitrix\Sale\Cashbox\Cashbox and implement the required methods:

Note: additionally you can use the following interfaces:

\Bitrix\Sale\Cashbox\IPrintImmediately - required for sending a receipt to be printed immediately after it's created;
\Bitrix\Sale\Cashbox\ICheckable - required, when you need to request information about the receipt printing results.

use \Bitrix\Sale\Cashbox\Cashbox,
       \Bitrix\Sale\Cashbox\Check,
       \Bitrix\Sale\Cashbox\IPrintImmediately,
      \Bitrix\Sale\Cashbox\ICheckable;

class CashboxCustom extends Cashbox implements IPrintImmediately, ICheckable
{
	/**
	 * @param Check $check
	 * @return array
	 */
	public function buildCheckQuery(Check $check)
	{
		// building a query with information about the cash register receipt
	}

	/**
	 * @param $id
	 * @return array
	 */
	public function buildZReportQuery($id)
	{
		// building query to print z-report
		// when z-print is not required, returns an empty array
	}
	
	public function printImmediately(Check $check)
	{
		// algorithm for sending receipt for printing
	}
	
	public function check(Check $check)
	{
		// algorithm for requesting receipt status
	}

	/**
	 * @return string
	 */
	public static function getName()
	{
		// handler name
		return Localization\Loc::getMessage('SALE_CASHBOX_CUSTOM_TITLE');
	}
	
	/**
	 * @param array $data
	 * @throws Main\NotImplementedException
	 * @return array
	 */
	protected static function extractCheckData(array $data)
	{
		// retrieving receipt data to be saved
	}
	public static function getVersion() ?: float
	{
		// version, operated by handler
		return null; 
	}
}

Connect cash register handler to the system using the event OnGetCustomCashboxHandlers. Event handler must return an array type: array(full_class_name => file_path):

AddEventHandler("sale", "OnGetCustomCashboxHandlers", 'myCashboxFunction');

function myCashboxFunction()
{
    return new \Bitrix\Main\EventResult(
       \Bitrix\Main\EventResult::SUCCESS,
       array(
           '\CashboxCustom' => '/bitrix/php_interface/include/cashboxcustom.php',
       )
   );
}

Resulting admin site section shows your handler in the cash register settings.

Related links:

Printing receipts via payment system

[ds]In previous article[/ds][di] Standard online cash register doesn't suit you? Use the product API and write your own custom handler.

Learn more...[/di] you have found out how to write your own cash register handler. In this article, you will find details on the algorithm used for printing receipts via payment system:

Creating a payment
Receipt data is prepared when creating a payment. Usually the following data:
- shopping cart contents;
- tax system;
- VAT;
- receipt type.
This data is sent jointly with query for creating a payment.

At this stage, system doesn't create a receipt, because buyer hasn't executed payment yet.
Payment
After the buyer has executed a payment, payment gate sends a corresponding notification.

When processing the notification, system changes payment status to Paid.
Receipt
When payment status is changed, collecting receipt data begins:
- system determines receipt type to be printed (matches with type, passed when creating a payment);
- calls the method buildCheckQuery that prepares receipt data;
- selects a suitable cash register for printing;
- calls the method printImmediately. Because receipt data is already available in the payment gate, its not passed again;
- receipt in status Printed is added to the system.

Receipt status
After the receipt is added to the system, you can get data on this receipt status via the agent \Bitrix\Sale\Cashbox\Manager::updateChecksStatus(), or a manager can manually request the status from interface.

Note: When first receipt was a "full payment" receipt, receipt handling is complete at this stage. When receipt type is different ("advance payment" or "prepayment") you need to print a second closing receipt when shipping an order.
Printing a closing receipt
At the moment of order shipment, the system begins to collect data for second receipt:
- system determines receipt type to be printed (in this case it's "full payment");
- calls the method buildCheckQuery, that prepares receipt data;
- selects a suitable cash register for printing;
- calls the method printImmediately, and now receipt data is sent to payment provider;
- receipt in status Printed is added to the system.

Finalizing ('closing') receipt status
After the receipt is added to the system, you can get status data for this receipt via agent \Bitrix\Sale\Cashbox\Manager::updateChecksStatus(), or a manager can manually request the status from interface.

Related links:

Handling delivery service REST

This chapter overviews principles for working with Delivery service REST:

Configuring delivery service handler;
Configuring a delivery service;
Settings for additional delivery services;
Handling shipment properties;
Typical scenario for delivery service REST handling: a Sales center delivery. Starting point for a manager can be a feature of payment receipt ("Receive payment in deal") or creating a delivery activity.

Delivery service creating and setup

Delivery service handler setup

Delivery service handler is a template employed to subsequently create instances of delivery service. That's why before creating a delivery service, you need to add a handler using the method sale.delivery.handler.add:

{
  "CODE":"uber",
  "NAME":"Uber",
  "DESCRIPTION":"Uber Description",
  "SETTINGS":{
    "CALCULATE_URL":"http://gateway.bx/calculate.php",
    "CREATE_DELIVERY_REQUEST_URL":"http://gateway.bx/create_delivery_request.php",
    "CANCEL_DELIVERY_REQUEST_URL":"http://gateway.bx/cancel_delivery_request.php",
    "HAS_CALLBACK_TRACKING_SUPPORT":"Y",
    "CONFIG":[
      {
        "TYPE":"STRING",
        "CODE":"SETTING_1",
        "NAME":"Setting 1"
      },
      {
        "TYPE":"STRING",
        "CODE":"SETTING_2",
        "NAME":"Setting 2"
      }
    ]
  },
  "PROFILES":[
    {
      "NAME":"Taxi",
      "CODE":"TAXI",
      "DESCRIPTION":"Taxi Delivery"
    },
    {
      "NAME":"Cargo",
      "CODE":"CARGO",
      "DESCRIPTION":"Cargo Delivery"
    }
  ]
}

Handler's symbolic code and name are mandatory. Handler's symbolic code will be required for creating a delivery service.

When creating a handler, you need to indicate URL for webhooks, used for queries in the following instances:

for delivery cost calculation (CALCULATE_URL)
for creating a delivery order (CREATE_DELIVERY_REQUEST_URL)
for cancelling a delivery order (CANCEL_DELIVERY_REQUEST_URL)

You may skip passing CREATE_DELIVERY_REQUEST_URL and CANCEL_DELIVERY_REQUEST_URL for scenarios when integration with delivery requests/orders is not employed. In this case, the flag HAS_CALLBACK_TRACKING_SUPPORT must be set as "N".

You have an option to specify a set of available parameters (CONFIG) when creating a delivery service handler, with unique values for each instance of delivery services. Parameters can be used for storage of API keys, contact numbers and other authentication data for specific delivery service instances.

Handler creating is possible only when minimum at least one delivery profile is available (PROFILES).

Also, you can use methods for updating and deleting existing handlers and retrieving list of handlers.

Delivery service settings

After successfully creating a delivery service handler you can start adding an instance of the delivery service itself using the method sale.delivery.add:

{
  "REST_CODE":"uber",
  "NAME":"Uber Taxi",
  "DESCRIPTION":"Uber Taxi Description",
  "LOGOTYPE":"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",
  "CURRENCY":"USD",
  "SORT":"500",
  "ACTIVE":"Y",
  "CONFIG":[
    {
      "CODE":"SETTING_1",
      "VALUE":"SETTING_1 value"
    },
    {
      "CODE":"SETTING_2",
      "VALUE":"SETTING_2 value"
    }
  ]
}

Handler symbolic code (REST_CODE) is mandatory.
Logo with image of delivery service can be passed as base64-encoded string.
You can setup a parameters config when creating an individual delivery service instance (CONFIG).

On successfully created delivery service, its assigned with a numerical identifier. Response example:

{
  "result":{
    "parent":{
      "ID":"622",
      "PARENT_ID":null,
      "NAME":"Uber Taxi",
      "ACTIVE":"Y",
      "DESCRIPTION":"Uber Taxi Description",
      "SORT":"500",
      "CURRENCY":"USD",
      "LOGOTYPE":"954"
    },
    "profiles":[
      {
        "ID":"688",
        "PARENT_ID":"622",
        "NAME":"Taxi",
        "ACTIVE":"Y",
        "DESCRIPTION":"Taxi Delivery",
        "SORT":"500",
        "CURRENCY":"USD",
        "LOGOTYPE":null
      },
      {
        "ID":"689",
        "PARENT_ID":"622",
        "NAME":"Cargo",
        "ACTIVE":"Y",
        "DESCRIPTION":"Cargo Delivery",
        "SORT":"500",
        "CURRENCY":"USD",
        "LOGOTYPE":null
      }
    ]
  },
  "time":{
    "start":1642404734.307061,
    "finish":1642404734.582061,
    "duration":0.27500009536743164,
    "processing":0.08100008964538574,
    "date_start":"2022-01-17T09:32:14+02:00",
    "date_finish":"2022-01-17T09:32:14+02:00"
  }
}

Returns the root delivery service, as well as all created profiles. Root delivery service is used as container for delivery services for specific profiles (their list was indicated when creating the handler). The setup process (additional service config, property adding and etc.) will require profile IDs for the root delivery service. You can get the list of created profiles either from the response after creating a root service, or later (for example, using the method sale.delivery.getList):

{
  "FILTER":{
    "PARENT_ID":622
  }
}

Response example:

{
  "result":[
    {
      "ID":"688",
      "PARENT_ID":"687",
      "NAME":"Taxi",
      "ACTIVE":"Y",
      "DESCRIPTION":"Taxi Delivery",
      "SORT":"500",
      "CURRENCY":"USD",
      "LOGOTYPE":null
    },
    {
      "ID":"689",
      "PARENT_ID":"687",
      "NAME":"Cargo",
      "ACTIVE":"Y",
      "DESCRIPTION":"Cargo Delivery",
      "SORT":"500",
      "CURRENCY":"USD",
      "LOGOTYPE":null
    }
  ],
  "time":{
    "start":1638544721.243672,
    "finish":1638544721.621672,
    "duration":0.37800002098083496,
    "processing":0.019999980926513672,
    "date_start":"2021-12-03T17:18:41+02:00",
    "date_finish":"2021-12-03T17:18:41+02:00"
  }
}

The example above shows, that during the process of creating a root delivery service - two subsidiary services were created for profiles with identifiers 688 and 689. These two specific services will be used for further setup. Root service is just a container for the delivery service profiles.

In case, you'll need to indicate settings or load a custom logo for a specific profile's delivery service, use the method sale.delivery.update.

Description for the rest of delivery service methods can be found in the section Delivery services.

Configuring additional delivery services

If the a profile has additional services, they can be added using the method sale.delivery.extra.service.add.

Example of adding an extra service of checkbox (yes/no) "Delivery to the door" type:

{
  "DELIVERY_ID":688,
  "ACTIVE":"Y",
  "CODE":"door_delivery",
  "NAME":"Door Delivery",
  "TYPE":"checkbox",
  "PRICE":59.99,
  "SORT":100
}

Example of adding an extra service of enum (list) "Cargo type" type:

{
  "DELIVERY_ID":688,
  "ACTIVE":"Y",
  "CODE":"cargo_type",
  "NAME":"Cargo Type",
  "TYPE":"enum",
  "ITEMS":[
    {
      "TITLE":"Small Package(s)",
      "CODE":"small_package",
      "PRICE":129.99
    },
    {
      "TITLE":"Documents",
      "CODE":"documents",
      "PRICE":69.99
    }
  ],
  "SORT":100
}

You can indicate a symbolic code (CODE) for additional delivery service to then identify selected extra services when getting queries to webhooks for calculating delivery prices and creating a delivery orders. The response returns a numerical identifier for created additional service. It can be also used as an alternative to symbolic code to identify selected extra services when querying the webhooks.

Full list of methods to handle additional services can be found in the section Additional services.

Handling shipping properties

When you have to provide additional information needed to calculate delivery price and/or create a delivery order, it can be done by adding properties to delivery service profiles. Below is an example of adding two "Address" properties (From and To) and "String" property for passing a text commentary. To create a shipping property, use the method sale.shipmentproperty.add.

Example of created property for indicating source shipping address:

{
  "fields":{
    "personTypeId":"3",
    "propsGroupId":"11",
    "name":"Address From",
    "active":"Y",
    "sort":"100",
    "description":"",
    "type":"ADDRESS",
    "required":"Y",
    "isAddressFrom":"Y"
  }
}

Example of creating property for indicating destination shipping address:

{
  "fields":{
    "personTypeId":"3",
    "propsGroupId":"11",
    "name":"Address To",
    "active":"Y",
    "sort":"100",
    "description":"",
    "type":"ADDRESS",
    "required":"Y",
    "isAddressTo":"Y"
  }
}

Example of creating property for indicating a commentary:

{
  "fields":{
    "personTypeId":"3",
    "propsGroupId":"11",
    "name":"Comments",
    "active":"Y",
    "sort":"100",
    "description":"",
    "type":"STRING",
    "required":"N"
  }
}

Responses will contain created properties' identifiers. They will be needed to identify property values subsequently passed to webhooks. They are also needed for adding a created property to delivery service profile (see next step).

Payer type (personTypeId) can be fetched by the method sale.persontype.list. Property must be created separately for each required payer type (legal, private persons).

Property group (propsGroupId) can be fetched by the method sale.propertygroup.list.

Each created property now must be added to a delivery service profile. You can do it using the method sale.propertyRelation.add.

Example:

{
  "fields":{
    "propertyId":"437",
    "entityId":"688",
    "entityType":"D"
  }
}

This example adds a property with identifier 437 to the delivery service with identifier 688.

When you plan to create several delivery services that share certain set of properties (for example, they all need "From" and "To" addresses, as well as commentary), then you don't have to create separate properties for each delivery service. You can just add new delivery services to already existing properties. You can get list of shipping properties using the method sale.shipmentproperty.list.

At this step, config and setup procedure is complete. Next stage is overviewed in the article for procedure of using installed and configured delivery service.

Using Delivery service in Sales Center scenarios

Let's overview one of full-scale standard scenarios available for REST delivery services: handing delivery in sales center. Starting point for a manager can be the feature of receiving payment ("Receive payment in deal") or creating a delivery activity.

Manager procedure

Delivery cost pre-calculation

Manger can preliminarily calculate delivery cost inside delivery slider by selecting products for shipping and by indicating property values (addresses and a comment in this case) and requirements for additional services:

When calculating a delivery, system sends query for a URL, indicated in the property CALCULATE_URL of delivery service handler. Query passes all the parameters necessary for calculating delivery cost (shipment properties, weight, item price, necessary additional services, delivery service settings and etc.). Response must retrieve a preliminary delivery cost in the request's currency. When delivery cost calculation is impossible, delivery service must display error text to the manager (see. delivery cost pre-calculation webhook).

In case delivery service handler supports an option of creating delivery requests and their subsequent tracking (handler's parameter value HAS_CALLBACK_TRACKING_SUPPORT is set as "Y"), the system creates an [dw]activity[/dw][di] [/di] for delivery of the created shipment.

Creating a delivery request

By using a delivery activity, manager can initiate process of delivery request creation. Clicking on Request delivery ([dw]Request Delivery[/dw][di] [/di]) sends a [dw]query[/dw][di] [/di] to URL, indicated in the property CREATE_DELIVERY_REQUEST of delivery service handler. The query, in addition to shipping information, also has information about sender and recipient contacts.

Upon successfully processed query results, delivery service creates a delivery request and passes its external identifier in the response. Subsequently, this identifier will be needed for updating the request's status and binding to sender or recipient of the request. If a delivery request cannot be created for some reason, delivery service must issue an error text to be displayed to the manager (see. delivery request creating webhook).

Delivery activity for successfully created delivery request will look as follows:

Cancelling a delivery request

Manager can attempt to cancel previously created request at any time until it wasn't completed by the delivery service. Clicking on Cancel request sends query to the URL, indicated in the property CANCEL_DELIVERY_REQUEST of delivery service handler. If permitted, delivery service can cancel the request and informs about successful cancellation in the response. Delivery activity in this case is returned to an original status and manager can re-issue delivery request. When request cannot be cancelled, delivery service must inform about the reason why the cancellation isn't possible. [dw]Reason[/dw][di] [/di] will be printed to the manager on attempt to cancel the request (see. delivery request cancellation webhook).

Delivery service procedure

Updating a delivery request

Next, it's expected that delivery service information will be updated while executing a delivery request.

Immediately after creating a delivery request, it's minimum required to update its status - for the manager to be aware what is happening with the request at this moment. For example, if searching for a request performer takes some time, manager can be informed by updating [dw]request status[/dw][di] [/di] by the method sale.delivery.request.update:

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "STATUS":{
    "TEXT":"Searching performer",
    "SEMANTIC":"process"
  }
}

Let's assume that request performer was found and now you need to register [dw]new status and performer information[/dw][di] [/di] in the request. You can select properties for delivery request (method sale.delivery.request.update):

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "STATUS":{
    "TEXT":"Performer found",
    "SEMANTIC":"process"
  },
  "PROPERTIES":[
    {
      "NAME":"Car",
      "VALUE":"Gray Skoda Octavia, a777zn"
    },
    {
      "NAME":"Driver",
      "VALUE":"John Smith"
    },
    {
      "NAME":"Phone Number",
      "VALUE":"+79097996161",
      "TAGS":[
        "phone"
      ]
    }
  ]
}

Set of properties can be arbitrary. If a property value is to be processed by a special method, you can mark it by tag. The example above demonstrates performer phone number marked by tag "phone". This allows displaying it as a link and open it via IP telephony (if it was configured at the customer's side), or standard browser features.

Suppose, the delivery service has forwarded a delivery request to the performer/executor (i. e. shipped an order) and now its status [dw]must be updated[/dw][di] [/di] by the method sale.delivery.request.update:

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "STATUS":{
    "TEXT":"Parcel on its way",
    "SEMANTIC":"process"
  }
}

In this case, property values are not passed, because they didn't require an update. Even if you still need to update delivery request properties, you can use two available modes:

adding new properties and values (OVERWRITE_PROPERTIES = N, default mode)
rewriting the complete set of properties (OVERWRITE_PROPERTIES = Y)

When a delivery order/request has been completed, you need to finalize it via the method sale.delivery.request.update:

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "FINALIZE":"Y"
}

Activity for delivery in this case moves to a [dw]completed status[/dw][di] [/di], and its cancellation from the manager's side mow is not possible.

Sending delivery request messages

Let's assume that during delivery order/request in progress, you need to notify the manager responsible for delivery or an order recipient about a specific event. For example, you need to inform the customer that the parcel was handed over to delivery service and about the delivery time (method sale.delivery.request.sendmessage):

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "ADDRESSEE":"RECIPIENT",
  "MESSAGE":{
    "SUBJECT":"We will soon deliver your parcel to you!",
    "BODY":"Your order has been dispatched and will be delivered to you in 23 minutes. Thank you!",
    "STATUS":{
      "MESSAGE":"Dispatched",
      "SEMANTIC":"success"
    }
  }
}

[dw]Notification[/dw][di] [/di] will be sent to the customer using one of available communication channels, configured in CRM. This can be a SMS or a message sent from one of available messengers (for example, WhatsApp). To send a notification to a manager must assign a message recipient (ADDRESSEE) into the value "MANAGER".

Sending delivery request messages

Delivery service can also cancel an order on its own volition, by sending a corresponding request and ensuring that receiving party has received it. Such action may be required, for example, when initially it's not known, if a performer would be found for this request, or not. If the performer wasn't found, delivery service must initiate a request cancellation. In this case, a delivery activity is returned to its original form, so that manager can re-issue the delivery again.

Version Control System

It is not complicated to organize project support by using the version control system if you decide to control only files. To do so, you can use, for example, Mercurial a cross-platform distributed system of version control developed for efficient work with very big code repositories. The use of an add-in with a graphic interface is recommended.

Simple Diagram of Repositories

The diagram contains three elements:

Central repository is the place where changes are stored.
Copy for development - workplaces for developers, there may be several workplaces.
Production website - ultimate target of all changes.

During work changes from Copy for development are transferred to the Central repository, and from it to the Production website.

How Work Is Organized

Developers have changed certain files. A person responsible for commits uses the command Hg Commit. A dialog appears which reflects the changes proper and where they were made:

The text in red means deletion, in green – addition. After the changes have been checked, click Commit and the changes are displayed in the Mercurial environment:

Then, we push the changes to the Central repository and go to the "Production" website. Changes in the "production" website are made from the command line. Also, we have to make sure whether the changes were made on the "production" website itself and, if necessary, transfer them to the Central repository and to Copies for development.

Difficulties

Kernel version on the website server and on the server Copy for developers may differ. That is why the kernel is exempted from the version control system. Technically, it is made by applying a set of rules for the setup file .hgignore.

There is one more difficulty. Kernel files are not changed by project developers but come from the "outside" as updates. In this case, the folder /bitrix/ cannot be just exempted, because it may contain, among other things, project files: modules, components, website templates, etc. As a result, the file .hgignore becomes excessive:

/bitrix/activities/bitrix/
/bitrix/admin
/bitrix/cache
/bitrix/components/bitrix/
/bitrix/gadgets/bitrix
/bitrix/image_uploader
/bitrix/images
/bitrix/js
/bitrix/managed_cache
/bitrix/stack_cache
/bitrix/modules/advertising
/bitrix/modules/bitrix.sitecommunity
...
/bitrix/modules/xdimport
/bitrix/modules/xmpp
/bitrix/modules/.htaccess
/bitrix/otp
/bitrix/sounds
/bitrix/template/
/bitrix/themes
/bitrix/tmp
/bitrix/tools
/bitrix/wizards/bitrix
/bitrix/[^/]*\.php$
/upload
/bitrix/php_interface
/bitrix/panel/
/bitrix/updates/
/bitrix/fonts/

Moreover, this file requires ongoing adjustments because new modules are issued or new folders are created in the system. They have to be added to the exemptions.

Support of the /local Folder

For the convenience of project developers, main project files are transferred from the folder /bitrix to the folder /local as a part of work on the new kernel D7 starting from kernel version 14.0.1. It will permit to separate changing project files from the product folder. Actually, it will suffice to add one folder /bitrix to the exemptions.

Which folders are processed in /local?

activities - actions of the production project;
components - components;
gadgets - desktop gadgets;
modules - modules;
php_interface - init.php, folder user_lang;
templates - templates of websites, templates of components, and templates of pages.

When processing folders, the /local folder will always have a priority over /bitrix. It means that if /local/templates/ and /bitrix/templates/ contain website templates with the same name, the template from /local will be connected.

Business Processes for Developer

Business process is a process of document processing for which one entry point, several exit points, and a sequence of activities (steps, stages, or functions) to be performed in a certain order and subject to certain conditions are set.

Business Processes Module:

Is intended for organizing both sequential processing of infoblock elements as a separate sequential process, and creating status profiles of complex processes with an indefinite period of activity.
Is a tool used by other parts of the product (modules, components, etc.) to provide users with a possibility to determine, perform, and manage business processes (workflows). It permits visually programming of arbitrary functionality and also run and manage such programs. Here, “arbitrary” means a possibility to create user-defined activities in order to expand standard functionality.
Provides for a versatile business process programming mechanism which can be used by non-programmers. Such versatile mechanism is implemented using a visual drag&drop programming mechanism which is familiar to any computer user. The template of business processes is created in a special visual design view.

Important! To ensure correct operation of the module the system must meet the minimum system requirements. Before installing it, please make sure your installation meets this requirement.

Each instance of a business process (hereinafter referred to as the “BP”), is a program. BP input parameters are the parameters used to launch the program. BP variables are the program’s variables.

Accordingly, the lifetime of BP parameters and variables is limited by the lifetime of the BP itself. In order to make sure BP variables, parameters, or any other values are available after BP termination and/or outside BP, you have to save them somewhere in ROM. The most convenient way to save them is to a BP document.

A BP instance may operate simultaneously only in one copy. An attempt to run a second copy before termination of operation of the first (e.g., process launch on behalf of two different users) will cause an error: The business process is blocked by another process. As a rule, it may be caused by an error and the incorrect termination of the other BP.

Each BP instance works on a document. The documents may be physically represented by different entities and determine different operation functionality. E.g., a BP component which example is located in the Services Bitrix24 menu eventually uses infoblock elements as a document.

Using activities, BP makes it possible to manipulate the document it works on. E.g., change the document or publish it.

Attention! The implementation of business processes requires that specialists have specific skills. These specialists must understand substantive essence of business processes in the company and be able to express this essence through logical circuits.

Before proceeding with the automatization of a business process it is recommended that a diagram of the business process be drawn first and a clear idea be formed as to how to implement such diagram.

Template of a Business Process

Business Process template is a diagram (program) where one entry point, a sequence of activities (steps, stages, or functions) to be performed in a certain order and intended to achieve a certain goal, and also one or more exit points defining the termination of the execution are set.

The template is created in a special module Business Process Designer using a visual designer. The visual designer permits drag and drop activities from the control panel to the main working area of the visual designer thus creating a business process template visually. The template is created in the form of a flow diagram which graphically displays the operating logic of a business process.

The installation package includes a number of embedded activities which can be used in order to perform general purpose work. There are several dozens of such activities. There are activities that permit using your own script or php code. Also, there is a possibility to create your own activities and connect them to a business process.

The created template of a business process can be executed automatically or manually, depending on the settings. Several instances of a business process can be executed simultaneously at any time, and the system manages execution of these instances, saving and recovering their condition upon request. A log of each instance of a business process is maintained for further analysis of the diagram operation and its adjustment according to new conditions.

The internal system design of a business process the business process template is represented as a multidimensional array containing a hierarchy of actions and their property values. It is this representation of a business process template that API of the Business Processes module works with.

An example of a simple array representing a business process template is provided below:

array(
  array(
    "Type" => "SequentialWorkflowActivity",
    "Name" => "SequentialWorkflowActivity1",
    "Properties" => array(),
    "Children" => array(
      array(
        "Type" => "SetFieldActivity",
        "Name" => "SetFieldActivity1",
        "Properties" => array("Field" => "XML_ID", "Value" => "Send for approval"),
      ),
      array(
        "Type" => "IfElseActivity",
        "Name" => "IfElseActivity1",
        "Properties" => array(),
        "Children" => array(
          array(
            "Type" => "IfElseBranchActivity",
            "Name" => "IfElseBranchActivity1",
            "Properties" => array("FieldCondition" => array("CREATED_BY", "=", 1)),
            "Children" => array(
              array(
                "Type" => "SetFieldActivity",
                "Name" => "SetFieldActivity2",
                "Properties" => array("Field" => "XML_ID", "Value" => "On approval"),
              ),
            ),
          ),
          array(
            "Type" => "IfElseBranchActivity",
            "Name" => "IfElseBranchActivity2",
            "Properties" => array(),
            "Children" => array(
              array(
                "Type" => "ApproveActivity",
                "Name" => "ApproveActivity1",
                "Properties" => array(
                  "Users" => array(1),
                  "ApproveType" => "all",
                  "OverdueDate" => null,
                  "Name" => "Verify entry",
                  "Description" => "",
                  "Parameters" => null,
                ),
                "Children" => array(
                  array(
                    "Type" => "SetFieldActivity",
                    "Name" => "SetFieldActivity3",
                    "Properties" => array("Field" => "XML_ID", "Value" => "Approved"),
                  ),
                  array(
                    "Type" => "SetFieldActivity",
                    "Name" => "SetFieldActivity4",
                    "Properties" => array("Field" => "XML_ID", "Value" => "Rejected"),
                  ),
                ),
              ),
            ),
          ),
        ),
      ),
    ),
  ),
)

Business Process

A Business Process is a specific instance of a business process template. It is created upon request, launched from the entry point, and terminates its operation upon achieving one of the exit points. An unlimited number of business processes can be launched for one template simultaneously.

A business process ceases to exist upon after its termination. But its status is maintained and available for use.

A business process is always executed over a certain document which is determined by its code. In this case, the document may not have a physical representation (i.e. it can be virtual). Business process may be set up for automatic launch in case any document is added or any modification is done to a document.

Each business process has a unique identification code which can be assigned by an executing environment or preset by the programmer. The code may be used to access a certain business process.

An event can be sent to a business process using methods of executing environment. The message is sent to the business process using its unique code.

When launched, a business process can accept as input parameters the values which list is preset at the business process’ design stage. For example, it can be an order ID or a current user’s code. Any activity of a business process will have access to these parameters.

A business process is not necessarily executed continuously. For example, a business process contains the activity CBPDelayActivity (executes a delay, postponing execution for a certain term), in which the business process enters into a wait condition, gets saved into the database, and then is removed from memory. Upon the expiry of the preset time, the business process is read from the database, recalled in memory, and goes on executing from the stop point on.

Advice

To see all the interior details during debugging, for example, in order to understand which variables can be operated, introduce the following PHP code into the points of interest in the diagram:

echo "<pre>", print_r( $_REQUEST ), "</pre>";
echo "-----<br />";
echo "<pre>", print_r( $this ), "</pre>";
exit;

After that, launch the business process for execution, for example, create or edit an infoblock element and take your time reviewing the process.

Activities

Everything that occurs in a business process is an activity. The business process proper is a composite activity which permits determining subordinate activities inside it. Each activity within a business process must have a unique name. .

Activity is a class which is inherited from the abstract class CBPActivity or its descendants. The name of the class must start from the substring CBP and may consist from Latin letters and numbers.

Example:

<?
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class CBPMyActivity1
	extends CBPActivity
{
	. . .
}
?>
>

Activities which cannot contain other actions inside are inherited directly from the CBPActivity class. This class determines a set of basic methods required by each activity. Some methods determined in the CBPActivity class can or must be redefined in the descendant class.

By default, the installation package contains several dozens of activities which permit creating business processes. However, sometimes it may become necessary to create your own activity.

Let us consider several examples of creating own activities.

Main Standard Activities

Activity	Description
CBPActivity	Abstract basic class of all activities.
CBPCompositeActivity	Abstract basic class of composite activities, i.e. activities which may contain subordinate activities inside.
CBPCodeActivity	Launches an arbitrary PHP code for execution.
CBPSetVariableActivity	Establishes values of business process variables.
CBPDelayActivity	Implements a delay, postponing execution for a certain term.
CBPHandleExternalEventActivity	Implements an activity which expects an external event. Business process is suspended pending such external event.
CBPEventDrivenActivity	Serves as a container for activities in which the execution depends on an event.
CBPIfElseActivity	Implements a condition functionality.
CBPIfElseBranchActivity	Implements a condition thread functionality.
CBPWhileActivity	Implements a cycle functionality.
CBPListenActivity	Implements a wait on one of several possible events. When one of the events occurs, the others stop waiting on events and get cancelled.
CBPParallelActivity	Launches a set of subordinate activities in parallel.
CBPSequenceActivity	Launches a set of subordinate activities sequentially.
CBPSequentialWorkflowActivity	Represents a business process which executes activities sequentially (a sequential business process).
CBPSetStateActivity	Establishes a status in a business process with statuses.
CBPStateActivity	Represents a status in a business process with statuses.
CBPStateMachineWorkflowActivity	Represents a business process with statuses.

Any activity is inherited from the basic activity class or one of its descendants.

Properties of Activities

An activity may have properties which values are set up when adding activities to a business process template. Both constants and links to properties of other activities of a business process may constitute property values.

Activity properties are described in the activity class designer by defining an array in the arProperties class members:

public function __construct($name)
{
	parent::__construct($name);
	$this->arProperties = array("Title" => "", "MyProperty" => "");
}

The names of the properties constitute the keys in the property definition array and default values of the properties constitute the values.

When executing an activity, the properties are available as class members:

$this->MyProperty

Input parameters (properties) of a business process are available as properties of a root activity of the business process. Any activity of a business process may access input parameters of a business process.

For example, if a business process was launched using the code:

// Business process template code
$workflowTemplateId = 12;

// Business process is launched for the document which is an infoblock element with code 358
$documentId  = array("iblock", "CIBlockDocument", 358);

// Input parameters of the business process
$arParameters = array("MyProperty" => "red");

$runtime = CBPRuntime::GetRuntime();
$wi = $runtime->CreateWorkflow($workflowTemplateId, $documentId, $arParameters);
$wi->Start();

then in any activity of this business process a parameter value can be obtained using the following code:

$rootActivity = $this->GetRootActivity();
if ($rootActivity->IsPropertyExists("MyProperty"))
	$val = $rootActivity->MyProperty;
//  $val == "red"

Developer describes activity properties when writing activity code. Income parameters of a business process (a.k.a. properties of root activity of a business process) are described by users when creating a business process template.

Both constants and links to properties of other business process activities may constitute property values, provided that these activities were executed previously.

In order to make sure that at the time of a business process execution the property value of one activity is the property value of another activity executed above, the following array must be set as a property value of the first activity at the stage of creating the template for such business process:

array("name of the activity which properties are referred to", "property name")

In case of simple types of these properties, the following string must be set as a property value of the first activity:

"{=activity_name, property_name}"

In order to refer to an input parameter (property) of a business process which is available as a property of a root activity of a business process, the word Template should be used as the name of the activity:

array("Template", "property name")
"{=Template, property_name}"

In general terms, the following words can be used as an activity name:

Document – to access an arbitrary field of the document for which a business process is started;
Template – to access an input parameter (property) of a business process (root activity);
Variable – to access a business process variable;
User – to obtain the code of the current user ("ID" must be indicated as the property name);
System – accessing system variables, presently only the property Now (current date in the website format) is available;
Any other name – to access an action property with this name.

For example, if during development the following string is set as a property value:

"Document [url={=Template:PathTemplate}]{=Document:NAME}[/url] was approved"

and the workflow is launched with the input parameter PathTemplate equal to file.php for the document named Chart of Accounts, the following string will constitute the property value during activity execution:

"Document [url=file.php]Chart of Accounts[/url] was approved"

Composite Activities

Composite activities are inherited from the abstract class CBPCompositeActivity which, in its turn, is inherited from the class CBPActivity. The class CBPCompositeActivity provides for support of the option to include subordinate activities inside the activity. For example, the standard activity CBPParallelActivity (execution in parallel) which contains subordinate activities corresponding to threads of parallel execution constitutes a composite activity.

The class CBPCompositeActivity contains the member arActivities which can be used to access subordinate activities.

For example, if the first subordinate activity must be started and terminated when launching an activity, the following code can be used:

class CBPMyActivity
	extends CBPCompositeActivity    // inherited, because it is a composite activity
	implements IBPEventActivity	// processing the event of termination of a subordinate //activity
{
	// Exacutable method of the activity
	public function Execute()
	{
		// We take the first subordinate activity
		$activity = $this->arActivities[0];
		// and subscribe to the event of subordinate activity status change
 		//  (termination)
		$activity->AddStatusChangeHandler(self::ClosedEvent, $this);
		// Submit the subordinate activity to the executing environment for execution
		$this->workflow->ExecuteActivity($activity);
		// Return the instruction to the executing environment that the activity is still being executed
		return CBPActivityExecutionStatus::Executing;
	}

	// Interface status change event handler IBPEventActivity
	// The parameter transmits the activity that has changed the status
	protected function OnEvent(CBPActivity $sender)
	{
		// Unsubscribe from the event of subordinate activity status change
 		// (termination)
		$sender->RemoveStatusChangeHandler(self::ClosedEvent, $this);
		// Subordinate activity is terminated, we execute other code we need
		//  we execute other code we need
		$this->workflow->CloseActivity($this);
	}
}

Creating Own Activities

User-defined activities are created in the folder /bitrix/activities/custom/ from the website root. Each activity is located in a separate folder. The folder name must be written in lower case letters.

The activity folder must contain an activity class file. The name of the activity class file (in our example it will be myactivity) must coincide with the activity folder name (in our example, /bitrix/activities/custom/myactivity/), but without the first characters “CBP,” and have a php extension. Also, the activity folder may contain other files required for the activity. E.g., a file with activity description, files with activity localization, images, resource files, etc.

The structure of the activity folder is generally similar to the component structure:

.description.php - description of future activity;
properties_dialog.php - form for activity settings;
myactivity.php – activity code;
icon.gif – the icon to display the activity in the general list;
/lang/en/ – contains folders with language messages. The names of the folders must be consistent with the language IDs, e.g., de, en. Each folder contains files with phrases named after corresponding activity files:

.description.php - description of language messages;
myactivity.php – language messages proper.

The file .description.php contains an activity required for proper operation of the system. The activity description file must contain a code similar to the following:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

$arActivityDescription = array(
	"NAME" => GetMessage("MYACTIVITY_DESCR_NAME"),
	"DESCRIPTION" => GetMessage("MYACTIVITY_DESCR_DESCR"),
	"TYPE" => "activity",
	"CLASS" => "MyActivity",
	"JSCLASS" => "BizProcActivity",
	"CATEGORY" => array(
		"ID" => "other",
	),
);
?>

Here, the activity type is determined in the TYPE element which must have two possible values: activity for activities and condition for conditions. Also, the activity name and description, JavaScript class for rendering in a visual editor, category, etc. are set.

The subfolder lang of the activity folder contains files with the localization of activity phrases into different languages.

The activity class file looks similar to the following:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

class CBPMyActivity
	extends CBPActivity
{
	public function __construct($name)
	{
		parent::__construct($name);
		// Determine the property of the action MyText
		// It can be set in the visual editor when
 		// placing the action in the business process template
		$this->arProperties = array("Title" => "", "MyText" => "");
	}

	// Executable method of the activity
	public function Execute()
	{
		// The essence of the activity – writing of a property value into the file
		if (strlen($this->MyText) > 0)
		{
			$f = fopen($_SERVER["DOCUMENT_ROOT"]."/dump.txt", "a");
			fwrite($f, $this->MyText);
			fclose($f);
		}

		// Return the instruction that the activity is terminated to the executing system
		return CBPActivityExecutionStatus::Closed;
	}

	// The static method returns the HTML code of the action property setting 
// dialog in the visual editor. If the action has no 
// properties, this method is unnecessary
	public static function GetPropertiesDialog($documentType, $activityName,
 		$arWorkflowTemplate,$arWorkflowParameters, $arWorkflowVariables,
 		$arCurrentValues = null, $formName = "")
	{
		$runtime = CBPRuntime::GetRuntime();

		if (!is_array($arWorkflowParameters))
			$arWorkflowParameters = array();
		if (!is_array($arWorkflowVariables))
			$arWorkflowVariables = array();

		// If the dialog opens for the first time, we upload the value
 	// of the property which was saved in the business process template
		if (!is_array($arCurrentValues))
		{
			$arCurrentValues = array("my_text" => ""); 

			$arCurrentActivity= &CBPWorkflowTemplateLoader::FindActivityByName(
 				$arWorkflowTemplate,
 				$activityName
 		);
			if (is_array($arCurrentActivity["Properties"]))
				$arCurrentValues["my_text "] =
 $arCurrentActivity["Properties"]["MyText"];
		}

		// The code that generates the dialog is located in a separate file
		// properties_dialog.php in the activity folder.
		// We return this code.
		return $runtime->ExecuteResourceFile(
			__FILE__,
			"properties_dialog.php",
			array(
				"arCurrentValues" => $arCurrentValues,
				"formName" => $formName,
			)
		);
	}

	// The static method receives the values entered in the property setting 
// dialog and saves them in the business process template. If the activity 
// has no properties, this method is unnecessary.
	public static function GetPropertiesDialogValues($documentType, $activityName, 
		&$arWorkflowTemplate, &$arWorkflowParameters, &$arWorkflowVariables,
 	 	$arCurrentValues, &$arErrors)
	{
		$arErrors = array();

		$runtime = CBPRuntime::GetRuntime();

		if (strlen($arCurrentValues["my_text "]) <= 0)
		{
			$arErrors[] = array(
				"code" => "emptyCode",
				"message" => GetMessage("MYACTIVITY_EMPTY_TEXT"),
			);
			return false;
		}

		$arProperties = array("MyText" => $arCurrentValues["my_text "]);

		$arCurrentActivity = &CBPWorkflowTemplateLoader::FindActivityByName(
 			$arWorkflowTemplate,
 			$activityName
 		);
		$arCurrentActivity["Properties"] = $arProperties;

		return true;
	}
}
?>

The code located in the file properties_dialog.php which generates activity setting dialog in the visual editor may look like the following:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();
?>
<tr>
	<td align="right" width="40%"><span style="color:#FF0000;">*</span> :</td>
	<td width="60%">
		<textarea name="my_text" id="id_my_text " rows="5" cols="40"><?= htmlspecialchars($arCurrentValues["my_text"]) ?></textarea>
		<input type="button" value="..." onclick="BPAShowSelector('id_my_text', 'string');">
	</td>
</tr>

The user can introduce an explicit value in the my_text or select one of the values using the dialog that opens using the button . In the second case, the user can establish that the property value of the root activity set as an input parameter upon launching the business process is the property value.

Executing a business process activity using API

Some activities may suspend the execution of a business process pending user’s response.

For such activities, there is an option to perform tasks instead of the user through API. To do so, send an external event to the business process as follows:

CBPDocument::SendExternalEvent($workflowId, $activityName, $arEventParameters);

where:

$workflowId - identifier for a business process instance;
$activityName - name for the activity pending an external event;
$arEventParameters - an array with parameters necessary for a specific activity.
Note: Parameters will vary for different activities.
For more details about the acceptable parameters of a specific activity, please refer to this activity’s source code using the method OnExternalEvent.

Example for the Activity "Document Approval":

CBPDocument::SendExternalEvent("5046fe0fbf1888.64722245","Approve1",array("USER_ID"=>1,"APPROVE"=>true));

where:

"5046fe0fbf1888.64722245" - the identifier of a business process instance;
"Approve1" - name for the approval activity;
"USER_ID"=>1 - identifier for the approving user;
"APPROVE"=>true - the approval result (if declined - false).

Arbitrary PHP Code in a Business Process

In some cases, the creation of own activities is not required to resolve a business process task. An own PHP code introduced as a part of a standard activity PHP code will suffice.

Before reviewing some examples, please take note of the following general advice on code creation:

The code will be executed in its space; i.e. take into account that modules were not connected beforehand. That is why a standard API of Bitrix Framework must be called.
No <??> characters are to be introduced.
Closely monitor the types of variables; variable type cast must be arranged without fail (in some examples of the chapter this step is omitted for easier understanding).

Let us consider the use of code as a part of the activity PHP code.

How to Start One Business Process from Another?

It cannot be done through the business process designer interface. API queries must be generated.

Go to the administrative part of the system, to the page with the documents for which a new business process template must be created.
Go to the page with business processes and create a sequential business process using the business process designer.
Add the activity PHP code (section Other) to the template.

As a part of this activity a more complex business process, e.g. Two-stage Approval, can be called from standard business process templates.

Open the dialog of activity parameter settings using the icon .

Introduce the following code:

CBPDocument::StartWorkflow(
6,
array("iblock","CIBlockDocument","{=Document:ID}"),
array("Voters"=>array("user_1")));

which is submitted to the method that creates the business process:

The first parameter is the ID of the launched template of the business process (in our example, it is a Two-stage Approval)
The second parameter contains parameters of the document for which the business process is being created. Here, the fact that the business process will be available in the administrative part and the variable {=Document:ID} are set.
The last, third, parameter is an array of parameters of the business process launched. In our case, this is the user who is the addressee of the document. In our example, it is the website administrator.

Log Output

If a developer wants to use the business process functionality to its fullest, additional possibilities of the functionality will be required. For example, the output of any messages into the business process log.

Let us assume that the manager’s determination from the lesson “Manager’s ID determination” is used, or the request text just needs to be displayed in the log.

There are two solutions for this: display in the log from the activity PHP code or creation of own activity Record to log. Let us consider both options.

PHP Code

Let us assume that while creating a business process the user types a text of a request which is saved in the Text. variable. In order to display the value of this variable, just add the following query into the PHP code activity:

$rootActivity = $this->GetRootActivity();
$this->WriteToTrackingService($rootActivity->GetVariable("Text"));

Creating an Activity

Create necessary folders from the website root:

bitrix\activities\custom
bitrix\activities\custom\logactivity
bitrix\activities\custom\logactivity\lang\en

Create the following files in the folder /logactivity/:

logactivity.php

<?
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class CBPLogActivity
   extends CBPActivity
{
   public function __construct($name)
   {
      parent::__construct($name);
      $this->arProperties = array(
         "Title" => "",
      );
   }

   public function Execute()
   {
      $rootActivity = $this->GetRootActivity();
      $this->WriteToTrackingService($rootActivity->GetVariable("Text"));

      return CBPActivityExecutionStatus::Closed;
   }

}
?>

.description.php

<?
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

$arActivityDescription = array(
   "NAME" => GetMessage("BPMA_DESCR_NAME"),
   "DESCRIPTION" => GetMessage("BPMA_DESCR_DESCR"),
   "TYPE" => "activity",
   "CLASS" => "LogActivity",
   "JSCLASS" => "BizProcActivity",
   "CATEGORY" => array(
      "ID" => "other",
   ),
);
?>

Create the file logactivity\lang\en\.description.php:

<?
$MESS ['BPMA_DESCR_NAME'] = "Record to log";
$MESS ['BPMA_DESCR_DESCR'] = "Recording a message into Log";
?>

Now the business process designer has a new activity Record to log in the section Other, and the activity just records the value of the variable Text into the log.

Log Output. Variables

Let us consider examples on how to display some variables in the log using PHP code.

List Type Variable

Let us assume that the following List type variable in the DB business process is used:

[Database 1]DB1
[Database 2]DB2
[Database 3]DB3

The value of this variable must be displayed in the log (it also admits multiple values). The display must be arranged as a search of values:

$rootActivity = $this->GetRootActivity();
$list = $rootActivity->GetVariable("DB");
foreach ($list as $k => $v)
{
   $str = $str." ".$v;
}
$this->WriteToTrackingService("The following databases are selected: ".$str);

The Variable of the Linked-to-User Type

Let us assume that the Manager variable is used, its type is Linked-to-User, and it is represented by a string user_145, where the number is the user ID. Let us display its value as the last name and first name.

$str = $rootActivity->GetVariable("Manager");
$str = str_replace("user_", "", $str);
$buf = CUser::GetByID(intval($str))->Fetch();
$this->WriteToTrackingService(" Supervisor:".$buf['NAME']." [".$buf['ID']."]");

Arithmetic Operations in a Business Process

Sometimes it may be necessary to sum up two variables in a business process during its execution, for example, if you analyze the costs and income. Let us consider the following example: how to recalculate the cost of a programmer’s work.

Set the parameters and variables in a business process template:

Business process parameter: {=Template:integrator_USD} - programmer’s work cost in USD;
Business process variable {=Variable:kurs_usd} - USD/EUR rate for recalculation.

Use the following code in the activity PHP code:

// Obtain current business process
$rootActivity = $this->GetRootActivity(); 
// Obtain the value of a business process variable {=Variable:kurs_usd}
$kursUSD = $rootActivity->GetVariable("kurs_usd"); 
// Obtain the value of a business process parameter {=Template:integrator_USD}
$integrator = $rootActivity->integrator_USD;
// Recalculate currency
$integrator = $integrator*$kursUSD;
// Set the value of the business process parameter {=Template:integrator_USD}
$rootActivity->integrator_USD = $integrator;
// Set the value of a business process variable {=Template:ttl}
// You can make calculations and generally do whatever you want with business process variables and parameters
$rootActivity->SetVariable("ttl",
   'The lowest price:'.number_format($min_ttl,0,',',' ')." EUR\n".
   'Profit from the minimum price:'.number_format($min_ttl_plus,0,',',' ')." EUR\n".
   'Tax:'.number_format($min_ttl*$nalog,0,',',' ')." EUR\n\n".
   'Average price:'.number_format($ttl,0,',',' ')." EUR\n".
   'Profit from the average price:'.number_format($ttl_plus,0,',',' ')." EUR\n".
   'Tax:'.number_format($ttl*$nalog,0,',',' ')." EUR\n"
);

Determining the Manager’s ID

In order to find out who the manager of the document initiator is, who is using the activity PHP code (i.e., without using the user’s choice activity), you can use the code provided below.

In this code, the variable $num shows the manager’s level (1 – direct supervisor, 2 – manager’s manager,..). Manager’s ID in a BP format (i.e. of the user_X type) is recorded into a variable with the name var5. This variable must be created in BP parameters and must have a linked-to-user type.

$num = 1;
$userId = substr("{=Document:CREATED_BY}", 5);
$userId = intval($userId);
if ($userId > 0)
{
 CModule::IncludeModule("intranet");
 $dbUser = CUser::GetList(($by="id"), ($order="asc"), array("ID_EQUAL_EXACT"=>$userId), array("SELECT" => array("UF_*")));
 $arUser = $dbUser->GetNext();
 $i = 0;
 while ($i < $num)
 {
  $i++;
  $arManagers = CIntranetUtils::GetDepartmentManager($arUser["UF_DEPARTMENT"], $arUser["ID"], true);
  foreach ($arManagers as $key => $value)
  {
   $arUser = $value;
   break;
  }
 }
 $rootActivity = $this->GetRootActivity();
 $rootActivity->SetVariable("var5", "user_".$arUser["ID"]);

Adding Information to Infoblock from a Business Process

Let us consider an example when the values from the user’s list boxes will be recorded into the user’s properties of an infoblock using a business process.

In this case, after the list boxes Name, String, and File (several files) are filled in and subsequently saved, a new element will be created in a relevant infoblock. The user’s properties of such infoblock will contain the values of the list boxes indicated above. The name of this element will correspond to the name of the created list element.

To begin with, let us create additional boxes in the list:

Values of these boxes will be recorded in the user’s properties of the infoblock using a business process.

Set a default value for the box IBlock ID to avoid filling it in each time when we create a new element of the list (in our case it will be an infoblock with ID = 1). This box is created for demonstration purposes only.

Note: The infoblock ID can also be written directly in the code (see below) or variable of a business process.
Go to the infoblock.
Go to the infoblock settings page, tab Properties (Control Panel > Content > Information blocks > Information block type > required_iblock) and create new user’s properties to which values from the list boxes will be recorded.
Go to the business process proper. Let us create a template of a sequential business process.
Create 2 variables to be used for adjustment purposes:
- ELEMENT_ID - a business process variable to which the ID of the created infoblock element will be recorded in case of success,
- ERROR - a business process variable to which the error text will be recorded in case of failure in creating an infoblock element.

Let us take a code from the sample API query CIBlockElement::Add

Source code

and modify it:

<?
CModule::IncludeModule("iblock"); //connect the module of infoblocks

$el = new CIBlockElement;

$PROP = array();
$PROP[IB_CUSTOM_PROPERTY] = {=Document:PROPERTY_106};
// set for the infoblock property "IB_CUSTOM_PROPERTY" of the type "string" a value from the document box "PROPERTY_106"  

$files = explode(', ',"{=Document:PROPERTY_107}");
foreach($files as $key=>$value)
 {
  $PROP[IB_FILE_PROPERTY]['n'.$key]=array('VALUE'=> CFile::MakeFileArray($value), 'DESCRIPTION' => '');
 }  
// create for the infoblock property "IB_FILE_PROPERTY" of the type "file" a (multiple) value from the document box "PROPERTY_107"	
	
$arLoadProductArray = Array(
  "IBLOCK_ID" = >{=Document:PROPERTY_108},	
// set the  Infoblock ID> where the element will be created from the document box "PROPERTY_108" of the type "string" 	
  "NAME" => {=Document:NAME},
// set the Name of the created infoblock element from the document box "Name"	
 "PROPERTY_VALUES"	=> $PROP,
);

$ELEMENT_ID = $el->Add($arLoadProductArray);

if($ELEMENT_ID > 0)
 $this->SetVariable('ELEMENT_ID', $ELEMENT_ID);
// set a value containing the number of the created infoblock element (should such infoblock element be created) for the business process
// variable "ELEMENT_ID" 
else
 $this->SetVariable('ERROR', $el->LAST_ERROR);
// set a value containing the text of the error message (should the infoblock element be not created) for the business process variable "ERROR"	
?>

This code will create (using API methods) a new infoblock element where the user’s properties IB_CUSTOM_PROPERTY, IB_FILE_PROPERTY, and also the infoblock element name will contain values of user’s boxes PROPERTY_106, PROPERTY_107, PROPERTY_108, and the value of the box list element name.

After that, we will add to the template the activity PHP Code where we will indicate our changed code.

We will add to the template the activity Log entry indicating the following text:
```
{=Variable:ELEMENT_ID_printable}, {=Variable:ERROR_printable}
```
This way, we will record the value of debugging variables into the business process execution report for analysis in case of errors.

Additional Information and Examples

This chapter provides some additional information which may be proved useful for developers. There are also examples of nonstandard tasks and their solutions.

If there is no API description

When working with Bitrix Framework API description is of major importance. Unfortunately, API descriptions of new functionality are never issued simultaneously with the functionality. There are several reasons for that:

It is impossible to write API and the functionality itself at the same time;
Writing API immediately after issuing a functionality is not practical, because soon after its issue many bugs are found; they require corrections and, accordingly, these corrections must be taken into account in the documentation.

As a rule, API is written some time (usually two or three months) after release. Unfortunately, it also occurs that the old functionality is not described fully and correctly. For example, changes were made but not included in the documentation.

Thus, the only solution for the developer consists in reviewing the code itself.

Web services

Web Service - is a program system identified by the URI string which public interfaces and links are defined and described by the XML language. The description of this program system may be found using other program systems which may interact with it according to such description through XML-based messages transmitted via Internet protocols.

Advantages of Web Services:

Web services ensure the interaction of program systems irrespective of the platforms. Web services are based on open standards and protocols. Thanks to XML, web services can be developed and debugged with ease. The use of HTTP Internet protocol provides for interaction of program system through the network firewall.

The web service module serves to facilitate the creation and integration with the existing web services. The module is mainly used for developing integrations with operating applications both inside the company and with external already operating web services.

Bitrix Framework

What is Bitrix Framework?

For Those Who Switched to Bitrix Framework from Other Platforms

Seeking knowledge first

Bitrix Framework and Drupal

Bitrix Framework and Joomla

Glossary

Glossary

Production Architecture

Production Architecture

MVC Architecture for Bitrix Framework

Structure