Events and Callbacks in Movable Type

Movable Type Callback Reference

See the table of contents for links to the following sections broken out into individual pages.

Quick Review

As Movable Type operates, events within the system are constantly occurring. Some plugins may want to be notified in some fashion when these events happen, and be passed information about the event so that they can respond properly. To do so, a developer needs to register a handler, also known as a callback, via the Movable Type registry. Here is a sample config.yaml file that registers a handler for a fictional event:

name: Example Plugin for Movable Type
id: Example
key: Example
description: This plugin is an example plugin for Movable Type.
version: 1.0
callbacks:
    CallBackName: $Example::Example::Plugin::my_callback

The developer then needs to implement the handler in their plugin. For the above example, a developer would create the following Plugin.pm:

package Example::Plugin;
use strict;
use MT 4;
sub my_callback {
    my ($cb, ...) = @_;
        return $cb->error("Error message");
    }
}

The parameters passed to the callback vary depending upon the event for which the callback is associated. The expected return value from the callback also depends upon the event that has occurred. The following appendix outlines each of the major categories of callbacks that can be registered, their input parameters, and their expected return values.

Activity Feed Callbacks

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.blog
ActivityFeed.comment
ActivityFeed.debug
ActivityFeed.entry
ActivityFeed.page
ActivityFeed.ping
ActivityFeed.system

Input Parameters

$cb - a reference to the MT::Callback object
$app - a reference to the MT::App::ActivityFeeds object processing this request.
$view - a string referring to the type of activity feed log entry is being produced. Acceptable values are:
- system
- comment
- blog
- ping
- debug
- entry
- page
$feed - a scalar reference to a string which corresponds to the contents of the generated feed. Upon return, this value is printed out. The content should be an Atom-based feed.

Example Handler

sub handler {
    my ($cb,$app,$view,$feed) = @_;
    # do your thing
    $$feed = "foo";
}

Application Callbacks

Application callbacks are invoked by Movable Type during the course of a user interacting with the core Movable Type application. They mark key points during the life-cycle of a request, like the initialization phase, or the terminus. They are (in the order in which they are invoked):

init_request
pre_run
post_run
TakeDown

Because Movable Type is broken up into multiple distinct applications, you will need to know specifically which application you wish to attach your callback handler to by its package name. The following is a list of known Movable Type applications:

MT::App::ActivityFeeds - this application renders Movable Type’s activity feeds in Atom.
MT::App::Comments - this application processes incoming comments.
MT::App::CMS - this application processes all requests to the main Movable Type administration user interface.
MT::App::NotifyList - this application processes subscriptions (deprecated).
MT::App::Search - this application processes search requests made from the published blog.
MT::App::Trackback - this application processes incoming pings.
MT::App::Upgrader - this application processes all automated upgrades.
MT::App::Wizard - this application process the installation wizard.

Let’s take a look at an example. Let’s say you wanted to attach a handler to the initialization phase of the commenting application. You would do this by appending the name of the application with the name of the callback, and registering in association with that the handler to process the callback in your config.yaml like so:

name: Example Plugin for Movable Type
id: Example
key: Example
description: This plugin is an example plugin for Movable Type.
callbacks:
    MT::App::Comments::init_request: $Example::Example::Plugin::handler

init_request

The init_request callback is invoked just prior to a mode handler being processed, but after all the other information has been marshaled. It can be used to inspect and/or modify a request prior processing or rendering any HTML to the browser. One use case in which it has been commonly used is to modify the templates used to render the application, as is done in the iPhone plugin for Movable Type which will use a different set of templates based upon the user agent (the text string transmitted by the browser identifying the client software by name, e.g. “Firefox”).

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.

Return Value

None.

Example Handler

sub init_request_handler {
    my ($cb, $app) = @_;
    # do something
}

pre_run

The pre_run callback is invoked at the beginning of the request, prior to invoking the mode handler. It is also invoked prior to the determining of the application mode that will be used to process the request, so this callback makes it possible for example to alter the mode that will ultimately be used.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.

Return Value

None.

Example Handler

sub pre_run_handler {
    my ($cb, $app) = @_;
    # do something
}

