From http://wiki.vtiger.com/archives

Creating Events for Vtiger Actions

When you want to extend vtiger, for example add email notification for a particular action, you end up needing to modify core vtiger code to add your functionality. The event api provides a simple way of adding actions without making any modification to vtiger.

The event handler interface

To add a new event handler you will need to define a class that extends the VTEventHandler abstract class.

SimpleHandler.php

class SimpleHandler extends VTEventHandler{

               public function handleEvent($handlerType, $data){

                        echo "This handler has been called for the $name event";

               }

}

Registering a handler

registerHandler is method of the class VTEventsManager. You can use it to register a handler you have created to be executed when a certain event is fired. It accepts four parameters.

• $eventName: The name of the event. This could be, for example, 'vtiger.entity.beforesave'

• $filePath: The path to the file in which the handler class is defined. This is relative to the base of the vtiger install, for example, 'include/changename/ChangeName.php'

• $className: The name of the handler class itself.

• $condition: A condition which must evaluate to true for the event to trigger. This is an optional parameter.

Example:

require 'include/events/include.inc';

$em = new VTEventsManager($adb);

$em->registerHandler($eventName, $filePath, $className);

It is also possible for you to specify conditions that restrict when the handler will be executed. You might want an event to be fired only for changes in a particular module. Currently the conditions are restricted to selecting module names

Example:

require 'include/events/include.inc';

$em = new VTEventsManager($adb);

$em->registerHandler($eventName, $filePath, $className, 'moduleName in ['Contacts', 'Accounts']);

In the above example the event will only be triggered if the triggering entity is of the module Contacts or Accounts.

Supported events

vtiger.entity.beforesave

This event is fired before an entity is saved. You will be passed a VTEntityData object representing the saved entity. It should be noted that new objects will not have an id. You can modify the contents of $entityData, this will be reflected in the save operation, some care should be taken as it is possible to corrupt the entity.

The following event always changes the assigned to id to admin on save. This i will make sure that the admin will be the owner of all new or saved entities.

class OwnerIsAdminEventHandler extends VTEventHandler{

         public function handleEvent($handlerType, $entityData){

                   $entityData->set('assigned_to_id', 1);

         }

}

As the content of the entity can be changed before saving, there are two sub events related to vtiger.entity.beforesave

vtiger.entity.beforesave.modifiable

This is fired before the beforesave event. Use this event if you want to change the contents of the entity object before saving it.

vtiger.entity.beforesave.final

This is fired after the beforesave event. This can be used to get the exact content of the entity before saveing it.

vtiger.entity.aftersave

This event is fired after an entity is saved. This too provides a VTEntityData object. Here's a simple example that logs the modified time when an entity is saved.

LogModifiedTimeHandler.php

class LogModifiedTimeHandler extends VTEventHandler{

         public function handleEvent($handlerType, $entityData){

                  global $log; $log->debug($data->getModuleName()":".$data->getId().":".$data->get('modifiedtime'));

         }

}

VTEntityData Objects

The VTEntityData object provides access to a vtiger entity objects. It implements the following methods

getModuleName

Returns the module name of the entity.

getId

Returns id of the entity, this will return null if the id has not been saved yet.

getData

Returns the fields of the entity as an array where the field name is the key and the field's value is the value.

isNew

Returns true if new record is being created, false otherwise.

Example: Event handlers add/update distinction

Modifying the fields of the entity object

In certain events, for example, 'vtiger.entity.beforesave.modifiable' it is possible to modify the entity, so that it gets saved. eg, for an VTEntityData obkect called $data you can change the field simple_field to the value 'value' using the following code.

$data->set('simple_field', 'value');

Now the entity will get saved with simple_field saved as 'value'.