API15:JEvent

The "API15" 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.

Defined in

libraries/joomla/event/event.php

Methods

Method name	Description
JEvent	Constructor
update	Method to trigger events

Importing

jimport( 'joomla.event.event' );

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:31, 17 April 2011 (CDT) Edit comment