post_run

The post_run callback is invoked immediately after running the mode handler for the request, but prior to the response being sent to the client.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.

Return Value

None.

Example Handler

sub pre_run_handler {
    my ($cb, $app) = @_;
    # do something
}

TakeDown

This callback is invoked as the application is finishing the service of a request. By this time the response has been sent to the client.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.

Return Value

None.

Example Handler

sub pre_run_handler {
    my ($cb, $app) = @_;
    # do something
}

Backup and Restore Callbacks

These events are fired while content is being backed up or restored using the Backup/Restore feature of Movable Type. They are used by plugins to handle how data they store are to be serialized and deserialized by Movable Type for the purposes of data retention and recovery.

MT::BackupRestore::Backup

This callback is invoked when a user initiates a backup of one or more blogs. The callback is invoked once regardless of how many blogs were selected for backup. The handler for this callback should return the XML that should be appended to the end of the backup file.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$blog_ids - an array of integers representing the list of blogs the user has requested to have backed up. If the array is empty, it is an indicator that the user has requested to have everything backed up.
$progress -

Return Value

A string of valid and well-formed XML. The value returned will be appended to the end of the backup file.

Example Handler

sub backup_handler {
    my ($cb, $blog_ids, $progress) = @_;
    my $xml = '';
    # do my thing
    return $xml;
}

MT::BackupRestore::restore

This callback is called when all of the XML files in the particular restore session are restored, thus, when $objects and $deferred would not have any more objects in them. In other words, this callback is invoked when all of the relevant objects have been restored and reconstituted.

This callback is therefore useful for restoring the relationships between two objects. For example, suppose one object may wish to reference or link to another, however during the restoration process it is not guaranteed that the both objects will exist at the time the individual Restore.$Localname:$Namespace callback is invoked. Therefore, this function is called at the very end of the process allowing you to subsequently link related objects to one another.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$objects - a hash reference which contains all the restored objects in the restore session. The hash keys are stored in the format MT::ObjectClassName#old_id.
$deferred - a hash reference which contains information about restore-deferred objects. Deferred objects are those objects which appeared in the XMl file but could not be restored because any parent objects are missing. The hash keys are stored in the format MT::ObjectClassName#old_id and hash values are 1.
$errors - an array ref for communicating errors back to the user.
$callback - a code reference which will print out the passed parameter. Callback method can use this to communicate with users.

Return Value

None.

Example Handler

sub restore_handler {
    my ($cb, $objects, $deferred, $errors, $callback) = @_;
    if (<error condition>) {
        push @$errors, "My error string.";
    }
}

MT::BackupRestore::restore_asset

This callback is called when an asset’s physical file is restored.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$asset - a reference to the MT::Asset object that was restored. At the time this callback is invoked, the asset in question has already been assigned a new url and path.
$callback - a code reference which will print out the passed parameter. Callback method can use this to communicate with users.

Return Value

None.

Example Handler

sub restore_asset_handler {
    my ($cb, $asset, $callback) = @_;
}

Restore.$Localname:$Namespace

This callback is invoked for each element found in the Movable Type backup file. If you have registered a backup handler that inserts XML into the backup file, then this callback is invoked when those XML elements are encountered during the restoration process. In this case $Localname refers to the XML element name, and $Namespace refers to the namespace of the element.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$data - is a parameter which was passed to XML::SAX::Base’s start_element callback method
$objects - a hash reference which contains all the restored objects in the restore session. The hash keys are stored in the format MT::ObjectClassName#old_id.
$deferred - a hash reference which contains information about restore-deferred objects. Deferred objects are those objects which appeared in the XMl file but could not be restored because any parent objects that were missing at the time. The hash keys are stored in the format MT::ObjectClassName#old_id and hash values are 1.
$callback - a code reference which will print out the passed parameter. Callback method can use this to communicate with users.

Return Value

None.

Example Handler

sub restore_element_handler {
    my ($cb, $data, $objects, $deferred, $callback) = @_;
}

CMS Callbacks

CMS callbacks are a subset of application callbacks that are invoked exclusively by the main Movable Type CMS application. They relate to specific actions that a user can perform within the context of the application.

