[dokuwiki] Re: events

  • From: Chris Smith <chris@xxxxxxxxxxxxx>
  • To: dokuwiki@xxxxxxxxxxxxx
  • Date: Sat, 22 Apr 2006 17:55:41 +0100

Martin Tschofen wrote: 

I'm wondering about the exact order of how the events will output the
results and how to access the processed content. For testing purposes
I came up with this custom action:

  function register(&$controller) {
    $controller->register_hook('ACTION_DISPATCH', $this, 'collect', NULL);
  }

  function collect($param, &$event){
    if ($event->data != 'collect') return;
        $event->preventDefault();
        global $EVENT_HANDLER;
    $EVENT_HANDLER->register_hook('TPL_ACTION_HTML', $this, 'tpl_action', NULL);
        
$EVENT_HANDLER->register_hook('TPL_DISPLAY_HTML',$this,'tpl_display',NULL);
        
$EVENT_HANDLER->register_hook('TPL_DISPLAY_HTML_AFTER',$this,'tpl_display_after',NULL);
        $event->stopPropagation();
  }
  function tpl_action($param, &$event){
    print "Collect print<br>";
        $event->preventDefault();
        $event->stopPropagation();
  }

  function tpl_display($param, &$event){
    print $event->data;
    print "TPL_Display_HTML output<br>";
  }

  function tpl_display_after($param, &$event){
    print $event->result;
    print "TPL_Display_HTML_AFTER output<br>";
  }

What I noticed: In a custom action I really don't need
TPL_DISPLAY_ACTION and TPL_DISPLAY_ACTION_AFTER as I can just use
TPL_ACTION_HTML to output all what I need to do.
For testing however, when I run this, I end up with the output of the

tpl_display function and then tpl_action:
"Collect print
TPL_Display_HTML output
Collect print"

It looks like TPL_DISPLAY_HTML outputs before TPL_ACTION_HTML and
TPL_ACTION_HTML_AFTER not at all.

I suspect I shouldn't "print" content. I tried returning it from the
function and putting it into $event->result. Neither made a
difference.

Please enlighten me...martin
TPL_ACTION_HTML the event data is $ACT, the default action is to output XHTML per $ACT. Output buffering is in effect, so all output is captured before being passed to TPL_DISPLAY_HTML. If you prevent the default action you should output any XHTML yourself.

TPL_DISPLAY_HTML receives the captured output as the event data. You can change or replace this output, the default action is for the event data to be sent to client. If you prevent the default action you should send any output yourself.

If you are adding a do command, you don't need to use either of these events. Use ACTION_TEMPLATE. ACTION_TEMPLATE is signalled during page output (ie, when dokuwiki is carrying out the default action of the TPL_ACTION_HTML) if there is an unrecognised $ACT value.

This all might seem a little complex. I'll explain a little (of my understanding) of how dokuwiki works. It sort of follows the pipelining model, whereby you carry out all your processing up front, then you display your output. I say sort of as its not as pure as that - at least it depends on what you count as processing and what you count as output preparation.

First comes:

ACTION_DISPATCH [1] where Dokuwiki carries out its processing of the $ACT variable. That means:
- it validates it, correcting its value if necessary.
- for any values of $ACT that require processing (e.g. page saving, admin plugin updates) it carries those out.

then:
TPL_ACTION_HTML [2]
- this is a wrapper around the output half of $ACT processing. $ACT is assumed to be validated at this point, so unlike within ACTION_DISPATCH, dokuwiki doesn't modify the $ACT value if it finds it to be incorrect.

during:
- tpl_content_core (formerly tpl_content) is a large switch statement, each case corresponds to a dokuwiki handled $ACT value. If the default case is reached, its an unrecognised $ACT value - whereupon an ACTION_TEMPLATE[3] event is signalled, allowing the appropriate event handler to generate the XHTML output for the $ACT value

then:
TPL_DISPLAY_HTML [4]
- the output from the TPL_ACTION_HTML was captured in an output buffer. Its passed to this event as data. After the event handlers have finished with it, its output to the browser.

If you are adding a new $ACT command, you can handle that command through $ACTION_TEMPLATE or $TPL_ACTION_HTML. If you are replacing a Dokuwiki default $ACT command then you need to either handle $TPL_ACTION_HTML or change the $ACT value before $TPL_ACTION_HTML and use $ACTION_TEMPLATE.

Sorry about the confusing event names. As noted previously, these will change to something that is more consistent.

Cheers,

Chris

[1] likely to be renamed ACTION_ACT_PREPROCESS
[2] likely to be renamed TPL_ACT_RENDER
[3] likely to be renamed TPL_ACT_UNKNOWN (though maybe this should be TPL_ACT_UNKNOWN_RENDER or TPL_ACT_RENDER_UNKNOWN)
[4] likely to be renamed TPL_CONTENT_DISPLAY

--
DokuWiki mailing list - more info at
http://wiki.splitbrain.org/wiki:mailinglist

Other related posts:

  1. Home
  2. dokuwiki
  3. Archive
  4. 04-2006