This manual is deprecated. Please visit https://groupoffice.readthedocs.io for the latest documentation.

Difference between revisions of "Event handling"

From Group-Office Groupware and CRM Documentation
Jump to: navigation, search
(→‎Adding event listeners in a simple way)
 
(5 intermediate revisions by one other user not shown)
Line 1: Line 1:
−
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.  
+
Group-Office fires event on certain actions. You can attach your own functions to do specific actions on these events. To do this create a new module.
  
−
Some practical examples:
+
eg. modules/myevent.
  
−
# The IMAP authentication module checks access when a user logs in.
+
Inside this folder create the file MyeventModule.php:
−
# When an order status changes in the webshop of group-office.com, an event handler enables the download for the customer
+
−
# When a password is change in Group-Office. A system account can be updated.
+
−
# 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:
+
  
 
<pre>
 
<pre>
−
$GO_EVENTS->fire_event('before_login', array($username, $password));
+
class GO_Myevent_MyeventModule extends GO_Base_Module{
−
</pre>
+
 +
public static function initListeners() {
 +
GO_Files_Model_File::model()->addListener('save', 'GO_Myevent_MyeventModule', 'save');
 +
GO_Files_Model_File::model()->addListener('delete', 'GO_Myevent_MyeventModule', 'delete');
 +
 +
//attaching to a controller works a bit different
 +
$c = new GO_Core_Controller_Maintenance();
 +
$c->addListener('someAction', 'GO_Myevent_MyeventModule', 'doSomething');
 +
}
 +
 +
public static function save(&$file){
 +
//do something with the file module here
 +
}
  
−
The event 'before_login' is fired and event listeners functions are called with the parameters $username and $password
+
public static function delete(&$file){
 +
//do something with the file module here
 +
}
  
−
==Adding event listeners in a simple way==
+
public static function doSomething(){
−
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:
+
//do something with the file module here
−
 
+
−
<pre>
+
−
<?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);
 
−
 
 
}
 
}
 
</pre>
 
</pre>
  
−
You need to '''install your module''' in Group-Office. When a user logged in and out these functions are called.
+
After creating new listeners you must reload Group-Office so it will call the initListeners function.
−
 
+
−
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==
+
=Standard events=
 +
Every model that is derived from GO_Base_Db_ActiveRecord has a "save" and "delete" event. They listeners will be called with the model as the first argument.
  
−
{|cellpadding="3" cellspacing="0" border="1"
+
Every controller that is derived from GO_Base_Controller_AbstractModelController has a "submit", "load", "display" and "delete" event. They are all called with these parameters: $controller, $response,$model,$params,$modifiedAttributes
−
! 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
+
−
|}
+

Latest revision as of 10:21, 26 July 2012

Group-Office fires event on certain actions. You can attach your own functions to do specific actions on these events. To do this create a new module.

eg. modules/myevent.

Inside this folder create the file MyeventModule.php: 

class GO_Myevent_MyeventModule extends GO_Base_Module{	
	
	public static function initListeners() {
		GO_Files_Model_File::model()->addListener('save', 'GO_Myevent_MyeventModule', 'save');
		GO_Files_Model_File::model()->addListener('delete', 'GO_Myevent_MyeventModule', 'delete');
		
		//attaching to a controller works a bit different
		$c = new GO_Core_Controller_Maintenance();
		$c->addListener('someAction', 'GO_Myevent_MyeventModule', 'doSomething');
	}
	
	public static function save(&$file){
		//do something with the file module here		
	}

	public static function delete(&$file){
		//do something with the file module here		
	}

	public static function doSomething(){
		//do something with the file module here		
	}
}

After creating new listeners you must reload Group-Office so it will call the initListeners function.

Standard events

Every model that is derived from GO_Base_Db_ActiveRecord has a "save" and "delete" event. They listeners will be called with the model as the first argument.

Every controller that is derived from GO_Base_Controller_AbstractModelController has a "submit", "load", "display" and "delete" event. They are all called with these parameters: $controller, $response,$model,$params,$modifiedAttributes

Retrieved from "http://www.group-office.com/w/index.php?title=Event_handling&oldid=2878"