NAME

MT::Callback - Movable Type wrapper for executable code with error state

SYNOPSIS

  $cb = new MT::Callback(name => <name>, code => sub { <callback code> });

<name> is a human-readable string which identifies the surrounding body of code, for example the name of a plugin--the name will help identify errors in the activity log.

METHODS

name: Returns the registered name of the callback.
invoke: Executes the callback, passing the MT::Callback object as the first parameter, followed by any parameters sent to the invoke method.
plugin: Returns the 'plugin' element associated with the callback object.

CALLBACK CALLING CONVENTIONS

The parameters passed to each callback routine depends on the operation in questions, as follows:

load(), load_iter()

Before loading items from the database, load() and load_iter() call the callback registered as <class>::pre_load, allowing a callback writer to munge the arguments before the database is called.

An example <class>::pre_load might be written as follows:

    sub pre_load {
        my ($eh, $args) = @_;
        ....
    }

Each object returned by load() or by an iterator will, before it is returned, be processeed by all callbacks registered as <class>::post_load. An example <class>::post_load function

    sub post_load {
        my ($eh, $args, $obj) = @_;
        ....
    }

The $args parameter for both the pre_load and post_load callback is an array reference of all parameters that were supplied to the load or load_iter methods.

save()

Callbacks for the save method might be written as follows:

    sub pre_save {
        my ($eh, $obj, $original) = @_;
        ....
    }

    sub post_save {
        my ($eh, $obj, $original) = @_;
        ....
    }

By altering the $obj in pre_save, you can affect what data gets stored in the database.

By creating pre_save and post_load functions which have inverse effects on the object, you might be able to store data in the database in a special form, while keeping the usual in-memory representation.

remove()

<class>::pre_remove and <class>::post_remove are called at the very beginning and very end of the respective operations. The callback routine is called as follows:

    sub pre_remove {
        my ($eh, $obj) = @_;
        ....
    }

The signature for the post_remove operation is the same.

<class>::pre_remove_all and <class>::post_remove_all are called at the very beginning and very end of the respective operations, with no arguments except the MT::Callback object.

ERROR HANDLING

The first argument to any callback routine is an MT::Callback object. You can use this object to return errors to MT.

To signal an error, just use its error() method:

    sub my_callback {
        my ($eh, $arg2, $arg3) = @_;

        ....

        if (some_condition) {
            return $eh->error("The foofiddle was invalid.");
        } 
        ...
    }

AUTHOR & COPYRIGHTS

Please see the MT manpage for author, copyright, and license information.