Bitrix Framework

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;
   }
}