Feature Proposals » Introducing renderParentHandler() to plugins

Motivation

META{"parent" ...} is used to generate breadcrumbs. It does the job by tracing the "parent" metadata of topics. There are other ways to construct breadcrumbs than tracing "parent" metadata.

Description and Documentation

Introducing renderParentHandler() to plugins to cope with situation where breadcrumbs are constructed in a different manner than parent-child relationships.

There might be a situation where renderParentHandler() of plugins need to be ignored and resorting to the parent-child relationships. For that, %META{"parent" ...}% will have ignorehandlers="on" parameter, which suppresses invocation of renderParentHandler() of plugins.

META{"parent" ...} is processed by TWiki::Render::renderParent(), which will invoke renderParentHandler(). If there are no plugins having renderParentHandler(), renderParent()'s behavior remains the same. If there are plugins exposing renderParentHandler() then, the first one returning true result dictates the result.

Examples

TWiki::Render

...
sub renderParent {
    my( $this, $web, $topic, $meta, $ah ) = @_;
...
    my $text;
    unless ( TWiki::Func::isTrue($ah->{ignorehandlers}) {
        $session->{plugins}->dispatch('renderParentHandler', $this->{session}, $web, $topic, $ah, \$text);
        return $text if ( defined($title) );
    }
...

TWiki::Plugins

my %onlyOnceHandlers =
  {
...
   renderParentHandler => 1,
...
  };

TWiki::Plugins::ARandomPlugin

sub renderParentHandler {
    # my ( $session, $web, $topic, $params, $textRef ) = @_;
    ...
    # if parents are not determined
    # not setting $$textRef
    return 0;
    ...
    # if a topic title is determined by the handlr
    $$textRef = ...;
    return 1; 
}

Alternative considered but discarded

Initially, I thought about introducing %BREADCRUMBS{...}% and breadcrubmsHandler(). But I realized that %META{"parent" ...}% constructs only a part of breadcrumbs rather than an entire breadcrumbs. So if %BREADCRUMBS{...}% is introduced, it's supposed to do more than %MEATA{"parent" ...}%.

Existing skins and other things need %META{"parent" ...}% anyway. So instead of introducing %BREACRUMBS{...}% and breadcrumbsHandler(), introducing reanderParentHandler() is better.

Impact

Implementation

-- Contributors: Hideyo Imazu - 2015-10-01

Discussion

Looks good. Needs doc on default, e.g. if no plugin uses this callback.

-- Peter Thoeny - 2015-10-01