<<

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

new(\%param) or new(%param)

Constructs a new object, using the given parameters. The parameters recognized for a callback object are:

name

The name of the callback.

code

A coderef that is invoked when running the callback.

plugin

The MT::Plugin that is associated with this callback.

priority

The priority to assign for the callback, which determines the order it is invoked when multiple callbacks are tied to the same method.

method

The name of the method this callback is associated with.

$cb->name()

Returns the registered name of the callback.

$cb->invoke(@params)

Executes the callback, passing the MT::Callback object as the first parameter, followed by any parameters sent to the invoke method.

$cb->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 ($cb, $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 ($cb, $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 ($cb, $obj, $original) = @_;
          ....
      }
  
      sub post_save {
          my ($cb, $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 ($cb, $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 ($cb, $arg2, $arg3) = @_;

        ....

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

AUTHOR & COPYRIGHTS

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

<<