239: Add system/hook to enable adding a method on an existing module

Detailed Explanation

coreBOS Events, Links and Hooks

Explanation

coreBOS permits the implementor/developer to add functionality to the existing application in three different ways: Events, Links and Hooks.

Events occur at special points in the execution of the application and the eventing system permits us to insert our own code and functionality at these points, while Hooks permit us to enhance the existing functionality of objects and modules as if the code had always been there. The difference is very subtle and basically resides in the way the developer's new code must be added for it to be functional. The Events system requires the developer to create a new class that extends the base event class, add the functionality to this class and register it into the system for it to be called, while the Hooks system will require adding specifically named functions and files to certain places for it to be found and executed accordingly.

Links are a mix between Events and Hooks as they permit us to load specific code as if it had always been there, including buttons and links, but they require to be registered in the application to be loaded.

As I have already said the difference between events and hooks is very subtle, even some types of links are hard to distinguish from hooks. In the end they are simply different ways of changing the default behavior of the application and you need to choose which one you need depending on the goal of your change.

If you read the official definition of a hook or a webhook, you can see that there is really no distinction, they are all ways to change the behavior of the application. coreBOS makes a distinction based on the way you insert the hook into the application, in other words, depending on the steps the programmer has to take to get the hook into the system. Looking at it that way we have:

Events: require that you create a specific class and launch some specific code to register the new functionality
Links: require that you create a URL and register the action using some specific code
Hooks: require that you create some specific code and do some steps that do not fall into the previous two categories

So, in the end the only difference is how you insert your code into the application depending on what you need to hook into.

EVENTS: Types and usage

When you want to extend coreBOS, you can use the event API, which provides a simple way of adding actions without making any modification to the base code files.

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

class SimpleHandler extends VTEventHandler{
 public function handleEvent($name, $data){
  global $log;
  $log->fatal("This handler has been called for the $name event and prints this message to the log file.");
 }
}

Then you have to register the handler in the system with this code:

require 'include/events/include.inc';
$em = new VTEventsManager($adb);
$em->registerHandler($eventName, $filePath, $className);

this can be done in an individual one-shot script or added to the vtlib_handler() method to be executed when installing a new module or extension.

The eventing system supports two types: actions and filters.

An action will be called to do some tasks without returning a value. Actions use the handleEvent($handlerType, $parameter) method in the Event class, which must exist.

A filter will be called to do some tasks and will return a value, with which some action will be done in the application. Normally the returned value will be the same $parameter with some modifications. Filters use the handleFilter($handlerType, $parameter) method, which will return the new $parameter value.

Event Launching

Events are launched for ALL modules and executed ALWAYS.

That means that we must encapsulate or protect our event code inside a condition that makes sure we are in the correct module. Looking at the different examples you can see that almost all of them start with a

"if ($moduleName=='whatever')"

This is the "de facto" standard

It also means that we have to be especially careful with the things that are done, our code has to be fast and efficient in order to not block the user experience, and also resistant to errors.

Although this may seem an incorrect approach, experience shows that it is extremely powerful for many situations.

That said, the "save" events (and some others) support conditions directly in their definition and also dependency launching. These events have a "condition" column and a "dependent on" column.

The condition column can accept expressions following this syntax:

he accepted grammer is:
 *  comparision | inclause
 * where
 *   comparision is: SYMBOL == value
 *   inclause is: SYMBOL IN listelement
 *   listelement is: [ value (, value )* ]
 *   SYMBOL can be: (a fieldname) | moduleName | id

for example, we can use expressions like:

moduleName in ['Contacts', 'Potentials']
moduleName == 'Accounts'
employees == '131'
id == '74'
rating in ['Active','Acquired']

The dependent column is a JSON encoded array of event handlers that must be executed before the one being defined. So you can ask the system to execute your event after some other event has finished.

Supported events

Note that inside each event type the set of active events will be executed in order of creation (sorted by their eventid) as can be read here.

vtiger.entity.beforesave.modifiable This event is an internal event that is launched before any other event when an entity is saved. It should not be used.

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 may not have an id (if it is being created). You can modify the contents of VTEntityObject.

vtiger.entity.beforesave.final This event is an internal event that is launched after all other BEFORESAVE events when an entity is saved. It should not be used.

vtiger.entity.aftersave.first This event is fired after an entity is saved, but before workflows and standard aftersave events but the local save_module() method of the object has been executed.

vtiger.entity.aftersave This event is fired after an entity is saved, even the local save_module() method of the object has been executed. This also provides a VTEntityData object.

vtiger.entity.aftersave.final This event is an internal event that is launched after all other SAVE events have occurred. It should not be used.

vtiger.entity.beforedelete This event is fired before an entity is deleted. You will be passed a VTEntityData object representing the entity that will be eliminated.

vtiger.entity.afterdelete This event is fired after an entity is deleted. You will be passed a VTEntityData object representing the deleted object. Be careful as this object can no longer be referenced using the applications' methods.

vtiger.entity.afterrestore This event is fired after an entity has been recovered from the Recycle Bin. You will be passed a VTEntityData object representing the entity that has been restored.

vtiger.entity.beforegroupdelete This event is fired before deleting a group. You will be passed an array with this structure:

array(
 'groupid' => $groupId; // Group Id to be deleted:: integer
 'transferToId' => $transferId; // Id of the group/user to which record ownership is to be transferred:: integer
);

corebos.header.premenu Will be triggered in the header of coreBOS, right after the announcement marquee has been rendered and before the application menu. It supports a generic way of sending some output before the menu.