MT::App::CMS::cms_post_delete.$type

This callback is invoked after an object has been deleted, and after all other operations have taken place in response to that object being deleted (removing related comments for entries for example). This callback is invoked as the very last step following an object’s removal. In this callback $type refers to the object type.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.
$obj - a reference to the MT::Object being deleted.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app, $obj) = @_;
    # do something
}

Note: this is different from MT::ObjectName.post_delete in that it is called after other related records have been removed and/or processed as well.

MT::App::CMS::cms_post_save.$type

This callback is invoked after an object has been saved, and after all other operations have taken place in response to that object being saved, created or updated (associating an entry to categories for example). This callback is invoked as the very last step following an object being saved. In this callback $type refers to the object type.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.
$obj - a reference to the MT::Object being saved.
$original - a reference to the original MT::Object prior to it being modified.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app, $obj, $original) = @_;
    # do something
}

Note: this is different from MT::ObjectName.post_save in that it is called after other related records have been created and/or processed as well.

MT::App::CMS::cms_pre_save.$type

This callback is invoked prior to a user saving an object via the Movable Type application. This callback is most often used by developers to save the state of the form/screen used to submit the entry. For example, the size of the WYSIWYG editor is “sticky,” meaning Movable Type will remember the size of the WYSIWYG editor between screens. This is accomplished through this callback. When a user submits the Edit Entry form, the callback retrieves from the form input parameters the size of the textarea and saves it for later retrieval.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing this request.
$obj - a reference to the MT::Object being saved.
$original - a reference to the original MT::Object prior to it being modified.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app, $obj, $original) = @_;
    my $height = $app->param('text_editor_size');
    # do something
}

MT::App::CMS::cms_view_permission_filter.$type

This callback is invoked when a user is attempting to view an object of a designated type (as specified by $type) from within the Movable Type application. The intent of this callback is to give plugins the opportunity to revoke the current user’s permission to view the correlated object.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing the request.
$id - the ID of the object, if it already exists, or “undef” if it is a new object with this request.
$obj_promise - 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.

Return Value

A boolean (true/false) value. Returning false will revoke the current user’s ability to view the corresponding object.

Example Handler

sub handler {
    my ($cb, $app, $id, $obj_promise) = @_;
    if ($id % 2 == 0) { return 0; }
    return 1;
}

MT::App::CMS::cms_save_permission_filter.$type

This callback is invoked when a user is attempting to save an object of a designated type (as specified by $type) from within the Movable Type application. The intent of this callback is to give plugins the opportunity to revoke the current user’s permission to save the correlated object.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing the request.
$id - the ID of the object, if it already exists, or “undef” if it is a new object with this request.

Return Value

A boolean (true/false) value. Returning false will revoke the current user’s ability to save the corresponding object.

Example Handler

sub handler {
    my ($cb, $app, $id) = @_;
    if ($id % 2 == 0) { return 0; }
    return 1;
}

MT::App::CMS::cms_delete_permission_filter.$type

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::CMS object processing the request.
$obj - a reference to the MT::Object being deleted.

Return Value

A boolean (true/false) value. Returning false will revoke the current user’s ability to delete the corresponding object.

Example Handler

sub handler {
    my ($cb, $app, $obj) = @_;  
    if ($obj->id % 2 == 0) { return 0; }
    return 1;
}

MT::App::CMS::cms_save_filter.$type

This callback is invoked just prior to saving an object and is typically used for validating form input submitted by the user. The callback can be targeted to a specific data type by modifying the value of $type with one of the registered MT::Objects or data types.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a handle to the current MT::App::CMS object processing this request.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app) = @_;
    if ($app->param('some_form_input') !~ /^\d+$/) {
        return $cb->error("The field 'some form input' must be a numeric value.");
    }
}

MT::App::CMS::cms_upload_file

This callback is invoked just after a file (not an image) has been uploaded. It passes to the handler information about the file that was uploaded so that additional information can be gathered, or additional transformations can be applied to the file.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$params - a hash ref containing information about the uploaded file.

The following are the keys of the parameter ($params) hash passed into the handler as input:

