Tags:
create new tag
, view all tags

Feature Proposals » Introducing renderParentHandler() to plugins

Summary

Current State: Developer: Reason: Date: Concerns By: Bug Tracking: Proposed For:
AcceptedProposal HideyoImazu AcceptedByReleaseMeeting 2015-10-01     KampalaRelease

Edit Form

TopicSummary:
CurrentState:
CommittedDeveloper:
ReasonForDecision:
DateOfCommitment:   Format: YYYY-MM-DD
ConcernRaisedBy:
BugTracking:
OutstandingIssues:
RelatedTopics:
InterestedParties:
ProposedFor:
TWikiContributors:
 

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

Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r4 - 2015-10-02 - HideyoImazu
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.