[Summary view] [Print] [Text view]

   1  <?xml version='1.0' encoding='utf-8' ?>
   2  <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   3  <!ENTITY % BOOK_ENTITIES SYSTEM "Developers_Guide.ent">
   4  %BOOK_ENTITIES;
   5  ]>
   6  <chapter id="dev.events">
   7      <title>Event System</title>
   8  
   9      <sect1 id="dev.events.concepts">
  10          <title>General Concepts</title>
  11  
  12          <para>
  13              The event system in MantisBT uses the concept of signals and hooked events
  14              to drive dynamic actions.  Functions, or plugin methods, can be hooked
  15              during runtime to various defined events, which can be signalled at any
  16              point to initiate execution of hooked functions.
  17          </para>
  18  
  19          <para>
  20              Events are defined at runtime by name and event type (covered in the next
  21              section).  Depending on the event type, signal parameters and return
  22              values from hooked functions will be handled in different ways to make
  23              certain types of common communication simplified.
  24          </para>
  25      </sect1>
  26  
  27      <sect1 id="dev.events.api">
  28          <title>API Usage</title>
  29  
  30          <para>
  31              This is a general overview of the event API.  For more detailed analysis,
  32              you may reference the file <filename>core/event_api.php</filename> in the
  33              codebase.
  34          </para>
  35  
  36          <blockquote id="dev.events.api.declare">
  37              <title>Declaring Events</title>
  38  
  39              <para>
  40                  When declaring events, the only information needed is the event name
  41                  and event type.  Events can be declared alone using the form:
  42              </para>
  43  
  44              <programlisting>event_declare( $name, $type=EVENT_TYPE_DEFAULT );</programlisting>
  45  
  46              <para>
  47                  or they can be declared in groups using key/value pairs of name => type
  48                  relations, stored in a single array, such as:
  49              </para>
  50  
  51              <programlisting>
  52  $events = array(
  53      $name_1 => $type_1,
  54      $name_2 => $type_2,
  55      ...
  56      );
  57  
  58  event_declare_many( $events );
  59              </programlisting>
  60          </blockquote>
  61  
  62          <blockquote id="dev.events.api.hook">
  63              <title>Hooking Events</title>
  64  
  65              <para>
  66                  Hooking events requires knowing the name of an already-declared event,
  67                  and the name of the callback function (and possibly associated plugin)
  68                  that will be hooked to the event.  If hooking only a function, it must
  69                  be declared in the global namespace.
  70              </para>
  71  
  72              <programlisting>event_hook( $event_name, $callback, [$plugin] );</programlisting>
  73  
  74              <para>
  75                  In order to hook many functions at once, using key/value pairs of name
  76                  => callback relations, in a single array:
  77              </para>
  78  
  79              <programlisting>
  80  $events = array(
  81      $event_1 => $callback_1,
  82      $event_2 => $callback_2,
  83      ...
  84      );
  85  
  86  event_hook( $events, [$plugin] );
  87              </programlisting>
  88          </blockquote>
  89  
  90          <blockquote id="dev.events.api.signal">
  91              <title>Signalling Events</title>
  92  
  93              <para>
  94                  When signalling events, the event type of the target event must be kept in
  95                  mind when handling event parameters and return values.  The general format
  96                  for signalling an event uses the following structure:
  97              </para>
  98  
  99              <programlisting>$value = event_signal( $event_name, [ array( $param, ... ), [ array( $static_param, ... ) ] ] );</programlisting>
 100  
 101              <para>
 102                  Each type of event (and individual events themselves) will use different
 103                  combinations of parameters and return values, so use of the
 104                  <link linkend="dev.eventref">Event Reference</link> is recommended for
 105                  determining the unique needs of each event when signalling and hooking them.
 106              </para>
 107          </blockquote>
 108      </sect1>
 109  
 110      <sect1 id="dev.events.types">
 111          <title>Event Types</title>
 112  
 113          <para>
 114              There are five standard event types currently defined in MantisBT.  Each type
 115              is a generalization of a certain "class" of solution to the problems that
 116              the event system is designed to solve.  Each type allows for simplifying
 117              a different set of communication needs between event signals and hooked
 118              callback functions.
 119          </para>
 120  
 121          <para>
 122              Each type of event (and individual events themselves) will use different
 123              combinations of parameters and return values, so use of the
 124              <link linkend="dev.eventref">Event Reference</link> is recommended for
 125              determining the unique needs of each event when signalling and hooking them.
 126          </para>
 127  
 128          <blockquote id="dev.events.types.execute">
 129              <title>EVENT_TYPE_EXECUTE</title>
 130  
 131              <para>
 132                  This is the simplest event type, meant for initiating basic hook
 133                  execution without needing to communicate more than a set of
 134                  immutable parameters to the event, and expecting no return of data.
 135              </para>
 136  
 137              <para>
 138                  These events only use the first parameter array, and return values from
 139                  hooked functions are ignored.  Example usage:
 140              </para>
 141  
 142              <programlisting>event_signal( $event_name, [ array( $param, ... ) ] );</programlisting>
 143          </blockquote>
 144  
 145          <blockquote id="dev.events.types.output">
 146              <title>EVENT_TYPE_OUTPUT</title>
 147  
 148              <para>
 149                  This event type allows for simple output and execution from hooked events.
 150                  A single set of immutable parameters are sent to each callback, and the
 151                  return value is inlined as output.  This event is generally used for an
 152                  event with a specific purpose of adding content or markup to the page.
 153              </para>
 154  
 155              <para>
 156                  These events only use the first parameter array, and return values from
 157                  hooked functions are immediately sent to the output buffer via 'echo'.
 158                  Example usage:
 159              </para>
 160  
 161              <programlisting>event_signal( $event_name, [ array( $param, ... ) ] );</programlisting>
 162          </blockquote>
 163  
 164          <blockquote id="dev.events.types.chain">
 165              <title>EVENT_TYPE_CHAIN</title>
 166  
 167              <para>
 168                  This event type is designed to allow plugins to successively alter the
 169                  parameters given to them, such that the end result returned to the caller
 170                  is a mutated version of the original parameters.  This is very useful
 171                  for such things as output markup parsers.
 172              </para>
 173  
 174              <para>
 175                  The first set of parameters to the event are sent to the first hooked
 176                  callback, which is then expected to alter the parameters and return the
 177                  new values, which are then sent to the next callback to modify, and this
 178                  continues for all callbacks.  The return value from the last callback is
 179                  then returned to the event signaller.
 180              </para>
 181  
 182              <para>
 183                  This type allows events to optionally make use of the second parameter set,
 184                  which are sent to every callback in the series, but should not be returned
 185                  by each callback.  This allows the signalling function to send extra,
 186                  immutable information to every callback in the chain.  Example usage:
 187              </para>
 188  
 189              <programlisting>$value = event_signal( $event_name, $param, [ array( $static_param, ... ) ] );</programlisting>
 190          </blockquote>
 191  
 192          <blockquote id="dev.events.types.first">
 193              <title>EVENT_TYPE_FIRST</title>
 194  
 195              <para>
 196                  The design of this event type allows for multiple hooked callbacks to
 197                  'compete' for the event signal, based on priority and execution order.
 198                  The first callback that can satisfy the needs of the signal is the last
 199                  callback executed for the event, and its return value is the only one
 200                  sent to the event caller.  This is very useful for topics like user
 201                  authentication.
 202              </para>
 203  
 204              <para>
 205                  These events only use the first parameter array, and the first non-null
 206                  return value from a hook function is returned to the caller. Subsequent
 207                  callbacks are never executed.  Example usage:
 208              </para>
 209  
 210              <programlisting>$value = event_signal( $event_name, [ array( $param, ... ) ] );</programlisting>
 211          </blockquote>
 212  
 213          <blockquote id="dev.events.types.default">
 214              <title>EVENT_TYPE_DEFAULT</title>
 215  
 216              <para>
 217                  This is the fallback event type, in which the return values from all
 218                  hooked callbacks are stored in a special array structure.  This allows
 219                  the event caller to gather data separately from all events.
 220              </para>
 221  
 222              <para>
 223                  These events only use the first parameter array, and return values from
 224                  hooked functions are returned in a multi-dimensional array keyed by plugin
 225                  name and hooked function name.  Example usage:
 226              </para>
 227  
 228              <programlisting>$values = event_signal( $event_name, [ array( $param, ... ) ] );</programlisting>
 229          </blockquote>
 230      </sect1>
 231  </chapter>