The paramters are ( $text, $topic, $web ) which are accessed as usual like $_[0], $_[1], $_[2]. Note that $text does not include the meta data. Meta data is not documented yet for plugins, we need first to design a clean interface for topic text and meta data.

This hook is useful to make some changes to the topic content just before a topic is saved. An example is a plugin that creates and updates cached data using the (not yet implemented) PluginDataStore.

Is in TWikiAlphaRelease and TWiki.org, MorePluginHooks are pending.

-- PeterThoeny - 06 Apr 2002

Change in spec: The $text in beforeSaveHandler hook includes now the meta data, e.g. is in the same format like the raw text file. (Change in spec is justifyable since it is Beta )

-- PeterThoeny - 29 Dec 2002

What about making beforeSaveHandler "conditional". That is, imagine this situation: You've got ExpensiveVoodooPlugin which is a beforeSaveHandler plugin, and it does some important mojo but you don't want it called every time you save the topic, only sometimes. The obvious way to do this is to add a checkbox to the preview.tmpl and then merge your ExpensiveVoodooPlugin with the save script. But then you've no longer got a plugin and your solution is decidely inelegant. So what to do?

My very hacky solution was this:

In bin/save I added near the top:

my %paramHash = $query->Vars;

and then changed the saveTopic line to:

my $error = &TWiki::Store::saveTopic( $webName, $topic, $text, $meta, $saveCmd, $unlock, $dontNotify, "", "", \%paramHash );

and in Store.pm:

sub saveTopic
{
    my( $web, $topic, $text, $meta, $saveCmd, $doUnlock, $dontNotify, 
        $dontLogSave, $forceDate, $paramRef ) = @_;
    my $attachment = "";
    my $comment = "";

    # FIXME: Inefficient code that hides meta data from Plugin callback
    $text = $meta->write( $text );  # add meta data for Plugin callback
    TWiki::Plugins::beforeSaveHandler( $text, $topic, $web, $paramRef );
    $meta = TWiki::Meta->remove();  # remove all meta data
    $text = $meta->read( $text );   # restore meta data

    my $error = saveNew( $web, $topic, $text, $meta, $saveCmd, $attachment,
                         $dontLogSave, $doUnlock, $dontNotify, $comment, $forceDate );
    return $error;
}

Then you can do:

sub beforeSaveHandler
{
    if( $_[3]->{"someoption"} eq "somevalue" ) {
         voodoo;
    }
}

Now this is pretty ugly, since it passes the whole text and a bunch of other options that we don't need through $paramRef but it should be a good jumping point from here (that is if anyone else agrees with me that this is important ).

-- ZacharyHamm - 25 Apr 2003