EventHandler Module

To get a better way to implement enhanced functions into the VtigerCRM, we created a free Event Handling module you could use to get a safe way to extend VtigerCRM.
If you install this module, you will not get any problems, because itself does absolutely nothing.
The task of this module is only to provide a fast interface by these functions:

EventHandler_Module_Model::do_filter(..)

and

EventHandler_Module_Model::do_action(..)

We add these functions in source, where we want to add custom code to prevent huge modifications in core code to have a layer between the custom code and the core code. This will heavily improve the ability to migrate your custom code to later versions.

If you know other plugin system, like WordPress CMS, you also know, what these functions do.

If you want to attach to an Event, this is done with the internal EventHandler.
Do it like this:

// Example from our Colorizer module

// Load Database Connection if not already done
$adb = PearDatabase::getInstance();

// Create internal EventsManager object
$em = new VTEventsManager($adb);

// Register your EventHandler
$em->registerHandler('vtiger.filter.listview.querygenerator.before', 'modules/Colorizer/ColorizerEventHandler.php', 'ColorizerEventHandler');

The registerHandler function have this parameters:

The function itself have more parameters, but they are not helpful.
This registration must only done once, for example during module setup.

Now you need to create your EventHandler class. Name the class, like you define during your registration. (In my next Example ColorizerEventHandler)
There have to be 2 functions that relate to what you want to handle.

A handleEvent($hook, $data) function or/and a handleFilter($hook, $parameter, …) function. See in next example:

<?php

class ColorizerEventHandler {
  public function handleEvent($hook, $data){
// ....
  }

  public function handleFilter($hook, $parameter) {
// ...
    return $parameter;
  }
}

If you want to be able to handle multiple different filter with the handleFilter function, only define the $parameter Parameter, because this is available in any case.

To access custom parameter, use something like this:

$additionalParameter = func_get_arg(2);
// The first additional parameter is the index 2

The $hook variable contain the name of the hook, currently executed.

If you have experience with your database, you do not need to call the registerHandler function, but also could directly insert your event into the database.

Insert a new row within table vtiger_eventhandlers with correct event_name, handler_path, handler_class and 1 as “is_active” column.
But do not forget to increase the sequence in vtiger_eventhandlers_seq, because otherwise you get problems during next module setup, which also attach an event.

EventHandler_Module_Model::do_action("$actionName", [$parameter])

$actionName is the name of the hook you define and, by this action name other plugins could attach themself.
This function is internally handled by the core EventHandler.

You could set up to 1 parameter, which is also available in Plugins. This function returns nothing. This function could be used for example to mark initial page loading.

EventHandler_Module_Model::do_filter("$actionName", $parameter1, [$parameter2, [$parameter3, ...]])

EventHandler_Module_Model::do_filter(array($actionName1, $actionNameN,...), $parameter1, [$parameter2, [$parameter3, ...]])

This function provide a filter interface, where you set a $parameter1, which could be modified by plugins.
Like the do_action function you have an $actionName, which define the name of this hook. But this function, in contrast to do_action, is also able to handle multiple hook-names in an array, which are executed one after the other from 1 to N.
You must provide a $parameter1, which is filtered by plugins. Other then this, you are able to set an unlimited number of parameters, which are also given to plugins.

For example you could use this function to be able to modify a SQL Query, before vTiger execute it.

Example where we use the multiple hooks is to provide a general hook, together with a module specific one. Then you are able to hook only into the module you need.
Here we have an example, where we modify the QueryGenerator in general ListView file, before the QueryGenerator is set into ListView model. One time with a general hook and second with a module specific hook name.

// Taken from file modules/Vtiger/models/ListView.php ~Line 234

$this->set(
	'query_generator',
	EventHandler_Module_Model::do_filter(
		array(
			'vtiger.filter.listview.querygenerator.before',
			'vtiger.filter.listview.'.strtolower($moduleName).'.querygenerator.before'
		),
		$this->get('query_generator'),
		$pagingModel
	)
);

You could attach to all modules, if you attach to hook vtiger.filter.listview.querygenerator.before. But you are also able to only modify the ListView of Accounts module, if you attach to vtiger.filter.listview.accounts.querygenerator.before

In this example the query generator is the parameter, which could be modified.  The paging model is set as additional parameter.

The module is hosted on GitHub, where you also could see the Source code.

Download for Vtiger 6

Download for Vtiger 7