====== System zdarzeń ======

System zdarzeń pozwala dostosować obsługę poprzez rozszerzenie lub zastąpienie standardowego przetwarzania dla każdej części DokuWiki, która sygnalizuje swoją aktywność przez system zdarzeń(cokolwiek to znaczy FIXME). Dowolne procedury obsługi mogą być dołączane w każdej wtyczce lub szablonie(lub w samej DokuWiki).  [[wiki:plugins:action|Wtyczki akcji]] zostały zaprojektowane do obsługi systemu zdarzeń. Są ładowane na początku procesu przetwarzania, aby umożliwić rejestrację zdarzeń zanim zajdzie którekolwiek z nich. Inne części DokuWiki mogą nie wykonać się bezpośrednio lub wogóle na danej stronie lub ścieżce wykonawczej.

Istnieje również możliwość przystosowania zdarzeń DokuWiki, aby mogły się same tworzyć i przywoływać.

System zdarzeń składa się z trzech części
  * [[#obiekt zdarzenia]].
  * główna procedura obsługi zdarzenia lub kontroler.  Jest to zmienna globalna ''$EVENT_HANDLER''. Skrypty, które mają wykonać się po wywołaniu zdarzenia muszą najpierw zarejestrować się przez ten obiekt. Kiedy wywołane zostaje zdarzenie wszystkie procedury obsługi w tym obiekcie zostają po kolei wykonywane.
  * individual event handlers or hooks.  These are functions that wish to receive a particular event.  The [[wiki:plugins:action|action plugin]] is a vehicle specifically for these functions, however they can also be part of templates, plugins of other types or the main DokuWiki scripts.FIXME

Detailed information describing existing events and when they occur is provided in the [[wiki:events list]].

===== Event Object =====

**class name ''Doku_Event''**

An event object consists of:
  * **PUBLIC** properties
    * ''name'', (READONLY) hooks must use this to register to process a particular event
    * ''data'', (READ/WRITE) data pertaining to the event, hooks have an opportunity to inspect and modify this
    * ''result'', (READ/WRITE) available after the default action has taken place to hooks that have registered for the ''after'' advise.
    * ''canPreventDefault'', (READONLY) informs a hook whether or not the default action can be prevented
  * **PRIVATE** properties
    * ''_default'' (bool, inital value ''true''), whether or not the default action associated with the event should be carried out.  Interact with this property via the ''preventDefault()'' method.
    * ''_continue'' (bool, initial value ''true''), whether or not to continue sending the event to registered hooks that have yet to receive it.  Interact with this property via the ''stopPropagation()'' method.

  * **PUBLIC** methods
    * ''trigger()'' - automated signalling of events.  This method accepts two optional parameters, the default action (callback), and whether or not it may be prevented (bool) and returns the results of the event.  It looks after the whole event process, signalling the "_BEFORE" advise, triggering the default action and signalling the "_AFTER" advise.
    * ''stopPropagation()'' - stop any further processing of the event by event handlers this function does not prevent the default action taking place
    * ''preventDefault()'' - prevent the default action taking place
  * ''advise_*()'' methods - for use when the signalling script wishes to handle the complete event signalling process (perhaps when functionalising a default action is not appropriate).
    * ''advise_before()'' - accepts one parameter, a boolean indicating whether the default action can be prevented, issues the "_BEFORE" signal.
    * ''advise_after()'' - issues the "_AFTER" signal.

===== Registering to Receive an Event =====

To register a hook to receive an event, call the ''register_hook()'' method of the ''$EVENT_HANDLER''.  Action plugins can do this using the ''$controller'' parameter from within their own ''register()'' method.  Other parts of DokuWiki should ensure they are either in global scope or declare $EVENT_HANDLER as a global. e.g.

  global $EVENT_HANDLER;
  $EVENT_HANDLER->register_hook( ... )

For up-to-date details of the register_hook function and its parameters refer to its declaration in ''inc/events.php''.  As of 2006-04-26 the declaration is

<code php>
  /**
   * register_hook
   *
   * register a hook for an event
   *
   * @PARAM  $event   (string)   name used by the event
   * @PARAM  $advise  (string)   ''BEFORE'' or ''AFTER'', the advise the hook wished to receive
   * @PARAM  $obj     (obj)      object in whose scope method is to be executed, 
   *                             if NULL, method is assumed to be a globally available function
   * @PARAM  $method  (function) event handler function
   * @PARAM  $param   (mixed)    (optional) data to be passed to the event handler
   */ 
  function register_hook($event, $advise, &$obj, $method, $param)
</code>

===== Signalling an Event =====

An event can be signalled in three ways.  
  - The simplest is to use the function wrapper ''trigger_event''. This function takes all the parameters necessary to create an event object and trigger it. \\ <code php>
/**
 *  trigger_event
 *
 *  function wrapper to process (create, trigger and destroy) an event
 *
 *  @PARAM  $name               (string)   name for the event
 *  @PARAM  $data               (mixed)    event data
 *  @PARAM  $action             (callback) (optional, default=NULL) default action, a php callback function
 *  @PARAM  $canPreventDefault  (bool)     (optional, default=true) can hooks prevent the default action
 *
 *  @RETURN (mixed)                        the event results value after all event processing is complete
 *                                         by default this is the return value of the default action however
 *                                         it can be set or modified by event handler hooks
 */
function trigger_event($name, &$data, $action=NULL, $canPreventDefault=true)
</code>
  - using the trigger method.  This isn't recommended as it is better to use the ''trigger_event()'' function wrapper described above. <code php>
  $evt = new Doku_Event(<event_name>,<event_data>);
  $evt->trigger(<default action>,<can prevent default>);
  unset($evt);
</code>
  - managing the whole event signalling process.  Use this method when there is a default action but it not possible to package it as a php callback function. <code php>
  $evt = new Doku_Event(<event name>, <event data>);
  if ($evt->advise_before(<can prevent default>)) {
    // default action code block
  }
  $evt->advise_after();
  unset($evt);
</code>

===== Examples =====

(these are examples only and may not exist in DokuWiki)

** On Wiki page save **

  // event:  'IO_WIKIPAGE_SAVE'
  // data:   array(file name, the raw wiki page)
  // action: save the raw wiki page to file name
  // return: bool, page saved
  $ok = trigger_event('SAVE_WIKIPAGE', array($id,$wikitext), io_savewikipage)

possible handlers, indexers, translaters
----

** Additional/Replacement ''do'' actions **

  // events:  'ACTION_ACT_PREPROCESS' & 'TPL_ACT_UNKNOWN'
  // data:    $ACT  (value of the ''do'' query string variable)
  // action:  none, handled by signalling script
  
  // in ''inc/actions.php act_dispatch()''
  $evt = new Doku_Event('ACTION_ACT_PREPROCESS', $ACT);  
  if ($evt->advise_before()) { 
     /* process $ACT normally */ 
  }
  $evt->advise_after();
  unset($evt);
  
  // in ''inc/template.php tpl_content()''
  default: /* unrecognised $ACT value */
    $evt = new Doku_Event('TPL_ACT_UNKNOWN', $ACT);
    if ($evt->advise_before()) { 
       print "unknown action"; 
    }
    $evt->advise_after();
    unset($evt);

possible handlers, customer form processing, additional ''do'' commands from template UI.
----

** On handler instruction list completion **

  // event:  ''PARSER_HANDLER_DONE''
  // data:   the handler, including the completed instruction list
  // action: none
  
  // in ''inc/parser/handler.php  _finalize()
  trigger_event('PARSER_HANDLER_DONE',$this);

possible handlers, footnote replacement plugins, enhanced TOC handlers
----