Site Tools


Event Handlers: Sample Code

eventcheck

eventcheck.tgz

eventcheck is a plugin that dumps output on all events, as they are being fired, to a file called eventcheck.txt in your main DokuWiki directory, labeling the 'BEFORE' and 'AFTER' phases of each event. A great deal of data accumulates in a very short time, so you may eventually want to exclude any events you are not currently interested in. A good way way to use this plugin is to check its output against the descriptions of the event objects in the DokuWiki Events List.

The eventCheck register() method registers all current DokuWiki events in both 'BEFORE' and 'AFTER' modes. This code illustrates that one plugin can accommodate multiple event handlers and that, where convenient, the same callbacks can be used for more than one handler. To use this plugin place it in a directory named eventcheck in lib/plugins.

headers and footers

Using TPL_ACT_RENDER, it’s possible to add text to the top and bottom of a wiki page. TPL_ACT_RENDER is signalled by tpl_content(), which is called from main.php to output the wiki page to the browser:

    <!-- wikipage start -->
    <?php tpl_content()?>
    <!-- wikipage stop -->

While this event is in effect, the text is held in a buffer outside of its reach and cannot be modified.

However, anything written to standard output (echo, print) will appear either above or below the page, depending on whether it has originated in the BEFORE or AFTER phase of the handler. The headers and footers appear on the screen but do not get written to the page files. This makes them ideal for outputting messages on the fly. When the user is editing a page, the header will appear above the standard instructions:

“Edit the page and hit Save. See syntax . . . ”

During a login session, it will appear above the Login title. What action is currently being processed can be determined from the data field ($event→data), which holds the name of the current action–edit, show, login, etc.1) TPL_ACT_RENDER provides a powerful option. You can stop the page from being printed to the screen by making the following calls:

$event->preventDefault()
$event->stopPropagation()

The page will not appear on the screen, but any text output from the handler will, enabling you to substitute your own message for the page. Assume, for instance, that certain pages can be viewed only by users from particular IP addresses, who may not be registered with your DokuWiki. You can substitute for the page a message indicating that this page is not available for viewing.2)

Content Modification

There are several events which give handlers a chance to modify the text:

  • PARSER_WIKITEXT_PREPROCESS: here $event→data holds the complete text as marked up in DokuWiki syntax. The modified text will appear in the browser, but it is not saved to disk.
  • RENDERER_CONTENT_POSTPROCESS: here the marked up text has been converted to XHTML. As in the above, the modified text appears in browser but is not saved to disk. The text is found in data[1].
  • IO_WIKIPAGE_WRITE: this event writes the text with modifications to disk. At the same time, the text, with any modifications, is returned to the browser. The text is in DokuWiki format and is found in $event→data[0][1]; event→data[0][0] holds the absolute path of the file.
1)
See the sample TPL_ACT_RENDER object
2)
The page can be determined from $_REQUEST['id'] and the IP from $_SERVER['REMOTE_ADDR'].