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
(→‎Defined events)
 
(13 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>
+
−
$GO_EVENTS->fire_event('before_login', array($username, $password));
+
−
</pre>
+
−
 
+
−
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:
+
−
 
+
−
# Event name
+
−
# The class file where the function is in
+
−
# The class name where the function is in
+
−
# The class method to call statically
+
−
 
+
−
In the following code we add a listener for the "before_login" event.
+
  
 
<pre>
 
<pre>
−
class imapauth
+
class GO_Myevent_MyeventModule extends GO_Base_Module{
−
{
+
−
var $config;
+
 
 
−
public function __on_load_listeners($events){
+
public static function initListeners() {
−
$events->add_listener('before_login', __FILE__, 'imapauth', 'before_login');
+
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 before_login($username, $password)
 
−
{
 
 
 
−
...
+
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
 
}
 
}
 
}
 
}
 
</pre>
 
</pre>
  
−
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.
+
After creating new listeners you must reload Group-Office so it will call the initListeners function.
−
 
+
−
The same could be done with 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.
+
−
|-
+
−
| 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 09: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"