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)
 
(7 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==
+
−
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 "login" and "logout" event.
+
−
 
+
−
Just create two folders and one file:
+
−
 
+
−
<pre>
+
−
modules/mymodule/classes/mymodule.class.inc.php
+
−
</pre>
+
−
 
+
−
in mymodule.class.inc.php put:
+
−
 
+
−
<pre>
+
−
class mymodule
+
−
{
+
−
 
+
−
public function __on_load_listeners($events){
+
−
$events->add_listener('login', __FILE__, 'mymodule', 'login');
+
−
$events->add_listener('logout', __FILE__, 'mymodule', 'add_user');
+
 
}
 
}
  
−
public static function login($username, $password, $user){
+
public static function doSomething(){
−
//do something here on login
+
//do something with the file module here
−
}
+
−
 
+
−
public static function logout($destroyed_session){
+
−
//do something here on logout
+
 
}
 
}
−
}  
+
}
 
</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"