Difference between revisions of "Event handling"

Revision as of 19:33, 22 September 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
	}
} 

You need to install your module in Group-Office. When a user logged in and out these functions are called.

You could use this to create authentication bridges for any application/protocol like Joomla, PhpBB, LDAP etc. You'll just have to write it!

Defined events