JDispatcher
From Joomla! Documentation
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.
Contents |
Availability
Defined in
/libraries/joomla/event/dispatcher.php
Extends
Methods
| Method name | Description |
|---|---|
| __construct | Constructor. |
| register | Registers an event handler to the event dispatcher. |
| trigger | Triggers an event by dispatching arguments to all observers that handle the event and returns their values. |
Importing
jimport( 'joomla.event.dispatcher' );
The Event-Dispatcher-Pattern
The Joomla Framework is devided into different tiers (See: Framework). The idea is that business logic and information are capsulated, 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 occures, the event-dispatcher calls all event-handlers that handle that certain event and passes a set of arguments to it.
See also
Examples
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.