File or file - a link to the file on the filesystem
Url or url - the URL to the file
Size or size - the size of the file in bytes
Asset or asset - a reference to the MT::Asset object
Type or type - the type of asset
Blog or blog - the blog ID

Return Value

None.

Example Handler

sub handler {
    my ($cb, $params) = @_;
    MT::Log->log({ message => "user uploaded a file at " . $params->{Url} });
}

MT::App::CMS::cms_upload_image

This callback is invoked just after an image has been uploaded. It passes to the handler information about the image that was uploaded so that additional information can be gathered, or additional transformations can be applied to the image.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$params - a hash ref containing information about the uploaded file.

The following are the keys of the parameter ($params) hash passed into the handler as input:

File or file - a link to the file on the filesystem
Url or url - the URL to the file
Size or size - the size of the file in bytes
Asset or asset - a reference to the MT::Asset object
Type or type - the type of asset
Blog or blog - the blog ID
Width or width - the width of the image
Height or height - the height of the image
ImageType or image_type - the mime type of the image (e.g. jpeg, png, gif, etc.)

Return Value

None.

Example Handler

sub handler {
    my ($cb, $params) = @_;
}

app_pre_listing_$app->mode

This callback is used by developers to intercept calls to Movable Type to generating a listing screen created by the $app->listing() method (see Developing Movable Type Applications). This method provides a short hand way to generate complex listing screens in Movable Type.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app, $terms, $args, $param, $hasher) = @_;
}

mail_filter

The mail_filter callback is invoked just prior to Movable Type sending an email.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$params - a hash ref containing information about the email being sent.

The following are the keys of the parameter ($params) hash passed into the handler as input:

args - a reference to all of the arguments passed to MT::Mail->send
headers - a reference to an associative array containing all of the SMTP headers for the email.
body - the text of the email
transfer - the value of MailTransfer (sendmail or smtp)
id - the ID of the template in string form, effectively identifying the email type, used to generate this email (optional)

Return Value

None.

Example Handler

sub handler {
    my ($cb, $params) = @_;
    $params->{headers}->{Content-Type} = "text/html";
}

Comment Callbacks

Comment callbacks are invoked as a part of the comment submission process. They are invoked to give plugins an opportunity to short circuit the process and keep a comment from being committed to the database.

CommentFilter

This callback is invoked just prior to the MT::Comment object being saved. The callback is invoked prior to any spam/junk filtering or scoring being performed on the comment. This callback is a way for plugins to intercept the form submission of any newly submitted comment and perform additional validation on the comment.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - An instance of the MT::App::Comments used to process this comment submission.
$comment - A reference to the MT::Comment object being processed.

Return Value

A boolean (true/false) value. If any comment filter callback returns false (zero), the corresponding comment will not be saved in the database.

Example Handler

sub handler {
    my ($cb, $app, $comment) = @_;
    if ($comment->text =~ /a bad word/gm) {
        MT::Log->log({message => "Not saving comment
            because it has a bad word in it."})
        return 0;
    }
    return 1;
}

Tip: developers should consider logging a message in the activity log as to why a comment is being rejected, as this callback is otherwise opaque.

CommentThrottleFilter

This callback is invoked as soon as a new comment has been received, but prior to the comment being instantiated. If the callback returns false (zero), then the comment will be discarded and the Movable Type will output an error page about throttling. When more than one CommentThrottleFilter are chained together, the data is discarded unless all callbacks return true.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - the MT::App::Comments object, whose interface is documented in MT::App::Comments
$entry - the entry on which the comment is to be placed.

You may notice that no comment object (MT::Comment) is passed to the callback because it has not yet been built. This has the advantage of allowing this callback to short circuit the commenting process before before much processing and overhead takes place.

Return Value

A boolean (true/false) value. If any comment throttle filter callback returns false (zero), the corresponding comment will not be saved in the database, and Movable Type will display an error to the user about their comment being “throttled.”

Example Handler

sub comment_throttle_filter {
    my ($cb, $app, $entry) = @_;
}

Template Set Callbacks

TODO

DefaultTemplateFilter.$template_set_id

When a user applies a template set to a blog, Movable Type invokes this callback to allow plugins an opportunity to alter the set of templates being applied to the blog, either to amend, or to filter them.

Specific template sets can be targeted by appending the template set ID for which this callback applies, or can be applied to all template sets by omitting the template set ID.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$templates - an array reference to the templates being applied. Because it is a reference to the array, developers can insert additional templates into the set to be installed, or even remove templates from the template.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $templates) = @_;
    # loop over the templates
    foreach my $tmpl (@$templates) {
        # do something
    }
    # add a template
    my $t = MT::Template->new;
    # do stuff
    push @$templates, $t;
}

