**********************************************************
    
    event.txt
    
    $Id$
    
    @author gERD Schaufelberger <gerd@exit0.net>
    @copyright 2004/2005 Wombat Web Bench
    @link http://wombat.exit0.net
    @package wombat
    @subpackage manual
    
**********************************************************

WOMBAT APPLICATION EVENTS
=========================

As metioned in "manual.txt" events in the scope of Wombat are applcation level
incidents. In other words, each event is potential interesting for site
administrator(s). So they do not represent some weird case that happens in the
deep of your code. An event is more likely to be a "real world happening", e.g.
an new page was created (using the CMS). 

Therefore those events happen all the time, still the way how to react on such
an event is site specific. Hence events and event handling is divided into three
parts: 

Trigger Event
-------------
Of course, events happen within an application and must be foreseen and
implementad by the application's developer. The first part is to trigger an
event in your code: 

-----------------8<-----------------8<-----------------8<-----------------
 // trigger a very basic event
 wbEvent::trigger( 'game:play', _( 'Look, someone plays the game!' );

 // it is also possible to pass additional data and even information, the
 // administration area uses to create hyper links
 $data = array( 'level' => 42, 'player' => 'Joe Doe' );
 $link = array( 'app' => 'Game/Over', 'result' => 'lost'  );
 wbEvent::trigger( 'myApp:gameover', _( '"{PLAYER} lost at level {LEVEL}"',
                   $data, $link 
                 );
-----------------8<-----------------8<-----------------8<-----------------

You might wonder where the wbEvent class comes from. WEll, don't bother about
that. It should be included automatically and the static function should be
ready to use whenever you need it. 

Actually, the class wbEvent (implemented in "include/wbEvent.php" )is two in
one: At first it provides a static interface to trigger a events (see above). At
the same time an instacicated object of wbEvent is an event itself! (A container
class that contains the event's data.)

Event Handling
--------------
The handling of the event is done by the event controller: wbEventController
(see class in "include/wbEventController.php"). Well, this is only half the
truth. The event controller is not capable to handle any event. Instead it looks
up the event configuration and delegates the event handling to specialized event
handler. 

This is where the site's maintainer comes in: "conf/event.xml" and files in
"conf/event/" need to be mendet to suit the site's need. 

Example of "conf/event.xml"
-----------------8<-----------------8<-----------------8<-----------------
<?xml version="1.0" encoding="iso-8859-1" ?>
<configuration>
    <xinc href="/definesEvent.xml" once="yes" />

    <!-- may hold many events -->
    <e:events>
        <!--
          Each event section contains a trigger and an action
        -->
        <e:event>
            <!-- 
              a trigger is an reguler expression that must match to an event's
              id to execute the action below.
            -->
            <e:trigger>/site:auth:*/</e:trigger>
            <!--
              in case the expression matches, the action: "__ignore" will be
              executed. As you might guess, "__ignore" stands for "do nothing"
            -->
            <e:action>__ignore</e:action>
        </e:event>
        <e:event>
            <e:trigger>/site:cms:activated:lead/</e:trigger>
            <!-- 
              This event will trigger the action named "cms"
              What happens there is defined in "conf/event/cms.xml"
            -->
            <e:action>cms</e:action>
        </e:event>
        <e:event>
            <e:trigger>/.*/</e:trigger>
            <e:action>default</e:action>
        </e:event>
    </e:events>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

Example event action definition: "conf/event/cms.xml"
-----------------8<-----------------8<-----------------8<-----------------
<?xml version="1.0" encoding="iso-8859-1" ?>
<configuration>
    <xinc href="/definesEvent.xml" once="yes" />

    <!-- Tell what actions must be performed on such an event -->
    <act:actions>
        <act:action>
            <!-- Each action must contain an event handler -->
            <act:handler>Ticket</act:handler>
            <!-- Optionally parameters may be passed to the event handler -->
            <act:params>
                <act:param name="title">Translate to German</act:param>
                <act:param name="status">assigned</act:param>
                <act:param name="type">task</act:param>
                <act:param name="owner">1</act:param>
                <!--<act:param name="rcpts">2,3,4,5</act:param>-->
            </act:params>
        </act:action>
        <act:action>
            <act:handler>Log</act:handler>
            <act:params>
                <act:param name="logid">event</act:param>
            </act:params>
        </act:action>
    </act:actions>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

Event handler
-------------
As said above, the event controller itself is not capable to handle events, it
just figures out whose handlers will be called. Event handler are plugable
modules located in "include/wbEventHandler/". Each handler derives from the base
class wbEventHandler and implements the processing function.