The Movable Type and Professional Network Wiki has been moved to wiki.movabletype.org.

MT::Plugin

[Login] Change #2 by Arvind Satyanarayan at 2006-08-28 13:20:36.

NAME

MT::Plugin - Movable Type class holding information that describes a plugin

SYNOPSIS

package MyPlugin;

use base 'MT::Plugin';
use vars qw($VERSION);
$VERSION = 1.12;

my $plugin = new MyPlugin({
    name => 'My Plugin',
    version => $VERSION,
    author_name => 'Conan the Barbaraian',
    author_link => 'http://example.com/',
    plugin_link => 'http://example.com/mt-plugins/example/',
    description => 'Frobnazticates all Diffyhorns',
    config_link => 'myplugin.cgi',
    settings => new MT::PluginSettings([
        ['option1', { Default => 'default_setting' }],
        ['option2', { Default => 'system_default', Scope => 'system' }],
        ['option2', { Scope => 'blog' }],
    ]),
    config_template => \&config_tmpl
});
MT->add_plugin($plugin);

# Alternatively, instantiating MT::Plugin itself

my $plugin = new MT::Plugin({
    name => "Example Plugin",
    version => 1.12,
    author_name => "Conan the Barbarian",
    author_link => "http://example.com/",
    plugin_link => "http://example.com/mt-plugins/example/",
    description => "Frobnazticates all Diffyhorns",
    config_link => 'myplugin.cgi',
    doc_link => <documentation URL>,
    settings => new MT::PluginSettings([
        ['option1', { Default => 'default_setting' }],
        ['option2', { Default => 'system_default', Scope => 'system' }],
        ['option2', { Scope => 'blog' }],
    ]),
    config_template => \&config_tmpl
});
MT->add_plugin($plugin);

DESCRIPTION

An MT::Plugin object holds data about a plugin which is used to help users understand what the plugin does and let them configure the plugin.

Normally, a plugin will construct an MT::Plugin object and pass it to the add_plugin method of the MT class:

MT->add_plugin($plugin);

This will help populate additional information about the plugin on the plugin listing in the MT system overview.

When adding callbacks, you will use the plugin object as well; this object is used to help the user identify errors that arise in executing the callback. For example, to add a callback which is executed before the MT::Foo object is saved to the database, you might make a call like this:

MT::Foo->add_callback("pre_save", 10, $plugin, \&callback_function);

This call will tell MT::Foo to call the function callback_function just before executing any save operation. The number '10' is signalling the priority, which controls the order in which various plugins are called. Lower number callbacks are called first.

ARGUMENTS

key

The key is an optional, but recommended element of the plugin. This value is used to uniquely identify the plugin and should never change from one version to the next. The key is used when available in storing plugin configuration data using the MT::PluginData package.
name (required)

A human-readable string identifying the plugin. This will be displayed in the plugin's slug on the MT front page.
version

The version number for the release of the plugin. Will be displayed next to the plugin's name wherever listed. This information is not required, but recommended.
schema_version

If your plugin declares a list of object classes, the schema_version is used to determine whether your classes require installation or upgrade. MT will store your plugin's schema_version in the MT::Config table for future reference.
description

A longer string giving a brief description of what the plugin does.
doc_link

A URL pointing to some documentation for the plugin. This can be a relative path, in which case it identifies documentation within the plugin's distribution, or it can be an absolute URL, pointing at off-site documentation.
config_link

The relative path of a CGI script or some other configuration interface for the plugin. This is relative to the "plugin envelope" — that is, the directory underneath mt/plugins where all your plugin files live.
author_name

The name of the individual or company that created the plugin.
author_link

A URL pointing to the home page of the individual or company that created the plugin.
plugin_link

A URL pointing to the home page for the plugin itself.
config_template

Defines a HTML::Template file by name to use for plugin configuration. This value may also be a code reference, which MT would call passing three arguments: the plugin object instance, a hashref of HTML::Template parameter data and the scope value (either "system" for system-wide configuration or "blog:N" where N is the active blog id).
system_config_template