blog_template_set_change

This callback is invoked whenever a user applies a template set to their blog. It is not invoked when a user is refreshing an existing template set. This callback can be used for example to populate the blog with sample content appropriate for the related template set (e.g. an “About” page, or a “Contact Me” page).

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$params - a hash ref containing information about the blog to which the template set is being applied.

The following are the keys of the parameter ($params) hash passed into the handler as input:

blog - a reference to MT::Blog object whose template set was just changed.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $params) = @_;
    my $set = $param->{blog}->template_set || '';
    # do something
}

Junk Handling Callbacks

Junk handling callbacks are used by plugins to handle comments that categorized as ham or spam incorrectly. These callbacks allow plugins to take action on a comment or TrackBack in addition to simply changing its junk status from true to false, or vice versa.

In each of the callbacks below, Movable Type passes in a reference to the MT::App processing the request, and a reference to the object, either a comment or TrackBack being reclassified.

handle_ham

This callback is invoked when a user re-classifies a comment from being spam to being ham.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App object processing this request.
$thing - a reference to the MT::Comment or MT::TBPing being flagged as ham.

Return Value

None.

Example Handler

sub handle_spam {
    my ($cb, $app, $thing) = @_;
    # do something
}

handle_spam

This callback is invoked when a user re-classifies a comment from being ham to being spam.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App object processing this request.
$thing - a reference to the MT::Comment or MT::TBPing being flagged as spam.

Return Value

None.

Example Handler

sub handle_ham {
    my ($cb, $app, $thing) = @_;
    # do something
}

New User Provisioning

new_user_provisioning

Object Level Callbacks

TODO: CMS cs Object-level

See Appendix B: MT::Object POD Documentation, CALLBACKS.

Publishing

TODO

build_file

This callback is invoked just after a file has been built and written to the filesystem. Unlike the build_page and build_file_filter callbacks, 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.

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 rebuilt in particular circumstances.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$args - An associative array that identifies the page being built.

The $args input parameter is a hash, or associative array with the following keys:

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. See MT::FileInfo for more information about what a MT::FileInfo contains. 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.

Return Value

None.

Example Handler

    sub build_file_filter {
        my ($cb, %args) = @_;
        if ($args->{Entry}->author->name eq "Byrne") {
            return 0; # don't publish anything by Byrne
        } 
        return 1;
    }

build_page

BuildPage callbacks are invoked just after a page has been built, but before the content has been written to the file system.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$args - An associative array that identifies the page being built.

The parameters given are include those sent to the BuildFileFilter callback. In addition, the following parameters are also given:

Content - This is a scalar reference to the content that will eventually be published.
BuildResult - 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.

Return Value

None.

Example Handler

sub build_page {
    my ($cb, %args) = @_;
}

pre_delete_archive_file

This callback is invoked just prior to an archive file, a file that is generated by the combination of an Archive template and an Archive Map, is deleted.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$path - the absolute path on the local file system to the file being removed.
$type - the archive type of the file being published, usually one of ‘Index’, ‘Individual’, ‘Category’, ‘Daily’, ‘Monthly’, or ‘Weekly’.
$entry - The entry object, if in reference to an individual archive. Undefined otherwise.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $path, $type, $entry) = @_;
    # do something
}

post_delete_archive_file

This callback is invoked just after to an archive file, a file that is generated by the combination of an Archive template and an Archive Map, is deleted.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$path - the absolute path on the local file system to the file being removed.
$type - the archive type of the file being published, usually one of ‘Index’, ‘Individual’, ‘Category’, ‘Daily’, ‘Monthly’, or ‘Weekly’.
$entry - The entry object, if in reference to an individual archive. Undefined otherwise.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $path, $type, $entry) = @_;
    # do something
}

