Joomla! Documentation™

The "API16" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

JDispatcher is a class to handle the dispatching of events. Together with the JEvent class, it implements the base funcitonality for the Event-Dispatcher-Pattern.

The Event-Dispatcher-Pattern

The Joomla Framework is divided into different tiers (See: Framework). The idea is that business logic and information are encapsulated, so they can be changed, and replaced without affecting other parts of the application. Sometimes however, you need to access information from other parts of the application. The Registry pattern can help you with that (See: JRegistry). And sometimes you want other parts of the application to be automatically informed, once an event anywhere within the application occurs. This is where the Event-Dispatcher-Pattern comes into play.

The pattern allows you to register event-handlers for a certain event at a global event-dispatcher. Once the event occurs, the event-dispatcher calls all event-handlers that handle that certain event and passes a set of arguments to it.

Defined in

libraries/joomla/event/dispatcher.php

Methods

Method name	Description
getInstance	Returns the global Event Dispatcher object, only creating it if it doesn't already exist.
register	Registers an event handler to the event dispatcher
trigger	Triggers an event by dispatching arguments to all observers that handle the event and returning their return values.

Importing

jimport( 'joomla.event.dispatcher' );

Code Examples

Example

Let's think of an event, that could affect different parts of your application... To keep it simple, we say that we create an onEmailChange event, that is triggered once the user changes his email address. When he does that, we want to display the change to the screen, but we also want to store it to the database. We also know, that there might be some components out there, who would like to implement their own functionality, once the useer changes his email-address.

/*
 * Let's define our concrete Event Handlers. One for the display, one for 
 * database storage
 *
 * The concrete Event Handlers only have to implement the functionality that should
 * be triggered once the event happens. All underlying functionality is implemented
 * by the abstract JEvent and JObserver classes.
 */
class EventHandlerEcho extends JEvent {
public function onEmailChange($user, $oldEmail, $newEmail){
echo $user->name . 'has changed his or her email address: <br/>';
echo 'OldEmail: '.$oldEmail.'<br/>';
echo 'NewEmail: '.$newEmail;
}
}
class EventHandlerDB extends JEvent {
public function onEmailChange($user, $oldEmail, $newEmail){
$db = JFactory::getDBO();
$sql = "UPDATE #__users SET email = ".$db->quote($newEmail)." " .
"WHERE id = " . $db->quote($user->id);
$db->setQuery($sql);
$db->query();
}
}


//Let's get the global dispatcher
$dispatcher = JDispatcher::getInstance();

/*
 * Let's construct the event handlers
 *
 * Since our Eventhandlers are decendents of JEvent, and JEvent is a decendent of JObserver the constructor
 * automatically attaches the eventhandler object to the dispatcher(which is a JObservable descendant).
 * This means when the Event Handlers are initialized they are automatically added to the observer stack of
 * the dispatcher.
 */
new EventHandlerEcho($dispatcher);
new EventHandlerDB($dispatcher);

After the Event Handlers have been created and added to the dispatcher, the event can be triggered from anywhere in the application. This could be in another module, another component, within the framework or even in another plugin.

 //Access the global dispatcher
 $dispatcher = JDispatcher::getInstance();
 
 /*
  * If we wanted, we could see, that our two Event handlers have been added to
  * observer stack of the dispachter before
  */

 var_dump($dispatcher->_observers);

 //Instead we want to trigger the event, and see what happens
 $user = JFactory::getUser();
 $oldEmail = 'old@email.com';
 $newEmail = 'new@email.com';

 $dispatcher->trigger('onEmailChange', array($user, $oldEmail, $newEmail));

 /*
  * Both event handlers have been triggered.
  * The email addresses have been displayed. The new one 
  * has been stored to the database
  */

Other components can now create their own concrete Event Handlers for the onEmailChange event and register it to the dispatcher. They will automatically be triggered once the event occurs anywhere in the application.

This example was originally contributed by User:Batch1211.

Chris Davenport 13:26, 17 April 2011 (CDT) Edit comment