One of the features introduced in the recent TWiki-4 release is the concept of a "tag handler". A tag handler is a function which is invoked when a TWiki variable is parsed out of the topic text. Many, though not all, TWiki core functions are implemented using tag handlers. Plugins authors can register their own tag handlers using the TWiki::Func::registerTagHandler API.

What may not be immediately obvious is that this approach lets you "decorate" existing tag handlers, to perform extra operations when a tag is seen in the topic text.

For example, say you wanted to detect when an INCLUDEd topic was access-protected, and provide some alternate text instead of the default warning string provided by TWiki. You could do this in a plugin like this:

sub initPlugin {
    # This is the only "illegal" call; functionTags is not exported outside TWiki.
    # Some day there will be a "getTagHandler" API.
    my $existingTagHandler = $TWiki::functionTags{INCLUDE};

    TWiki::registerTagHandler( "INCLUDE", sub {
        my $result = _myInclude(@_);
        return $result if defined $result;
        return $existingTagHandler(@_));
    });
}

sub _myInclude {
    my( $session, $attrs ) = @_;
    # have to do this to tell TWiki::Func where the TWiki object is
    $TWiki::Plugins::SESSION = $session;
    unless( TWiki::Func::checkAccessPermission ) {
       return "regretfully, you are too small a soul to access this mighty tome";
    }
    return undef; # fall through to default behaviour
}

The fun thing is that if plugins use tag handlers, you can decorate their tags as well

Be warned, though, that TWiki Variables take precedence over function tags; so if someone manages to * Set INCLUDE, then their definition will still override yours.

-- Contributors: CrawfordCurrie

Discussion

This is a rather cool feature I never thought about. I'm curios to see the first implementations. (If I remenber correct) There are some plugins that don't respect user permissions. This could be a simple way to allow these plugins also on an open TWiki installation while restricting them to access allowed content only through subclassing the tag handlers.

Another feature is restriction plugins to a specific user group - a feature I miss really but never had the time to report/request. This is somewhat hackish, implementing this feature sometime in the plugin interface is more clean of course.

-- TobiasRoeser - 04 Apr 2006

I'm most of the way through implementing lightweight tag handlers. Plugins supposedly cost some speed even if they're not used, but fooTag won't. Yay!

-- MeredithLesly - 04 Apr 2006