Actions

API15

Difference between revisions of "JDispatcher"

From Joomla! Documentation

(New page: <span class="editsection" style="font-size:76%;"> <nowiki>[</nowiki>Edit Descripton<nowiki>]</nowiki> </span> {{Description:JDispatcher}} ===Defined in==...)
 
m (fixing)
 
(One intermediate revision by one user not shown)
Line 24: Line 24:
 
|Triggers an event by dispatching arguments to all observers that handle the event and returning their return values.
 
|Triggers an event by dispatching arguments to all observers that handle the event and returning their return values.
 
|}
 
|}
 +
 
===Importing===
 
===Importing===
 
<source lang="php">jimport( 'joomla.event.dispatcher' );</source>
 
<source lang="php">jimport( 'joomla.event.dispatcher' );</source>
Line 36: Line 37:
 
<dpl>
 
<dpl>
 
  noresultsheader=\n
 
  noresultsheader=\n
 +
namespace=CodeExample
 
  category=JDispatcher
 
  category=JDispatcher
 
  category=CodeExample
 
  category=CodeExample

Latest revision as of 21:13, 4 July 2013

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

[Edit Descripton] 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

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
__construct Constructor
getInstance Returns a reference to 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' );

[Edit See Also] SeeAlso:JDispatcher

Examples

<CodeExamplesForm />

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