Event handling

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);

}

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

Module	Event name	Parameters	Description
Framework	before_login	username, password	Fires just before a user logins. Useful for authentication bridges.
Framework	login	username, password, user (array with all db fields)	Fires when a user logs in successfully
Framework	logout	session The old $_SESSION['GO_SESSION'] var that was destroyed	Fires when a user logs out
Framework	update_user	user: array with all db fields	Fires when a user is updated.
Framework	before_add_user	user: array with all db fields	Fires just before a user is added.
Framework	add_user	user: array with all db fields	Fires after a user is added.
Framework	user_delete	user: array with all db fields	Fires after a user is deleted.
Framework	install_module	module: array with module db fields	Fires when a module is installed. Eg. You could enable extra functionality in another module when a module is installed
Framework	save_settings	None, but you can use the $_POST array.	Fires when a the user settings are updated. Each module can add it's own panels to the settings dialog. Through this event you can update the module settings.
Framework	load_settings	response: The JSON response to the client. Useful for adding settings to the array.	Fires when a the user settings are loaded. Each module can add it's own panels to the settings dialog. Through this event you can update the module settings.
Framework	reminder_dismissed	reminder: array with reminder db fields	Fires when a reminder is dismised. Eg. When a reminder of a recurring event is dismissed, a new reminder is created for the next occurrence.
Framework	require_language_file	module_id: name of the module, $language: the language code requested	Fires when a language file is required. Useful for overridding some language vars with another module. This one was added at 22-09-2009 in version 3.3 and a lot of older files don't use the require_language_file function yet.
Tools	check_database	none	Perform a database check on your module.
Billing	order_status_change	order, new_status, old_status	Fires when an order changes to another status