Difference between revisions of "Event handling"

Revision as of 08:12, 25 August 2009

Group-Office modules can interact with eachother with event handling. For example you might want to do something in a custom module when a particular thing happens in another module.

Some practical examples:

1. The IMAP authentication module checks access when a user logs in.
2. When an order status changes in the webshop of group-office.com, an event handler enables the download for the customer
3. When a password is change in Group-Office. A system account can be updated.
4. etc.

How does it work? I'll explain the IMAP authentication example.

When a user logs in, an event is fired in classes/base/auth.class.inc.php:

$GO_EVENTS->fire_event('before_login', array($username, $password));

The event 'before_login' is fired and event listeners functions are called with the parameters $username and $password

Adding event listeners

To execute code at a particular event you must add event listeners. You can do this in a special function "__on_load_listeners" that must be in the class file "module/<module_id>/classes/<module_id>.class.inc.php". The class name must match the module name. At login time this function is called and you can add the listeners. Listeners are static functions.

The add_listener function takes four arguments:

1. Event name
2. The class file where the function is in
3. The class name where the function is in
4. The class method to call statically

In the following code we add a listener for the "login" and "logout" event.

Just create two folders and one file:

modules/mymodule/classes/mymodule.class.inc.php

in mymodule.class.inc.php put:

class mymodule
{

	public function __on_load_listeners($events){
		$events->add_listener('login', __FILE__, 'mymodule', 'login');
		$events->add_listener('logout, __FILE__, 'mymodule', 'add_user');
	}

	public function  login($username, $password, $user){
		//do something here on login
	} 

	public function  logout($destroyed_session){
		//do something here on logout
	}
} 

So now just before a user is logging in this function is called. The function connects to the IMAP server using the supplied password. If it succeeds it will add a user account and e-mail account or update the password if necessary.

The same could be done with any application/protocol like Joomla, PhpBB, LDAP etc. You'll just have to write it!

Defined events