CALLBACKS

$obj->add_callback()

Most MT::Object operations can trigger callbacks to plugin code. Some notable uses of this feature are: to be notified when a database record is modified, or to pre- or post- process the data being flowing to the database.

To add a callback, invoke the add_callback method of the MT::Object subclass, as follows:

MT::Foo->add_callback( "pre_save", <priority>, 
                       <plugin object>, \&callback_function);

The first argument is the name of the hook point. Any MT::Object subclass has a pre_ and a post_ hook point for each of the following operations:

• load
• save
• update (issued for save on existing objects)
• insert (issued for save on new objects)
• remove
• remove_all
• (load_iter operations will call the load callbacks)

The second argument, <priority>, is the relative order in which the callback should be called. The value should be between 1 and 10, inclusive. Callbacks with priority 1 will be called before those with 2, 2 before 3, and so on.

Plugins which know they need to run first or last can use the priority values 0 and 11. A callback with priority 0 will run before all others, and if two callbacks try to use that value, an error will result. Likewise priority 11 is exclusive, and runs last.

How to remember which callback priorities are special? As you know, most guitar amps have a volume knob that goes from 1 to 10. But, like that of certain rock stars, our amp goes up to 11. A callback with priority 11 is the “loudest” or most powerful callback, as it will be called just before the object is saved to the database (in the case of a ‘pre’ callback), or just before the object is returned (in the case of a ‘post’ callback). A callback with priority 0 is the “quietest” callback, as following callbacks can completely overwhelm it. This may be a good choice for your plugin, as you may want your plugin to work well with other plugins. Determining the correct priority is a matter of thinking about your plugin in relation to others, and adjusting the priority based on experience so that users get the best use out of the plugin.

The <plugin object> is an object of type MT::Plugin which gives some information about the plugin. This is used to include the plugin’s name in any error messages.

<callback function> is a code reference for a subroutine that will be called. The arguments to this function vary by operation (see MT::Callback for details), but in each case the first parameter is the MT::Callback object itself:

sub my_callback {
    my ($cb, ...) = @_;
    if ( <error condition> ) {
        return $cb->error("Error message");
    }
}

Strictly speaking, the return value of a callback is ignored. Calling the error() method of the MT::Callback object ($cb in this case) propagates the error message up to the MT activity log.

Another way to handle errors is to call die. If a callback dies, MT will warn the error to the activity log, but will continue processing the MT::Object operation: so other callbacks will still run, and the database operation should still occur.