Ghazascanner_2019runbot

//homepage/v-mt/lib/MT/Callback.pod

=pod

=head1 NAME

Callback.pod - Movable Type Callbacks

=head1 DESCRIPTION

The callback system in Movable Type is easy to use and is invoked at key areas
throughout the application. This document is a reference of all available
callbacks in Movable Type itself.

It's important to note that this documentation (as with all API documentation)
applies to the B<Movable Type platform> which includes both Movable Type and 
Movable Type Enterprise.  In the rare occurance that something refers 
exclusively to one or the other, it will be explicitly noted.

=head1 OVERVIEW

What follows is a listing of each available MT callback, grouped by
system component. The callback is immediately followed by a I<signature>
which describes how to write your callback subroutine to accept the
parameters the callback provides.

For example, if the signature reads like this:

callback($cb, $param1, $param2)

Then your callback subroutine should be declared as:

sub my_callback {
        my ($cb, $param1, $param2) = @_;

}

If the callback signature looks like this:

callback($cb, %info)

Then your callback subroutine should be:

sub my_callback {
        my ($cb, %info) = @_;

}

=head1 ERROR HANDLING

The first argument to any callback routine is a I<MT::Callback>
object. You can use this object to return errors to MT.

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

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

....

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

In addition to the error() method, the I<MT::Callback> package also has
metadata related to the plugin that registered the callback:

my $plugin = $cb->plugin;

It's possible that this method will return undef if the callback
was registered without a plugin.

=head1 Naming Conventions

MT callbacks are typically in one of these forms:

=over 4

=item * CallbackName

This is a simple high-level callback. Typically an application (C<TakeDown>)
or process-oriented callback (such as C<BuildFileFilter>).

=item * callback_name

Lower-cased callbacks signify a lower-level callback. These are common in
the I<MT::Object> callbacks (such as C<pre_save>, C<post_save>, etc.)

=item * Package::CallbackName

Callbacks that are invoked with a package name prefix are used to distinguish
a callback that may be used for many classes. The transformer callbacks are
examples of this. These callbacks can also be hooked into with an wildcard
syntax:

MT->add_callback('*::CallbackName', ...)

or even just:

MT->add_callback('CallbackName', ...)

So the namespace is there when you need your callback to be for a specific
package, or can be registered without one when you want the callback to
run regardless of the package.

=item * Package::CallbackName.type

=item * CallbackName.type

This is a syntax for running callbacks with a parameter or identifier to
distinguish it. This is also used to the hooks to be more selective. Some
of the CMS application callbacks use this syntax:

MT->add_callback('CMSDeletePermissionFilter.entry', ...)

The transformer callbacks use this syntax to let you target a specific
application template:

MT->add_callback('AppTemplateSource.list_blog', ...)

Some of these also allow you to register without the suffix:

MT->add_callback('AppTemplateSource', ...)

And some also provide the package name syntax for scoping to a particular
application/object type:

MT->add_callback('MT::App::CMS::AppTemplateSource.header', ...)

This last example targets use of the header application template specifically
for the CMS application (and only the CMS application).

=back

=head1 Object Callbacks

The Object callbacks are those that are tied to I<MT::Object> and its
descendants.  This includes classes such as I<MT::Entry>, I<MT::Blog>, etc.

=over 4

=item * <package>::pre_save