BX.addCustomEvent

Function BX.addCustomEvent

Function provides for two variants of input parameters.

void 
BX.addCustomEvent(
 Object eventObject,
 string eventName,
 Function eventHandler
);

void 
BX.addCustomEvent(
 string eventName,
 Function eventHandler
);

Function assigns the eventHandler to the custom eventName, occurring in the eventObject. If eventObject is not specified (short call), the handler will be called during each event call with such custom eventName in any object.

Retrieveal of list of all events in the system

When handling custom events, a reasonable question arises - how to get a full list of events available in the system (current for the ready templates, Control panel and Bitrix24 Self-Hosted)?

This task can be solved as follows: find the following method in the /bitrix/js/main/core/core.js file:

BX.onCustomEvent = function(eventObject, eventName, arEventParams, secureParams);

Insert logging feature into the executed method:

console.log(eventName, arEventParams);

After that, when various actions are performed with the account (clicks, push-information, opening the popup), event codes will be recorded into the log.

Note: don't forget to delete the log-enabling string in the kernel after the required data is collected.

Example of function use

How to add your own fonts into the visual editor

And the required fonts into the array of the GetFontFamilyList event. Then, they will start to be displayed in the font list in the editor.

BX.addCustomEvent('GetFontFamilyList', BX.delegate(function (fontlist) {
	fontlist.push({value: 'RobotoThin', name: 'RobotoThin'});
	fontlist.push({value: 'RobotoLight', name: 'RobotoLight'});
	fontlist.push({value: 'RobotoRegular', name: 'RobotoRegular'});
	fontlist.push({value: 'RobotoBlack', name: 'RobotoBlack'});

	for(var key in userFonts) {
		fontList.push({value: userFonts[key], name: userFonts[key]})
	}
}));

How to register the counter update

Event handler must be added to achieve this:

BX.addCustomEvent("onPullEvent-main", BX.delegate(function(command,params){
   if (command == 'user_counter' && params[BX.message('SITE_ID')] && params[BX.message('SITE_ID')]['__YOUR_COUNTER_NAME__'])
   {
      // Execute the code to update the counter
      // new value of the counter will be specified in the params[BX.message('SITE_ID')]['__YOUR_COUNTER_NAME__'] 
   }
}, this));

For mobile version:

BX.addCustomEvent("onPull-main", BX.delegate(function(data){
   if (data.command == 'user_counter' && data.params[BX.message('SITE_ID')] && data.params[BX.message('SITE_ID')]['__YOUR_COUNTER_NAME__'])
      {
      // execute the code to update the counter
      // new value of the counter will be specified in the data.params[BX.message('SITE_ID')]['__YOUR_COUNTER_NAME__']
   }
}, this));

Handling Push and Pull module

Trap for desktop version pages (all events except the online events):

BX.addCustomEvent("onPullEvent-moduleName", BX.delegate(function(command,params){
   console.log('Events of moduleName', command, params);
}, this));

Trap for mobile version pages (all events except the online events):

BX.addCustomEvent("onPull-moduleName", BX.delegate(function(data){
    console.log('Events of moduleName', data.command, data.params);
}, this));

Note: on't forget to change the name of your module in the "moduleName" example.

Example of code to handle the PHP classes of the module (Pull, Pull Shared, Pull Watch):

BX.addCustomEvent("onPullEvent-main", function(module_id,command,params) {
    if (command == 'check')
    {
        console.log('Command from module MAIN - its work!');
    }
});

In the example we are subscribing to the command receiving event (onPullEvent-moduleName), moduleName - is the name of your module, for example main; in the function we receive command, params, which we have specified when ending a command from PHP. Commands are processed with account of your logic.

If your logic requires collection of all events, the format is a little bit different: (available for any pull version)

Trap for desktop version pages (all events except online events):

BX.addCustomEvent("onPullEvent", BX.delegate(function(module_id,command,params){
   console.log(module_id, command, params);
}, this));

Trap for mobile version pages (all events except online events):

BX.addCustomEvent("onPull", BX.delegate(function(data){
    console.log(data.module_id, data.command, data.params);
}, this));

Example of code to handle the PHP classes of the module (Pull, Pull Shared, Pull Watch):

BX.addCustomEvent("onPullEvent", function(module_id,command,params) {
    if (module_id == "test" && command == 'check')
    {
        console.log('Work!');
    }
});

In the example we are subscribing to the command receiving event (onPullEvent), module_id is received in the function, and command, params which we specified when sending a command from PHP. We process our commands with account of our logic.

Note:

To retrieve online data, use the [link=9211141]onPullOnlineEvent[/link] event
It is recommended to use event handlers for specific modules, instead of the handler for all events. Such format will be mode efficient.

Examples of handling widget on site

Adding your own channel and button

BX.addCustomEvent(document, "b24-sitebutton-load", function (e, instance){
	instance.buttons.add({
	  'id': 'my-mail',
	  'href': 'mailto: robert@bitrix.com',
	  'title': 'Email me',
	  'target': '_self',
	  'sort': 1000,
	  'icon': 'http://sparkysite.ru/medium/mails/mails01/mmail01.png',
	  'onclick': function() {console.log('button my-mail clicked!!!');},
	});
});

The same with jQuery
$( document ).on( "b24-sitebutton-load", function (e, instance){ instance.buttons.add({ 'id': 'my-mail', 'href': 'mailto: robert@bitrix.com', 'title': 'Email me', 'target': '_self', 'sort': 1000, 'icon': 'http://sparkysite.ru/medium/mails/mails01/mmail01.png', 'onclick': function() {console.log('button my-mail clicked!!!');}, }); });

The same with jQuery

Changing the panel titles of the form

BX.addCustomEvent(document, "b24-sitebutton-load-widget-crmform", function (e, widget){
    widget.caption = 'Form title';
});
BX.addCustomEvent(document, "b24-sitebutton-load-widget-callback", function (e, widget){
    widget.caption = 'Call title';
});

The same with jQuery
$( document ).on( "b24-sitebutton-load-widget-crmform", function (e, widget){ widget.caption = 'Form title'; }); $( document ).on( "b24-sitebutton-load-widget-callback", function (e, widget){ widget.caption = 'Call title'; });

The same with jQuery

Passing the pre-set values into CRM form

BX.addCustomEvent(document, "b24-sitebutton-form-init", function (e, form){
      form.fields = {
         'values': {
            'LEAD_PHONE': '+87754632212',
            'LEAD_NAME': 'Robert'
         }
      };
});

The same with jQuery
$( document ).on( "b24-sitebutton-form-init", function (e, form){ form.fields = { 'values': { 'LEAD_PHONE': '+87754632212', 'LEAD_NAME': 'Robert' } }; });

Your hello via events

BX.addCustomEvent(document, "b24-sitebutton-load", function (e, instance){
   instance.hello.setConditions([{
      'icon': 'http://crm.bitrix24.com/upload/main/76d/52b.jpg',
      'name': 'Victoria',
      'text': 'Hello! Need any help?',
      'page': '',
      'delay': 1
   }]);
});

The same with jQuery
$( document ).on( "b24-sitebutton-load", function (e, instance){ instance.hello.setConditions([{ 'icon': 'http://crm.bitrix24.com/upload/main/76d/52b.jpg', 'name': 'Victoria', 'text': 'Hello! Need any help?', 'page': '', 'delay': 1 }]); });

The same with jQuery