Defines a HTML::Template file by name to use for system-wide plugin configuration. If not defined, MT will fall back to the config_template setting. This value may also be a code reference, which MT would call passing three arguments: the plugin object instance, a hashref of HTML::Template parameter data and the scope value (always "system" in this case).
blog_config_template

Defines a HTML::Template file by name to use for weblog-specific plugin configuration. If not defined, MT will fall back to the config_template setting. This value may also be a code reference, which MT would call passing three arguments: the plugin object instance, a hashref of HTML::Template parameter data and the scope value (for weblogs, this would be "blog:N", where N is the active blog id).
settings

Identifies the plugin's configuration settings.
app_methods

Used to register custom mode handlers for one or more application classes. This parameter accepts a hashref of package names mapping to a hashref of modes and their handlers. For example:
```
app_methods => {
    'MT::MyPackage' => {
        'mode1' => \&handler1,
        'mode2' => \&handler2
    }
}
```

app_action_links

Used to register plugin action links that are displayed on various pages within the MT::App::CMS application. The format for this key is:

app_action_links => {
    'MT::App::CMS' => {   # application the action applies to
        'type' => {
            link => 'myplugin.cgi',
            link_text => 'Configure MyPlugin'
        }
    }
}

This is an alternative to using MT->add_plugin_action.

app_itemset_actions

Used to register plugin itemset action links that are displayed on various listings within the MT::App::CMS application. The format for this key is:

app_action_links => {
    'MT::App::CMS' => {   # application the action applies to
        'type' => {
            key => 'unique_action_name',
            label => 'Uppercase text',
            code => \&itemset_handler
        }
    }
}

This is an alternative to using MT::App::CMS->add_itemset_action.

callbacks

Used to register object or application callbacks with the callback system. This can be used in lieu of MT->add_callback. Example:

callbacks => {
    'callback_name' => \&callback_handler,
    'another_callback' => {
        priority => 1,
        code => \&another_handler
    }
}

junk_filters

You can register one or more junk detection filters using this key. The format is:
```
junk_filters => {
    'MyJunkFilter' => \&junk_filter_handler
}
```
This is an alternative to using MT->register_junk_filter.
init_app

It's possible for a plugin to define code that is to be executed upon app initialization with this parameter. It may be a simple coderef which will be invoked for all MT::App instances:
```
init_app => \&init_app_routine
```
Or it can be a hashref that maps MT::App package names to a coderef.
```
init_app => {
    'MT::App::CMS' => \&init_cms_app_routine,
    'MT::App::Comments' => \&init_comments_app_routine,
}
```
init_request

A plugin can use this parameter to define a routine to execute upon the start of each HTTP request to an application. Like 'init_app', this parameter can either be a coderef or a hashref for app-specific routines.
template_tags

This parameter is used to declare custom tag handlers for Movable Type. It is similar in function to MT::Template::Context->add_tag. The parameter is given as a hashref, in this format:
```
template_tags => {
    'TagName' => \&tag_handler
}
```
You may register one or more template tags in this way.
container_tags

This parameter is used to declare custom container tags for Movable Type. It is similar in function to MT::Template::Context->add_container_tag. You may register one or more container tags in this way.
```
container_tags => {
    'ContainerTag' => \&container_tag_handler
}
```
conditional_tags

This parameter is used to declare custom conditional tags for Movable Type. This is similar in function to MT::Template::Context->add_conditional_tag. You may register one or more conditional tags in this way.
```
conditional_tags => {
    'IfCondition' => \&conditional_tag_handler
}
```
global_filters

This parameter is used to declare global tag attributes. It is similar in function to MT::Template::Context->add_global_filter. You may register 1 or more global filters in this way.
```
global_filters => {
    'attribute_name' => \&attribute_handler
}
```
text_filters

Text formatting filters can be declared with this parameter. It is similar in function to MT->add_text_filter. You may register 1 or more filters in this way.
```
text_filters => {
    'format_name' => { label => "My Text Format", code => \&formatter }
}
```
tasks

System tasks that are executed through the MT::TaskMgr can be registered with this parameter. The format for this parameter is as follows:
```
tasks => {
    'task_id' => \&task_code,
    'weekly_task' => {
        name => "My Weekly Task",
        frequency => 24 * 60 * 60 * 7,   # run every 7 days
        code => \&weekly_task_code
    }
}
```
The task identifier used for the key of each task registered should be globally unique. You should use some unique prefix or suffix that only your plugin will use.

