From In-Portal Developers Guide

Обработчик событий
Статьи в этой категории
Event Handlers

The purpose of Event handlers is to handle and process user data submitted through website and passed to PHP. Below you will see the main aspects of programming the event handlers.

Getting Object of Event Caller

• Following code should be used if the object ID is passed in request submitted by the user:

$object =& $event->getObject();

Additionally, this code will load the actual object data using the ID passed in user request.

• Following code should be used if object ID is unknown:

$object =& $event->getObject( Array('skip_autoload' => true) );

This approach is used by OnCreate and OnUpdate events because first one doesn't have an ID (adding new data record), while second can receive more then one (1) object ID at the same time (ie. when you are editing multiple data records).

Getting Form Data

• Following code gets the data submitted through the form (only in case if POST request is used):

$items_info = $this->Application->GetVar( $event->getPrefixSpecial(true) );

Processing Form Data

• In case if only object ID has been passed through the form then $items_info array (see. Getting Form Data) should be used in the following manner:

if ($items_info) {
	list ($id, $field_values) = each($items_info);
	// data processing
}

• In case if request can have multiple object IDs passed, then it's recommended to use the following code:ледующий код:

if ($items_info) {
	foreach ($items_info as $id => $field_values) {
		// data processing
	}
}

Specifying Redirect Template

Right after successful execution and processing of called event, a redirect to current template (if Front-End) or last data grid (in Admin) will take place. In case if custom redirect template needs to be specified, then redirect property of the object should be used:$event:

$event->redirect = 'template_name'; // in-link/links/thankyou

Note that it's a bad practice to hard-code any template names in your PHP code. The best solution would be to pass it through the form which called actual event.

Current pop-up functionality in Admin Console is build in such way that value of redirect property will ignored. Regardless of that Front-End will always use that property. In case if it's needed to change the redirect template for OnCreate or OnUpdate events, then the following code should be used before setting a new value into redirect property.:

$event->SetRedirectParam('opener', 's');

It's not required if other Events are used.

Calling New Event from Event Handler

Following code should be used to call a new event of the same Unit prefix (in other words the same unit):

$event->CallSubEvent('OnSampleEvent');

Following code should be used to call a new event of different Unit prefix:

$this->Application->HandleEvent( new kEvent('prefix.special:OnSampleEvent') );

No need to put a dot (.) if no special been used.

Specifying Permissions for Event Handlers

When you are creating a new event handler which is not part kDBEventHandler class, then access permissions must be specified in kEventHandler::mapPermissions method for you custom event handler to properly execute::

function mapPermissions()
{
	parent::mapPermissions();
	$permissions = Array (
		'OnSampleEvent' => Array ('self' => 'main_permissions', 'subitem' => 'subitem_permissions'),		
	);
 
	$this->permMapping = array_merge($this->permMapping, $permissions);
}

If the Unit Config, which declared the class of that event handler has an [K4:Unit Configs#SubItems|SubItems]] option, then the name of the access rights must be specified in the "self</ code>" key. If this option is not present, then the name of the access rights must be specified in "<code>subitem</ code>" key. If you want to specify multiple access rights at the same time, you need to separate them using a vertical bar ("<code> | </ code>"). In this case, the user will be checked to have at least one of these rights. If event execution requires no permission check at all, then you can simply specify "<code>true</ code>" instead of a string with permission names.

It's prohibited to use any Control Structures in <code>mapPermissions</code> method.

Translated from: revision 1076