Applications

BigPAPI is obsolete in Movable Type 3.3 and up! The features it provides are now part of MT itself. When you upgrade to MT 3.3x, you'll need to remove or disable BigPAPI, and upgrade any installed plugins that rely on it.

Movable Type provides a powerful API that allows developers to extend its functionality. Plugins can add tags to MT's templating system, or create full-fledged applications that interact with the MT database.

One missing piece of the API, however, has been the ability for plugins to modify MT's own interface—the screens you see when using Movable Type to manage your content.

BigPAPI is intended to fill this gap. It provides hooks so that other plugins can access and alter any page of the MT interface before it's displayed to the user. In effect, it enlarges the Plugin API—hence the name BigPAPI.

Unless you're a developer, that's probably all you need to know. The best way to get an idea of the kinds of things BigPAPI enables plugins to do is to install one or more of the plugins that have already been developed.

Requirements

BigPAPI works with Movable Type 3.16 and higher. (It may work with earlier versions, but has not been tested.) However, specific BigPAPI-based plugins may have their own MT version requirements.

Installation

To install the BigPAPI plugin, upload the file BigPAPI.pl to the plugins directory within your Movable Type directory.

Once the plugin is installed, when you run Movable Type, you'll notice... nothing. (Except that it'll appear in the list of installed plugins.) By itself, BigPAPI doesn't affect the MT interface. But once it's installed, it will enable other plugins, like those listed below, to do so.

Terms of Use

BigPAPI is available free of charge under a Creative Commons license.

If you develop a Movable Type plugin that relies on the functionality added by BigPAPI, you're encouraged to include BigPAPI.pl in your own plugin distribution, so your users won't have to download files from multiple sources.

Support

Please use the support forums for all support requests, bug reports, feature requests, questions, and comments regarding this plugin.

Special Thanks

To Six Apart's Brad Choate for coding help and feature suggestions, and to Arvind Satyanarayan for early testing.

Available BigPAPI-Based Plugins

If you've written or know of a plugin not listed here, let me know and I'll add it to the list. Please note that I can't vouch for or support, and have not necessarily used or tested, any of the plugins by other authors.

alogblog MT Interface by Joon Lee: A set of replacement templates that uses BigPAPI to implement switchable styles.
BigTemplateWindow by Joon Lee: "For a really big template editing window."
Ajaxify by Arvind Satyanarayan: "A series of plugins that add various javascript and AJAX widgets into the Movable Type interface."
Better Entry Preview by Dan Wolfgang: "Lets you retool the entry preview screen to your heart's delight."
Better File Uploader by Dan Wolfgang: "Allows you to create default settings for file uploads."
Granular Interface Styling by Su: "Adds extra classes to the MT interface to allow for more detailed customization."
LinkEntryToFile: Adds fields to the Edit Entry screen that let you enter the name of a file to be kept in sync with the text of the Entry Body or Extended Entry (like the "Link this template to a file" feature for MT templates).
MainMenuRecent: On the main Movable Type menu, lists the three most recent entries as part of the area for each weblog.
MTMaps by Patrick Calahan: "Makes it easy to create Google Maps from your Movable Type blog entries."
Show System ID by Su: "Integrates display of blog, entry and category ID numbers directly within the MT interface."
Smilies by Dan Wolfgang: "With a click, you can add any of [13] emoticons to your entryÕs body and extended entry fields."
UpdateAuthoredOn: Adds an "Update" button to the "Authored On" field on the Edit Entry screen, which sets the timestamp to the current date and time.
WeblogsActionMenu: Adds a menu of actions next to the menu of weblogs in the Movable Type header, so you can jump directly to somewhere other than the menu in a different weblog.

Developing Plugins With BigPAPI

Most MT users can stop reading here, and start trying out the plugins listed above. If you're a developer interested in creating your own plugins to enhance or modify the Movable Type interface, read on.

How It Works

The BigPAPI plugin doesn't actually do all that much. It simply overrides a couple of subroutines in the MT::App module that are called whenever a page of the MT CMS is about to be displayed. Before going ahead and building the page, it runs some callbacks. So your plugin simply needs to install appropriately named callbacks for a particular CMS page (or all pages), and you'll have the opportunity to tinker with the contents of the page before it's displayed to the user.

There are two types of callbacks you can add: template callbacks, which let you operate on the unbuilt text of the CMS page template, and param callbacks, which let you control the data that will be placed onto the template when it's built.

The code to add a callback is fairly simple, and looks something like this:

require MT::Plugin;
require MT;
my $plugin = MT::Plugin->new({
	name => "MyAuthorWidget",
	description => 'Adds a nifty little widget to the Authors listing screen.',
	version => '1.0'
});
MT->add_plugin($plugin);

MT->add_callback('bigpapi::template::list_author', 9, $plugin, \&_template);

The details of how the callbacks should be named are covered below. For now, just note that you pass add_callback() a callback name, a priority, an MT::Plugin object, and a a reference to the subroutine that will handle the callback.

HTML::Template

