devel:event_handlers
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
devel:event_handlers [2013-11-01 18:55] – [Global Scope] Klap-in | devel:event_handlers [2023-09-02 13:37] (current) – Klap-in | ||
---|---|---|---|
Line 5: | Line 5: | ||
===== The Event Loop ===== | ===== The Event Loop ===== | ||
- | To begin with, it's helpful to understand how events are processed. To be notified of an event, your code must register to receive the notification. Registering places your request for notification on a list of requests for the event. The list is a first come, first serve array; that is, it's treated as a stack where each next request is pushed on the end of the list. This means it's possible to implement more than one handler for the same event. | + | To begin with, it's helpful to understand how events are processed. To be notified of an event, your code must register to receive the notification. Registering places your request for notification on a list of requests for the event. The list is a first-come, first-served |
- | When DokuWiki processes an action that has an associated event, it does not perform this action immediately. Instead, it triggers an event for this action. For instance, when DokuWiki goes to write a wiki page, it triggers an [[events_list# | + | When DokuWiki processes an action that has an associated event, it does not perform this action immediately. Instead, it triggers an event for this action. For instance, when DokuWiki goes to write a wiki page, it triggers an [[devel: |
- | There are actually two lists: one for before and one for after DokuWiki performs its own action. These are designated by the '' | + | There are actually two lists: one for before and one for after DokuWiki performs its own action. These are designated by the '' |
- | After performing its own action, DokuWiki loops through all the '' | + | After performing its own action, DokuWiki loops through all the '' |
DokuWiki' | DokuWiki' | ||
Line 17: | Line 17: | ||
In simplified pseudo code, the event process would look like this: | In simplified pseudo code, the event process would look like this: | ||
< | < | ||
- | + | var $process_event = true; | |
- | var $process_event = true; | + | var $default_stopped = false; |
- | | + | |
- | loop_through_BEFORE_List() { | + | loop_through_BEFORE_List() { |
- | | + | return if $process_event == false; |
- | | + | } |
- | do_DokuWiki_Action() { | + | do_DokuWiki_Action() { |
- | | + | return if $default_stopped; |
- | | + | } |
- | var $process_event = true; | + | var $process_event = true; |
- | loop_through_AFTER_List(){ | + | loop_through_AFTER_List(){ |
- | return if $process_event == false; | + | return if $process_event == false; |
- | | + | } |
</ | </ | ||
===== Registering an Event ===== | ===== Registering an Event ===== | ||
- | Event handlers are registered using the '' | + | Event handlers are registered using the [[xref>register_hook()]] function of the [[xref> |
The function definition for '' | The function definition for '' | ||
- | < | + | < |
void register_hook(string $event, string $advise, | void register_hook(string $event, string $advise, | ||
- | mixed &$obj, string $method, mixed $param=NULL) | + | object |
</ | </ | ||
- | * '' | + | * '' |
* '' | * '' | ||
* '' | * '' | ||
* '' | * '' | ||
* '' | * '' | ||
+ | * '' | ||
==== Global Scope ==== | ==== Global Scope ==== | ||
- | To call register_hook() from the global scope, you | + | To call '' |
- | set '' | + | the global variable |
- | the global variable | + | < |
- | < | + | $EVENT_HANDLER-> |
- | '' | + | </ |
+ | '' | ||
==== Action plugins ==== | ==== Action plugins ==== | ||
- | Action plugins do not need direct access to the global '' | + | [[devel:Action plugins]] do not need direct access to the global '' |
- | and typically you would be calling register_hook from an action plugin. | + | |
- | In action plugins, event handlers are registered in the | + | In action plugins, event handlers are registered in the '' |
- | register() method, which all action plugins must implement. It takes one parameter, '' | + | < |
- | < | + | use dokuwiki\Extension\EventHandler; |
- | function register(&$controller) { | + | ... |
- | $controller%%->%%register_hook(' | + | public |
+ | $controller-> | ||
+ | | ||
} | } | ||
</ | </ | ||
- | * The event is [[events_list# | + | * The event is [[devel: |
- | * The event handler is '' | + | * The event handler is '' |
- | * The '' | + | * The '' |
* Finally, the handler is to be called **after** DokuWiki formats the page content. | * Finally, the handler is to be called **after** DokuWiki formats the page content. | ||
Line 77: | Line 79: | ||
The handler has this basic form: | The handler has this basic form: | ||
- | < | + | < |
- | | + | use dokuwiki\Extension\Event; |
- | * $event: Doku_Event | + | ... |
- | * $param: optional | + | /** |
- | | + | |
- | function handler (&$event, $param) { | + | |
- | // handler code | + | */ |
+ | public | ||
+ | // handler code | ||
} | } | ||
</ | </ | ||
- | When Doku_Event_Handler | + | When EventHandler |
((DokuWiki' | ((DokuWiki' | ||
==== The Event Object ==== | ==== The Event Object ==== | ||
- | The authoritative specification for the event object | + | The authoritative specification for the event object |
[[events# | [[events# | ||
Line 97: | Line 101: | ||
* '' | * '' | ||
* '' | * '' | ||
- | * '' | + | * '' |
- | * '' | + | * '' |
- | * '' | + | * protected |
- | * '' | + | * protected |
==== Methods ==== | ==== Methods ==== | ||
- | - '' | + | - '' |
- | * Calling this method from a '' | + | * Calling this method from a '' |
- | - '' | + | - '' |
- | * Calling this method sets '' | + | * Calling this method sets '' |
- | - mixed '' | + | - '' |
- | * This is a global function, not a method of the Doku_Event class. Calling this function enables the triggering of a user-defined event. Its parameters are as follows: | + | * This is a global function. Calling this function enables the triggering of a user-defined event. Its parameters are as follows: |
- | * '' | + | * '' |
- | * '' | + | * '' |
- | * '' | + | * '' |
- | * '' | + | * '' |
- | * mixed return value: This is whatever is stored in the event' | + | * mixed return value: This is whatever is stored in the event' |
- | * It's possible to use this function to trigger a standard DokuWiki event, but this would require careful coding and a knowledge of when and how the DokuWiki event is processed. Moreover, triggering a standard event doesn' | + | * It's possible to use this function to trigger a standard DokuWiki event, but this would require careful coding and a knowledge of when and how the DokuWiki event is processed. Moreover, triggering a standard event doesn' |
+ | |||
+ | =====Examples===== | ||
+ | See [[event handlers code]] samples. | ||
+ | |||
+ | =====See also ===== | ||
+ | |||
+ | * The [[Events|Event system]] | ||
+ | * [[Events List]] with existing events. | ||
+ | * Use [[Action plugins]] to register handlers on events. |
devel/event_handlers.1383328518.txt.gz · Last modified: 2013-11-01 18:55 by Klap-in