Feature Proposal: Pass text and meta data to registerTagHandler callback

Motivation

The recommended way to handle plugin variables is to register them at plugin initialization time using TWiki::Func::registerTagHandler. Some plugins such as ChartPlugin and SpreadSheetPlugin need to reference text outside the variable, such as tables. These plugin currently cannot use registerTagHandler because there is no way to get at the topic text besides loading the topic from disk. This in turn would show outdated data in a topic preview.

Description and Documentation

This proposal adds two more parameters to the callback: $meta, $textRef. The $textRef is a reference to the topic text. It is considered read-only, e.g. can't be changed.

Example

package TWiki::Plugins::ExamplePlugin;

sub initPlugin {
    TWiki::Func::registerTagHandler( 'EXAMPLEVAR', \&_EXAMPLEVAR );
    return 1;
}

sub _EXAMPLEVAR {
    my( $session, $params, $theTopic, $theWeb, $meta, $textRef ) = @_;

    my $output = "EXAMPLEVAR: web $theWeb, topic $theTopic";

    # Access meta data, such as:
    my $attachments = $meta->find( 'FILEATTACHMENT' );
    $output .= ', number of attachments: ' . scalar( $attachments );

    # Access topic text by de-referencing $textRef, such as:
    if( $$textRef =~ /DEMO/ ) {
        $output .= ', found "DEMO" in text';
    }

    return $output;
}

1;

Impact

Implementation

-- Contributors: PeterThoeny - 2011-05-16

Discussion

Great idea! Would help plugins to convert from the old plugin API to using the new (registerTagHandler) plugin API

-- TaitCyrus - 2011-05-17

Yes, that was the intent.

One word of caution: Due to parsing algorithm, you'll see unexpanded text in $textRef. That is, variables enclosed in the current one and variables in previous lines are unexpanded. $params contains expanded text as expected.

-- PeterThoeny - 2011-05-17

This is now accepted by the SevenDayFeedbackPeriod.

-- PeterThoeny - 2011-05-23

This is now implemented and documented in SVN trunk.

-- PeterThoeny - 2011-05-23