The Movable Type CMS uses the Perl module HTML::Template as the basis for its templating system. (Note that this has nothing whatsoever to do with the "Templates" defined within an MT weblog and used to generate pages on your site. If this distinction is unclear to you, you may be in somewhat over your head, here.) That's why the .tmpl files within the /tmpl/cms directory contain a lot of tags that look like <TMPL_WHATEVER>.

To use BigPAPI to implement functionality beyond simple HTML tweaks, your plugin's callbacks are going to have to know how to interact with HTML::Template. Your template callbacks may be inserting <TMPL...> tags into the template, and your param callbacks will set parameters in the format prescribed by HTML::Template. So if you're not already familiar with this module, you might want to peruse the documentation before going any further.

Template Callbacks

The name of a template callback should be in the form

bigpapi::template::tmpl_name

where tmpl_name is the name of the template file that resides in /tmpl/cms, minus .tmpl.

Whenever MT is about to build tmpl_name.tmpl, your callback subroutine will be called with three parameters:

a callback object, which can be used to return an error;
the application object containing data about the MT application that's being run;
a reference to the unbuilt text of the template.

A template callback subroutine will look something like this:

sub _template {
	my ($cb, $app, $template) = @_;
	...
}

What does your plugin do during those three dots? It takes the text represented by $$template (note the dereferencing of the variable) and—carefully—does whatever it wants with it. This will probably involve searching for some text and replacing it with some other text using a regular expression.

The callback doesn't need to return anything; any changes made to $$template will show up on the built template.

Included Templates

MT's CMS templates use the HTML::Template tag TMPL_INCLUDE to call in other templates (header, footer, and other elements that are used on more than one page). When you define a BigPAPI template callback for a specific template, it will actually be called once with the text of the main template, and once with the text of any other template that's TMPL_INCLUDEd into that the main template. (Unfortunately, there's no way for the callback to know whether it's being passed an included template, or which one.)

If you want a particular callback to apply only to a template itself and not to any included templates, you can add ::top to the callback name:

MT->add_callback('bigpapi::template::tmpl_name::top', 9, $plugin, \&_template);

Param Callbacks

The name of a param callback should be in the form

bigpapi::param::tmpl_name

where tmpl_name is the name of the template that resides in /tmpl/cms, minus .tmpl.

Whenever MT is about to build tmpl_name.tmpl, your callback subroutine will be called with three parameters:

a callback object, which can be used to return an error;
the application object containing data about the MT application that's being run;
a reference to a hash containing all the data that's going to be sent to HTML::Template to place onto the page.

A param callback subroutine will look something like this:

sub _param {
	my ($cb, $app, $param) = @_;
	...
}

Within this subroutine, you can add values to $param or modify what's already in there. The callback doesn't need to return anything; any changes made to $param will show up on the built template.

To get any parameters you add to show up on the built page, you'll need to use a template callback to insert the appropriate HTML::Template tags. Refer to the HTML::Template documentation, or look at lib/MT/App/CMS.pm for examples, to see how to create loops, nested loops, and conditional statements.

Keep in mind that MT has already loaded up the template with a lot of parameters, and other plugins might want to put their own parameters in there as well. If you try to add parameters like category_loop or blog_id, there's going to be trouble. To avoid conflicts, use a distinctive prefix for all the parameters for a given plugin: mywidget_category_loop, mywidget_blog_id.

Global and Version-Specific Callbacks

If you want your plugin to apply to all CMS pages, simply define callbacks with no template name specified:

MT->add_callback('bigpapi::template', 9, $plugin, \&_template);
MT->add_callback('bigpapi::param', 9, $plugin, \&_param);

Since the CMS templates may change with each new version of MT, your plugin may need to behave differently or search for different text depending on the version of MT in use. BigPAPI provides for this by calling not only the template-specific and global callbacks described above, but version-specific callbacks with different levels of specificity. For example, if you're running MT 3.17, when the template edit_entry.tmpl is about to be built, BigPAPI will call the following template callbacks:

bigpapi::template::edit_entry
bigpapi::template::edit_entry::3.17
bigpapi::template::edit_entry::3.17x
bigpapi::template::edit_entry::3.1x
bigpapi::template::edit_entry::3.x
bigpapi::template::edit_entry::top::3.17
bigpapi::template::edit_entry::top::3.17x
bigpapi::template::edit_entry::top::3.1x
bigpapi::template::edit_entry::top::3.x
bigpapi::template
bigpapi::template::3.17
bigpapi::template::3.17x
bigpapi::template::3.1x
bigpapi::template::3.x

This means your plugin can define actions that will only apply to a single, specific version of MT (3.17), or to a set of versions (3.1x). This will probably prove most useful for template callbacks, but it applies to param callbacks as well.

Version History

9/9/05 - version 1.04

Fixed missing filename in error message if a template file cannot be found

8/22/05 - version 1.03

Made several changes to load_tmpl() code based on latest betas of MT 3.2
Fixed warning from uninitialized filepath when running with DebugMode on (Aziz Ashofte)

8/2/05 - version 1.02

Fixed problem when a plugin CGI app tries to load a template with a relatively specified filename/path (Arvind)

8/1/05 - version 1.01

Fixed path problem under MT 3.2b2 when default mt-static directory is used (Jasmeet Singh)

7/21/05 - version 1.0 released