Refer to MT::TaskMgr for more details on the MT task subsystem.
object_classes

Declaration of a list of MT::Object descendant classes that you want the MT upgrade process to maintain.
```
object_classes => [ 'MyPlugin::Foo', 'MyPlugin::Bar' ]
```
Define this in conjunction with a schema_version to have MT maintain the schema for your object packages.
upgrade_functions

This defines a list of custom upgrade operations that you may require MT to use to upgrade your schema from one version to another. For most upgrades (simple column additions or size changes), this is unnecessary, but if you require any kind of data manipulation or conversion, you will need to register an upgrade function to handle it. Please refer to the MT::Upgrade package for how to declare an upgrade function. Here is an example:
```
upgrade_functions => {
    'my_plugin_fix_field_a' => {
        version_limit => 1.1,   # runs for schema_version < 1.1
        code => \&plugin_field_a_fixer
    }
}
```

METHODS

Each of the above arguments to the constructor is also a 'getter' method that returns the corresponding value. MT::Plugin also offers the following methods:

$plugin->init_app

For subclassed MT::Plugins that declare this method, it is invoked when the application starts up.

$plugin->init_request

For subclassed MT::Plugins that declare this method, it is invoked when the application begins handling a new request.

$plugin->envelope

Returns the path to the plugin, relative to the MT directory. This is determined automatically when the plugin is loaded.

$plugin->set_config_value($key, $value[, $scope])

$plugin->get_config_value($key[, $scope])

These routines facilitate easy storage of simple configuration options. They make use of the PluginData table in the database to store a set of key-value pairs for each plugin. Call them as follows:

$plugin->set_config_value($key, $value);
$value = $plugin->get_config_value($key);

The name field of the plugin object is used as the namespace for the keys. Thus it would not be wise for one plugin to use the same name as a different plugin.

$plugin->get_config_obj([$scope])

Retrieves the MT::PluginData object associated with this plugin and the scope identified (which defaults to 'system' if unspecified).

$plugin->get_config_hash([$scope])

Retrieves the configuration data associated with this plugin and returns it a a Perl hash reference. If the scope parameter is not given, the 'system' scope is assumed.

$plugin->config_template($params[, $scope])

Called to retrieve a HTML::Template object which will be output as the configuration form for this plugin. Optionally a scope may be specified (defaults to 'system').

my $system_tmpl = $plugin->config_template($params, 'system');
my $system_tmpl = $plugin->config_template($params);
my $blog_tmpl = $plugin->config_template($params, 'blog:1');

$plugin->config_vars([$scope])

Returns an array of configuration setting names for the requested scope.

$plugin->save_config($param[, $scope])

Handles saving configuration data from the plugin configuration form.

my $param = { 'option1' => 'x' };
$plugin->save_config($param); # saves system configuration data
$plugin->save_config($param, 'system'); # saves system configuration data
$plugin->save_config($param, 'blog:1'); # saves blog configuration data

$plugin->load_config($param[, $scope])

Handles loading configuration data from the plugindata table.

$plugin->load_tmpl($file[, ...])

Used to load a HTML::Template object relative to the plugin's directory. It will scan both the plugin's directory and a directory named 'tmpl' underneath it. It will passthrough parameters that follow the $file parameter into the HTML::Template constructor.

MT::PluginSettings

The MT::PluginSettings package is also declared with this module. It is used to define a group of settings and their defaults for the plugin. These settings are processed whenever configuration data is requested from the plugin.

Example:

$plugin->settings = new MT::PluginSettings([
    ['option1', { Default => 'default_setting' }],
    ['option2', { Default => 'system_default', Scope => 'system' }],
    ['option2', { Scope => 'blog' }],
]);

Settings can be assigned a default value and an applicable 'scope'. Currently, recognized scopes are "system" and "blog".

AUTHOR & COPYRIGHTS

Please see the MT manpage for author, copyright, and license information.

[Login] Change #2 by Arvind Satyanarayan at 2006-08-28 13:20:36.