NAME

Callback.pod - Movable Type Callbacks

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 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.

OVERVIEW

What follows is a listing of each available MT callback, grouped by system component. The callback is immediately followed by a 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) = @_;

}

ERROR HANDLING

The first argument to any callback routine is a 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 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.

Naming Conventions

MT callbacks are typically in one of these forms:

callback_name

This is the most common form of callback name and is generally recommended for new callbacks in order to provide consistency. Examples of these include most of the MT::Object callbacks (such as pre_save, post_save, etc.) and the MT::WeblogPublisher callbacks (e.g. build_file_filter, build_page, build_file).
CallbackName

In the past, this form was heavily used for simple high-level callbacks, typically an application callback (TakeDown) or process-oriented ones (such as PeriodicTask and DefaultTemplateFilter). However, most of the core callbacks using this format were converted to the callback_name format for the sake of consistency leaving this form mainly to plugins.
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.
Package::CallbackName.type and Package::callback_name.type
CallbackName.type and callback_name.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('template_source.list_blog', ...)
```
Some of these also allow you to register without the suffix:
```
MT->add_callback('template_source', ...)
```
And some also provide the package name syntax for scoping to a particular application/object type:
```
MT->add_callback('MT::App::CMS::template_source.header', ...)
```
This last example targets use of the header application template specifically for the CMS application (and only the CMS application).

Object Callbacks

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

<package>::pre_save
```
callback($cb, $obj, $original)
```
Callback issued prior to saving $obj to the database. $original is the instance that was invoked to be saved. If $obj->id is unset, then it is a new object.
<package>::post_save
```
callback($cb, $obj, $original)
```
Callback issued after to saving $obj to the database. $original is the instance that was invoked to be saved.
<package>::pre_update
```
callback($cb, $obj, $original)
```
Callback issued prior to saving an existing $obj to the database. $original is the instance that was invoked to be saved.
<package>::post_update
```
callback($cb, $obj, $original)
```
Callback issued after saving an existing $obj to the database. $original is the instance that was invoked to be saved.
<package>::pre_insert
```
callback($cb, $obj, $original)
```
Callback issued prior to saving a new $obj to the database. $original is the instance that was invoked to be saved.
<package>::post_insert
```
callback($cb, $obj, $original)
```
Callback issued after to saving a new $obj to the database. $original is the instance that was invoked to be saved.
<package>::pre_load
```
callback($cb, \@params)
```
\@params is an array containing the arguments that were passed to the load method.
<package>::post_load
```
callback($cb, \@params, $obj)
```
\@params is an array containing the arguments that were passed to the load method. The object returned by the load method is provided through the $obj parameter.
<package>::pre_remove
```
callback($cb, $obj)
```
<package>::post_remove
```
callback($cb, $obj)
```
<package>::pre_remove_all
```
callback($cb, $class)
```
<package>::post_remove_all
```
callback($cb, $class)
```
<package>::pre_direct_remove
```
callback($cb, $class, $terms, $args)
```
<package>::post_clone
```
callback($cb, %param)
```
This callback in particular is unique to the MT::Blog package. It is run when the user does a blog cloning operation that makes a physical copy of the weblog and it's children objects. If a plugin has data that is associated with a blog and you wish to copy that data when the blog is cloned, you should hook into this callback to capture this event.

When the blog is cloned, all of the children records are cloned along with it: entries, categories, templates, etc. As such, it may be important for you to know the original IDs of the cloned records, in addition to their new IDs. So the callback also provides this information, for the cloned entries, categories, trackback and template objects.

Parameter data passed to the callback include:
- OldObject
  
  The MT::Blog object that was been cloned. This is the original blog object, not the newly created one.
- NewObject
  
  The MT::Blog object that was created from the original.
- EntryMap
  
  A hashref containing keys of the original entry IDs and values of the newly created entry IDs.
- CategoryMap
  
  A hashref containing keys of the original category IDs and values of the newly created category IDs.
- TrackbackMap
  
  A hashref containing keys of the original trackback IDs and values of the newly created trackback IDs.
- TemplateMap
  
  A hashref containing keys of the original template IDs and values of the newly created template IDs.
- Callback
  
  A coderef that may be used to message the user as to the progress of the cloning operation. Call this with a message and a unique identifier. Each progress update with that identifier will refresh the same status message displayed. Refer to the MT::Blog::clone_with_children subroutine for further examples of using the callback.
```
$callback->("Now cloning foozles...", "foozles");
```
<package>::post_create_default_templates
```
callback($cb, $blog, $tmpl_list)
```
This callback in particular is also unique to the MT::Blog package. It is run when the user creates a new blog, or when the user refreshes all templates for existing blog to have it clean start again. If a plugin has something to do with template sets and with when user uses the particular set, you should hook into this callback to capture this event.

$blog argument carries the blog user created. $tmpl_list carries the list of template data associated to the blog.

Application Callbacks

MT::App

These callbacks are common to all MT applications that descend from the MT::App package.

<package>::pre_run
```
callback($cb, $app)
```
Called at the beginning of the request, prior to invoking the mode handler (and prior to determining the application mode, so it is possible for the callback to alter the mode at this point).
<package>::post_run
```
callback($cb, $app)
```
Called after running the mode handler for the request. This callback is run prior to the response being sent to the client.
TakeDown
```
callback($cb, $app)
```
Executed as the application is finishing the service of a request. By this time the response has been sent to the client.

In addition to the above callbacks, MT::App also provides a set of "Transformer" callbacks that are documented in their own section, "Transformer Callbacks".

MT::AtomServer and MT::XMLRPCServer

APIPreSave.entry
```
callback($cb, $app, $entry, $original)
```
This callback is invoked prior to saving the entry object. If a new entry is being saved, $entry->id will not be set.
APIPostSave.entry
```
callback($cb, $app, $entry, $original)
```
This callback is invoked after to saving the entry object. If a new entry has being saved, $original->id will not be set.
APIUploadFile
```
callback($cb, %params)
```
This callback is invoked for each file the user uploads to the weblog. This callback is similar to the CMSUploadFile callback found in MT::App::CMS. Currently, this callback is only used in MT::XMLRPCServer, since the MT::AtomServer app does not handle file uploads.

The named parameters passed for this callback are:
- File
  
  The full physical file path of the uploaded file.
- Url
  
  The full URL to the file that has been uploaded.
- Type
  
  For this callback, this value is currently always 'file'.
- Blog
  
  The MT::Blog object associated with the newly uploaded file.

MT::App::CMS

The following callbacks are unique to the MT::App::CMS package. Many of these callbacks have a <type> suffix which is one of the registered datatypes for the CMS. The available types are:

Suffix          Object Package
author       => MT::Author
comment      => MT::Comment
entry        => MT::Entry
template     => MT::Template
blog         => MT::Blog
notification => MT::Notification
templatemap  => MT::TemplateMap
category     => MT::Category
ping         => MT::TBPing
ping_cat     => MT::TBPing
group        => MT::Group
role         => MT::Role
association  => MT::Association

CMSViewPermissionFilter.<type>

Calling convention is:
```
callback($cb, $app, $id, $obj_promise)
```
Where $id is the ID of an object, if it already exists, or undef if the user will be creating a new object of this type.

$obj_promise is a promise for the object itself. You can use $obj_promise->force to get ahold of the object, if you need it, but typically you won't need it. (See MT::Promise)

Return a false value to abort the operation and display a message to the user that s/he doesn't have permission to view the object.
CMSSavePermissionFilter.<type>

Calling convention is:
```
callback($cb, $app, $id)
```
Where $id is the ID of the object, if it already exists, or undef if it is a new object with this request.

Note that at this point, the object may not yet exist. The request can be understood through the query parameters of the app, accessible through $app->param(). A CMSSavePermissionFilter callback should be "safe"--it should not modify the database.

Return a false value to abort the operation and display a message to the user that s/he doesn't have permission to modify the object. The method is not called if the acting user is a superuser.
CMSDeletePermissionFilter.<type>
```
callback($cb, $app, $object)
```
CMSSaveFilter.<type>

This callback gives you the chance to "decline" for reasons other than lack of permissions.

The routine is called as follows:
```
callback($cb, $app)
```
Returning a false value will decline the request. It is advisibable to return an error via the $cb object in order to signal to the user what went wrong.

Note that the new object has not been constructed yet. The operation can be understood by examining the $app object's query parameters via $app->param()

A CMSSaveFilter callback should be "safe"--it should not modify the database.
CMSPreSave.<type>
```
callback($cb, $app, $object, $original)
```
$object and $original hold the object which is about to be saved, and the object as it was when this request began, respectively. This allows the callback to determine what kind of changes are being attempted in the user's request. If the request is to create a new object, $original will be a valid object reference, but the object will be "blank": it will be just what is returned by the new method on that class.
CMSPostSave.<type>
```
callback($cb, $app, $object, $original)
```
$object and $original hold the object which is about to be saved, and the object as it was when this request began, respectively. When the callback routine is called, the new object as $object has already been committed to the database. This is a convenient time to trigger follow-up actions, such as notification and static-page rebuilds.
CMSPostDelete.<type>
```
callback($cb, $app, $object)
```
$object holds the object that has just been removed from the database. This callback is useful when removing data that is associated with the object being removed.
CMSUploadFile
```
callback($cb, %params)
```
This callback is invoked for each file the user uploads to the weblog. It is called for each file, regardless of type. If the user uploads an image, both the CMSUploadFile and CMSUploadImage callbacks are invoked.

The parameters passed in the %params hash include:
- File
  
  The full file path of the file that has been saved into the weblog.
- Url
  
  The URL of the file that has been saved into the weblog.
- Size
  
  The length of the file in bytes.
- Type
  
  Either 'image', 'file' or 'thumbnail'.
- Blog
  
  The MT::Blog object the uploaded file is associated with.
CMSUploadImage
```
callback($cb, %params)
```
This callback is invoked for each uploaded image. In the case the user creates a thumbnail for their uploaded image, this callback will be invoked twice-- once for the uploaded original image and a second time for the thumbnail that was generated for it.

The parameters passed in the %params hash include:
- File
  
  The full path and filename for the uploaded file.
- Url
  
  The full URL for the uploaded file.
- Size
  
  The length of the uploaded image in bytes.
- Type
  
  Either "image" or "thumbnail" (for generated thumbnails).
- Height
  
  The height of the image in pixels (available if Image::Size module is present).
- Width
  
  The width of the image in pixels (available if Image::Size module is present).
- ImageType
  
  The image identifier as reported by the Image::Size module. Typically, 'GIF', 'JPG' or 'PNG'.
- Blog
  
  The MT::Blog object of the weblog the image is associated with.
HandleJunk
```
callback($cb, $app, $object)
```
This callback is invoked when a user intentionally marks a given comment or TrackBack ping as junk. The $object can be either a MT::Comment or MT::TBPing object.
HandleNotJunk
```
callback($cb, $app, $object)
```
This callback is invoked when a user intentionally marks a given comment or TrackBack ping as non-junk. The $object can be either a MT::Comment or MT::TBPing object.
RebuildOptions
```
callback($cb, $app, \@options)
```
The RebuildOptions callback provides control over an array of additional custom rebuild options that are displayed in MT's rebuild window. The array is populated with hashrefs, each containing:

code

The code to execute when running the custom rebuild option.

label

The label to display in the list of rebuild options.

key

An identifier unique to this option (optional, will derive from the label if unavailable).
```
MT->add_callback('RebuildOptions', 5, undef, \&add_rebuild_options);
sub add_rebuild_options {
    my ($cb, $app, $options) = @_;
    push @$options, {
        code => \&rebuild_by_author,
        label => "Rebuild My Entries",
        key => "rebuild_by_author",
    }
}
```

MT::App::Comments

This application handles receiving all comments posted to the Movable Type installation.

CommentThrottleFilter
```
callback($cb, $app, $entry)
```
Called as soon as a new comment has been received. The callback must return a boolean value. If the return value is false, the incoming comment data will be discarded and the app will output an error page about throttling. A CommentThrottleFilter callback has the following signature:
```
sub comment_throttle_filter {
    my ($cb, $app, $entry) = @_;
    ...
    $boolean; # 1 to accept, 0 to reject
}
```
$app is the MT::App::Comments object, whose interface is documented in MT::App::Comments, and $entry is the entry on which the comment is to be placed.

Note that no comment object is passed, because it has not yet been built. As such, this callback can be used to tell the application to exit early from a comment attempt, before much processing takes place.

When more than one CommentThrottleFilter is installed, the data is discarded unless all callbacks return true.
CommentFilter
```
callback($callback, $app, $comment)
```
Called once the comment object has been constructed, but before saving it. If any CommentFilter callback returns false, the comment will not be saved. The callback has the following signature:
```
sub comment_filter {
    my ($cb, $app, $comment) = @_;
    ...
    $boolean; # 1 to accept, 0 to reject
}
```

MT::App::Trackback

This application handles receiving all TrackBack pings sent to the Movable Type installation.

TBPingThrottleFilter
```
callback($cb, $app, $trackback)
```
This callback is issued early on upon receiving a TrackBack ping and it allows the callback code to return a boolean as to whether the request should be accepted or rejected. So if the callback returns 0, it signals a reject for the ping. Returning 1 will accept it for further processing.
```
sub trackback_throttle_filter {
    my ($cb, $app, $trackback) = @_;
    ...
    $boolean; # 1 to accept, 0 to reject
}
```
TBPingFilter
```
callback($cb, $app, $ping)
```
Called once the TrackBack ping object has been constructed, but before saving it. If any TBPingFilter callback returns false, the ping will not be saved. The callback has the following signature:
```
sub trackback_filter {
    my ($cb, $app, $ping) = @_;
    ...
    $boolean; # 1 to accept, 0 to reject
}
```

MT::App::ActivityFeeds

The Activity Feeds application handles the generation of various system activity feeds, based on the contents of the system activity log. The application uses callbacks to dispatch the creation of the feed. The callbacks that are used include:

ActivityFeed
ActivityFeed.system
ActivityFeed.comment
ActivityFeed.ping
ActivityFeed.entry
ActivityFeed.debug
ActivityFeed.blog

All ActivityFeed callbacks have the same callback signature:

callback($cb, $app, $view, $feed)

The $view parameter is one of 'system', 'comment', 'ping', 'entry', 'blog', 'debug', or whatever is given using the 'view' parameter to the activity feed script.

The $feed parameter is a scalar reference to a string-- the contents of the generated feed. Upon return, this value is printed out. The content should be an Atom-based feed.

API Callbacks

Publishing

The Movable Type publishing callbacks are invoked from the MT::WeblogPublisher module. These callbacks are used to allow manipulation of the publishing process.

build_file_filter

This filter is called when Movable Type wants to rebuild a file, but before doing so. This gives plugins the chance to determine whether a file should actually be rebuild in particular situations.

A build_file_filter callback routine is called as follows:
```
sub build_file_filter {
    my ($cb, %args) = @_;
    ...
    return $boolean;
}
```
As with other callback functions, the first parameter is an MT::Callback object. This can be used by the callback to propagate an error message to the surrounding context.

The %args parameters identify the page to be built. See MT::FileInfo for more information on how a page is determined by these parameters. Elements in %args are as follows:
- Context
  
  Holds the template context that has been constructed for building (see MT::Template::Context).
- ArchiveType
  
  The archive type of the file, usually one of 'Index', 'Individual', 'Category', 'Daily', 'Monthly', or 'Weekly'.
- TemplateMap
  
  An MT::TemplateMap object; this singles out which template is being built, and the filesystem path of the file to be written.
- Blog
  
  The MT::Blog object representing the blog whose pages are being rebuilt.
- Entry
  
  In the case of an individual archive page, this points to the MT::Entry object whose page is being rebuilt. In the case of an archive page other than an individual page, this parameter is not necessarily undefined. It is best to rely on the $at parameter to determine whether a single entry is on deck to be built.
- PeriodStart
  
  In the case of a date-based archive page, this is a timestamp at the beginning of the period from which entries will be included on this page, in Movable Type's standard 14-digit "timestamp" format. For example, if the page is a Daily archive for April 17, 1796, this value would be 17960417000000. If the page were a Monthly archive for March, 2003, $start would be 20030301000000. Again, this parameter may be defined even when the page on deck is not a date-based archive page.
- Category
  
  In the case of a Category archive, this parameter identifies the category which will be built on the page.
- FileInfo
  
  If defined, an MT::FileInfo object which contains information about the file. Chief amongst all the members of MT::FileInfo, for these purposes, will be the virtual member. This is a boolean value which will be false if a page was actually created on disk for this "page," and false if no page was created (because the corresponding template is set to be built dynamically).
  
  It is possible for the FileInfo parameter to be undefined, namely if the blog has not been configured to publish anything dynamically, or if the installation is using a data driver that does not support dynamic publishing.
build_page

This callback is invoked just after a page has been built, but before the content has been written to the file system.
```
sub build_page {
    my ($cb, %args) = @_;
    ...
}
```
The parameters given are include those sent to the build_file_filter callback. In addition, the following parameters are also provided:
- Content
  
  This is a scalar reference to the content that will eventually be published.
- BuildResult / (or RawContent, deprecated)
  
  This is a scalar reference to the content originally produced by building the page. This value is provided mainly for reference; modifications to it will be ignored.
build_file

This callback is invoked just after a file has been built and written to the filesystem. Unlike the callbacks above, this callback will only be triggered if the content compiled for the page differs from that in the target file.
```
sub build_file {
    my ($cb, %args) = @_;
    ...
}
```
Parameters in %args are the same as those provided by the build_page callback.

Transformer Callbacks

These callbacks are available for any MT application that descends from the MT::App class. These callbacks

<package>::AppTemplateSource
<package>::AppTemplateSource.<filename>
```
callback($cb, $app, \$tmpl_str)
```
Executed after loading the HTML::Template file. The <package> portion is the full package name of the application running. For example,
```
MT::App::CMS::AppTemplateSource.menu
```
Is the full callback name for loading the menu.tmpl file under the MT::App::CMS application. The "MT::App::CMS::AppTemplateSource" callback is also invoked for all templates loading by the CMS. Finally, you can also hook into:
```
*::AppTemplateSource
```
as a wildcard callback name to capture any HTML::Template files that are loaded regardless of application.
<package>::AppTemplateParam
<package>::AppTemplateParam.<filename>
```
callback($cb, $app, \%param, $tmpl_obj)
```
This callback is invoked in conjunction with the MT::App->build_page method. The $param argument is a hashref of HTML::Template parameter data that will eventually be passed to the template to produce the page.
<package>::AppTemplateOutput
<package>::AppTemplateOutput.<filename>
```
callback($cb, $app, \$tmpl_str, \%param, $tmpl_obj)
```
This callback is invoked in conjunction with the MT::App->build_page method. The $tmpl_str parameter is a string reference for the page that was built by the MT::App->build_page method. Since it is a reference, it can be modified by the callback. The $param parameter is a hash reference to the parameter data that was given to build the page. The $tmpl parameter is the HTML::Template object used to generate the page.

Default Templates

When a new weblog is created, Movable Type uses the MT::DefaultTemplates module to retrieve the set of default templates to be installed. It also invokes a callback that provides plugins an opportunity to alter the set of default templates (either to amend, or to filter them).

DefaultTemplateFilter
```
callback($cb, \@templates)
```
This callback is invoked prior to returning the list of default templates. This provides plugins an opportunity to adjust the set of default templates, by amending it, supplementing it, etc., using @templates array reference passed to the callback. The contents of the array are hash references, each containing the following keys:
- type
  
  The type of template. This should be one of the following values:
  - index
    
    An index template.
  - individual
    
    An individual archive template.
  - category
    
    A category archive template.
  - archive
    
    A date-based archive template.
  - comment_preview
    
    A system template for comment previews.
  - search_template
    
    A system template for search results.
  - comment_pending
    
    A system template for the comment pending page.
  - comment_error
    
    A system template for comment errors.
  - popup_image
    
    A system template for inserting popup images.
  - comments
    
    A system template for listing comments for a particular entry.
  - dynamic_error
    
    A system template for a dynamic publishing error page.
  - pings
    
    A system template for listing TrackBack pings.
  Note that only one template may be defined for each "system" template type.
- name
  
  The name to give to the template being installed.
- outfile
  
  The name of the output file when building a non-system template.
- rebuild_me
  
  Set to '1' to cause the 'index' type templates to be rebuilt upon publishing new entries.
- text
  
  The full text of the template. This template may also contain <MT_TRANS> tags which will become localized upon installing it to the database. Note: For plugins that are providing custom templates, the plugin should do the localize step itself, prior to providing the text to the callback. This will allow the plugin to use it's own lexicon for localizing the template for the currently logged-in user.

New User Provisioning

This feature is only available in Movable Type Enterprise.

NewUserProvisioning
```
callback($cb, $user)
```
This callback is invoked when a user is being added to Movable Type. Movable Type itself registers for this callback (with a priority of 5) to provision the user with a new weblog if the system has been configured to do so.

Upgrade API

MT::Upgrade::SQL

Called with each SQL statement that is executed against the database as part of the upgrade process. The parameters passed to this callback are:
```
callback($cb, $app, $sql_statement)
```
The first parameter is an MT::Callback object. $upgrade_app is a package name or MT::App object used to drive the upgrade process. $sql_statement is the actual SQL query that is about to be executed against the database.

Task API

PeriodicTask
```
callback($cb)
```
Prior to running scheduled tasks, this callback is invoked. It may be a point where a plugin might conditionally add a task to the list of tasks to run.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Callback.pod

Callback.pod

NAME

DESCRIPTION

OVERVIEW

ERROR HANDLING

Naming Conventions

Object Callbacks

Application Callbacks

MT::App

MT::AtomServer and MT::XMLRPCServer

MT::App::CMS

MT::App::Comments

MT::App::Trackback

MT::App::ActivityFeeds

API Callbacks

Publishing

Transformer Callbacks

Default Templates

New User Provisioning

Upgrade API

Task API

METHODS

invoke

method

new

plugin

Files

Callback.pod

Latest commit

History

Callback.pod

File metadata and controls

NAME

DESCRIPTION

OVERVIEW

ERROR HANDLING

Naming Conventions

Object Callbacks

Application Callbacks

MT::App

MT::AtomServer and MT::XMLRPCServer

MT::App::CMS

MT::App::Comments

MT::App::Trackback

MT::App::ActivityFeeds

API Callbacks

Publishing

Transformer Callbacks

Default Templates

New User Provisioning

Upgrade API

Task API

METHODS

invoke

method

new

plugin