rebuild_options

This callback provides control over an array of additional custom rebuild options that are displayed in MT’s rebuild window.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - A reference to the MT::App instance processing the rebuild request.
$options - An array of hash references, for which each hash contains the following keys:
- 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).

The options input parameter is used to populate the pull down menu that appears in the Movable Type publishing pop-up.

Return Value

None.

Example Handler

sub add_rebuild_options {
    my ($cb, $app, $options) = @_;
    push @$options, {
        code => \&rebuild_by_author,
        label => "Rebuild My Entries",
        key => "rebuild_by_author",
    }
}

Task Callbacks

PeriodicTask

Prior to running any registered tasks, this callback is issued to allow any registered MT plugins to add additional tasks to the list or simply as a way to signal tasks are about to start. This callback sends no parameters, but it is possible to retrieve the active MT::TaskMgr instance using the instance method.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.

Return Value

None.

Example Handler

sub handler {
    my ($cb) = @_;
    # do something
}

tasks

Upon initialization of the Task Manager instance, the list of Movable Type tasks are gathered from the MT registry.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$tasks - a hash reference of tasks being executed.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $tasks) = @_;
    foreach my $task (keys %$tasks) {
        # do something
    }
}

TrackBack Callbacks

Movable Type’s implementation of TrackBack has two closely associated objects or data types that bear the need for some explanation and clarification. Without going into too much technical details about the TrackBack protocol, let’s attempt to disambiguate between these two entities: TrackBacks and Pings.

A “TrackBack” is defined as a generic entity within a system that is eligible to receive pings, or has received pings in the past. A “Ping” then is the actual piece of data that correlates two otherwise unlinked entities together.

Why is this confusing? Well, colloquially bloggers and the industry at large has often used these terms interchangeably, and the manner in which these terms are used do not harmonize well with their technical implementation. This is a very difficult conflict to resolve, so it is important that you as the developer recognize that this consistency exists when dealing with the following callbacks.

TBPingFilter

This callback is invoked just prior to the MT::TBPing object being saved. The callback is invoked prior to any spam/junk filtering or scoring being performed on the ping. This callback is a way for plugins to intercept the submission of any newly submitted ping and perform additional validation on the ping.

If any TrackBack ping filter callback returns false (zero), the ping will not be saved in the database.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - An instance of the MT::App::Trackbacks used to process this comment submission.
$ping - The MT::Comment object.

Return Value

A boolean (true/false) value. If any TrackBack filter callback returns false (zero), the corresponding TrackBack ping will not be saved in the database.

Example Handler

sub handler {
    my ($cb, $app, $ping) = @_;
    if ($ping->text =~ /a bad word/gm) {
        MT::Log->log({message => "Not saving ping
            because it has a bad word in it."})
        return 0;
    }
    return 1;
}

TBPingThrottleFilter

This callback is invoked as soon as a new TrackBack ping has been received. If the callback returns false (zero), then the ping will be discarded and the Movable Type will output an error page about throttling. When more than one TBPingThrottleFilter are chained together, the ping is discarded unless all callbacks return true.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - the MT::App::Trackback object, whose interface is documented in MT::App::Comments
$trackback - the TrackBack to which the ping is being sent. The MT::TrackBack object will contain a reference to the entry, page or category a ping is in direct relation to.

Return Value

A boolean (true/false) value. If any TrackBack throttle filter callback returns false (zero), the corresponding TrackBack ping will not be saved in the database, and Movable Type will return an error to the service sending the ping about their ping being “throttled.”

Example Handler

sub comment_throttle_filter {
    my ($cb, $app, $trackback) = @_;
    my $entry = $trackback->entry();
    # do something
}

You will notice that a reference to the TrackBack is passed to this callback. A “TrackBack” is technically the node within the system that is eligible to receive pings. This abstraction layer exists because pings can technically be associated with entries, pages and categories.

Transformation Callbacks

template_source
template_param
template_output

Upgrade Callbacks

TODO

MT::Upgrade::SQL

This callback is invoked for each SQL statement that is executed against the database as part of the upgrade process.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to the MT::App::Upgrade object processing this request.
$sql - the SQL about to be invoked by Movable Type.

Return Value

None.

Example Handler

sub handler {
    my ($cb,$app,$sql) = @_;
    # do something
}

XMLRPC/Atom Callbacks

TODO

api_pre_save.$obj_type

This callback is invoked prior to saving the entry object via the XML-RPC or Atom API. If a new entry is being saved, “$entry->id” will not be set.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to TODO object processing this request.
$entry -
$original -

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app, $entry, $original) = @_;
}

