Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

Developer Network License

The Joomla! Developer Network content is © copyright 2006 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5
Source code for file /joomla/application/event.php

Documentation is available at event.php

  1. <?php
  2. /**
  3. * @version        $Id: event.php 6678 2007-02-19 09:06:14Z louis $
  4. * @package        Joomla.Framework
  5. * @subpackage    Application
  6. * @copyright    Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
  7. * @license        GNU/GPL, see LICENSE.php
  8. *  Joomla! is free software. This version may have been modified pursuant
  9. *  to the GNU General Public License, and as distributed it includes or
  10. *  is derivative of works licensed under the GNU General Public License or
  11. *  other free or open source software licenses.
  12. *  See COPYRIGHT.php for copyright notices and details.
  13. */
  14.  
  15. // Check to ensure this file is within the rest of the framework
  16. defined('JPATH_BASE') or die();
  17.  
  18. jimport('joomla.base.observer');
  19.  
  20. /**
  21.  * Class to handle dispatching of events.
  22.  *
  23.  * This is the Observable part of the Observer design pattern
  24.  * for the plugin architecture.
  25.  *
  26.  * @package     Joomla.Framework
  27.  * @subpackage    Application
  28.  * @since    1.5
  29.  * @see        JPlugin
  30.  * @link http://dev.joomla.org/component/option,com_jd-wiki/Itemid,31/id,tutorials:plugins/ Plugins tutorial
  31.  */
  32. class JEventDispatcher extends JObservable
  33. {
  34.     /**
  35.      * Constructor
  36.      *
  37.      * @access    protected
  38.      */
  39.     function __construct()
  40.     {
  41.         parent::__construct();
  42.     }
  43.  
  44.     /**
  45.      * Returns a reference to the global Event Dispatcher object, only creating it
  46.      * if it doesn't already exist.
  47.      *
  48.      * This method must be invoked as:
  49.      *         <pre>  $dispatcher = &JEventDispatcher::getInstance();</pre>
  50.      *
  51.      * @access    public
  52.      * @return    JEventDispatcher    The EventDispatcher object.
  53.      * @since    1.5
  54.      */
  55.     function & getInstance()
  56.     {
  57.         static $instance;
  58.  
  59.         if (!is_object($instance)) {
  60.             $instance = new JEventDispatcher();
  61.         }
  62.  
  63.         return $instance;
  64.     }
  65.  
  66.     /**
  67.      * Registers an event handler to the event dispatcher
  68.      *
  69.      * @access    public
  70.      * @param    string    $event        Name of the event to register handler for
  71.      * @param    string    $handler    Name of the event handler
  72.      * @return    void 
  73.      * @since    1.5
  74.      */
  75.     function register($event, $handler)
  76.     {
  77.         // Are we dealing with a class or function type handler?
  78.         if (function_exists($handler))
  79.         {
  80.             // Ok, function type event handler... lets attach it.
  81.             $method = array ('event' => $event, 'handler' => $handler);
  82.             $this->attach($method);
  83.         }
  84.         elseif (class_exists($handler))
  85.         {
  86.              //Ok, class type event handler... lets instantiate and attach it.
  87.             $this->attach(new $handler($this));
  88.         }
  89.         else
  90.         {
  91.             JError::raiseWarning('SOME_ERROR_CODE', 'JEventDispatcher::register: Event handler not recognized.', 'Handler: '.$handler );
  92.         }
  93.     }
  94.  
  95.     /**
  96.      * Triggers an event by dispatching arguments to all observers that handle
  97.      * the event and returning their return values.
  98.      *
  99.      * @access    public
  100.      * @param    string    $event            The event name
  101.      * @param    array    $args            An array of arguments
  102.      * @param    boolean    $doUnpublished    [DEPRECATED]
  103.      * @return    array    An array of results from each function call
  104.      * @since    1.5
  105.      */
  106.     function trigger($event, $args = null, $doUnpublished = false)
  107.     {
  108.         // Initialize variables
  109.         $result = array ();
  110.  
  111.         /*
  112.          * If no arguments were passed, we still need to pass an empty array to
  113.          * the call_user_func_array function.
  114.          */
  115.         if ($args === null) {
  116.             $args = array ();
  117.         }
  118.  
  119.         /*
  120.          * We need to iterate through all of the registered observers and
  121.          * trigger the event for each observer that handles the event.
  122.          */
  123.         foreach ($this->_observers as $observer)
  124.         {
  125.             if (is_array($observer))
  126.             {
  127.                 /*
  128.                  * Since we have gotten here, we know a little something about
  129.                  * the observer.  It is a function type observer... lets see if
  130.                  * it handles our event.
  131.                  */
  132.                 if ($observer['event'] == $event)
  133.                 {
  134.                     if (function_exists($observer['handler']))
  135.                     {
  136.                         $result[] = call_user_func_array($observer['handler'], $args);
  137.                     }
  138.                     else
  139.                     {
  140.                         /*
  141.                          * Couldn't find the function that the observer specified..
  142.                          * wierd, lets throw an error.
  143.                          */
  144.                         JError::raiseWarning('SOME_ERROR_CODE', 'JEventDispatcher::trigger: Event Handler Method does not exist.', 'Method called: '.$observer['handler']);
  145.                     }
  146.                 }
  147.                 else
  148.                 {
  149.                      // Handler doesn't handle this event, move on to next observer.
  150.                     continue;
  151.                 }
  152.             }
  153.             elseif (is_object($observer))
  154.             {
  155.                 /*
  156.                  * Since we have gotten here, we know a little something about
  157.                  * the observer.  It is a class type observer... lets see if it
  158.                  * is an object which has an update method.
  159.                  */
  160.                 if (method_exists($observer, 'update'))
  161.                 {
  162.                     /*
  163.                      * Ok, now we know that the observer is both not an array
  164.                      * and IS an object.  Lets trigger its update method if it
  165.                      * handles the event and return any results.
  166.                      */
  167.                     if (method_exists($observer, $event))
  168.                     {
  169.                         $args['event'] = $event;
  170.                         $result[] = $observer->update($args);
  171.                     }
  172.                     else
  173.                     {
  174.                         /*
  175.                          * Handler doesn't handle this event, move on to next
  176.                          * observer.
  177.                          */
  178.                         continue;
  179.                     }
  180.                 }
  181.                 else
  182.                 {
  183.                     /*
  184.                      * At this point, we know that the registered observer is
  185.                      * neither a function type observer nor an object type
  186.                      * observer.  PROBLEM, lets throw an error.
  187.                      */
  188.                     JError::raiseWarning('SOME_ERROR_CODE', 'JEventDispatcher::trigger: Unknown Event Handler.', $observer );
  189.                 }
  190.             }
  191.         }
  192.         return $result;
  193.     }
  194. }
  195. ?>
Documentation generated on Mon, 05 Mar 2007 20:57:58 +0000 by phpDocumentor 1.3.1