Difference between revisions of "Event handling"

Revision as of 08:45, 27 April 2011

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 in a simple way

The simplest way to add an event listener is to add a "local_listeners.php" file in the same directory as the config.php file is. This will only work in 3.7.9 and higher. Here's an example file:

<?php
/**
 * This file can be put in the same directory as your config.php file is located.
 * You can add your own listeners to do some actions at particular events.
 */

//Register the listener. This will be fired when a user is added
if(isset($events)){
	$events->add_listener('add_user', __FILE__, '', 'local_add_user_listener');
}

//The function to be called. This example adds a user to the user group
//domain.com. Where domain.com is the domain part of the user's e-mail address.

function local_add_user_listener($user, $password){

	global $GO_CONFIG, $GO_SECURITY;

	//load the group management class
	require_once($GO_CONFIG->class_path.'base/groups.class.inc.php');
	$GO_GROUPS = new GO_GROUPS();

	$arr = explode('@', $user['email']);

	$domain = $arr[1];

	//get the group.
	$group = $GO_GROUPS->get_group_by_name($domain);
	if(!$group){
		//group doesn't exist so create it.
		$group_id = $GO_GROUPS->add_group(1, $domain, 0, $GO_SECURITY->get_new_acl('groups'));
	}else
	{
		$group_id = $group['id'];
	}

	//add the user to the group
	$GO_GROUPS->add_user_to_group($user['id'], $group_id);

	//load the security management class
        require_once($GO_CONFIG->class_path.'base/security.class.inc.php');
        $GO_SECURITY = new GO_SECURITY();
   
        //add user is visible to group
        $GO_SECURITY->add_group_to_acl($group_id, $user['acl_id']);

}

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