api_post_save.$obj_type

This callback is invoked after to saving the entry object via the XML-RPC or Atom API. The callback is invoked after the object has been saved, and after all other operations related to saving the options have been completed, where as the object level post_save callback is invoked just prior to these operations. This callback is invoked subseq If a new entry has being saved, “$original->id” will not be set.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$app - a reference to TODO object processing this request.
$entry -
$original -

Return Value

None.

Example Handler

sub handler {
    my ($cb, $app, $entry, $original) = @_;
}

api_upload_file

This callback is invoked for each file the user uploads to their blog via the XML-RPC API. This callback is similar to the CMSUploadFile callback found in MT::App::CMS.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
$params - a hash reference containing a set of name/value pairs describing the file being uploaded.

The parameters passed in via the params input parameters are identified by the following keys:

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.

Return Value

None.

Example Handler

sub handler {
    my ($cb, $params) = @_;
}

Note: Currently, this callback is only used in MT::XMLRPCServer, since the MT::AtomServer app does not handle file uploads.

api_upload_image

This callback is invoked for each file the user uploads to their blog via the XML-RPC API. This callback is similar to the CMSUploadFile callback found in MT::App::CMS.

Input Parameters

$cb - a reference to the current MT::Callback object handling this event.
params - a hash reference containing a set of name/value pairs describing the file being uploaded.

The parameters passed in via the params input parameters are identified by the following keys:

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.
Width - the width of the image
Height - the height of the image
ImageType - the mime type of the image (e.g. jpeg, png, gif, etc.)

Return Value

None.

Example Handler

sub handler {
    my ($cb, $params) = @_;
}

Note: Currently, this callback is only used in MT::XMLRPCServer, since the MT::AtomServer app does not handle file uploads.

api_upload_file.$asset_class

TODO Similar to the

Events and Callbacks in Movable Type

Movable Type Callback Reference

Activity Feed Callbacks

Application Callbacks

init_request

pre_run

post_run

TakeDown

Backup and Restore Callbacks

MT::BackupRestore::Backup

MT::BackupRestore::restore

MT::BackupRestore::restore_asset

Restore.$Localname:$Namespace

CMS Callbacks

MT::App::CMS::cms_post_delete.$type

MT::App::CMS::cms_post_save.$type

MT::App::CMS::cms_pre_save.$type

MT::App::CMS::cms_view_permission_filter.$type

MT::App::CMS::cms_save_permission_filter.$type

MT::App::CMS::cms_delete_permission_filter.$type

MT::App::CMS::cms_save_filter.$type

MT::App::CMS::cms_upload_file

MT::App::CMS::cms_upload_image

app_pre_listing_$app->mode

mail_filter

Comment Callbacks

CommentFilter

CommentThrottleFilter

Template Set Callbacks

DefaultTemplateFilter.$template_set_id

blog_template_set_change

Junk Handling Callbacks

handle_ham

handle_spam

New User Provisioning

Object Level Callbacks

Publishing

build_file

build_file_filter

build_page

pre_delete_archive_file

post_delete_archive_file

Task Callbacks

PeriodicTask

tasks

TrackBack Callbacks

TBPingFilter

TBPingThrottleFilter

Transformation Callbacks

Upgrade Callbacks

MT::Upgrade::SQL

XMLRPC/Atom Callbacks

api_pre_save.$obj_type

api_post_save.$obj_type

api_upload_file

api_upload_image

api_upload_file.$asset_class

Getting Started

Guides

Reference

Solutions