NAME

MT::Plugin - Movable Type class 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 MT::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 MT::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 MT::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 MT::Template parameter data and the scope value (always "system" in this case).
blog_config_template
Defines a MT::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 MT::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_itemset_actions => {
        'MT::App::CMS' => {   # application the action applies to
            $type => {
                key => 'unique_action_name',
                label => 'Uppercase text',
                code => \&itemset_handler
            }
        }
    }

Where $type should be an MT item such as 'entry', 'asset', 'ping', etc.

Please see the full documentation of these type options in the MT::App::CMS add_itemset_action section.

In the event that you need to register multiple actions for a single type, you can use the alternate format:

    app_itemset_actions => {
        'MT::App::CMS' => [   # application the action applies to
            {   type => 'type',
                key => 'unique_action_name',
                label => 'Uppercase text',
                code => \&itemset_handler_upper
            },
            {   type => 'type',
                key => 'unique_action_name2',
                label => 'Lowercase text',
                code => \&itemset_handler_lower
            }
        ]
    }

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
        }
    }
```
icon
Set the icon filename (not including the plugin's static web path).

log_classes

Set the name of the plugin's log classes to use. For example:

  MT->add_plugin({
    name => "My custom plugin",
    log_classes => { customlog => "MyCustomLog" }
  });

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:

MT::Plugin->new

Return a new MT::Plugin instance. This method calls the init method.

$plugin->init

This construction helper method registers plugin callbacks, junk_filters, text_filters, log_classes, template_tags, conditional_tags, global_filters.

$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->init_tasks

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

$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])

See the get_config_value description below.

$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->apply_default_settings($data[, $scope])

Applies the default plugin settings to the given data.

$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 MT::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])

This method returns the configuration data associated with a plugin (and an optional scope) in the given param hash reference.

$plugin->reset_config($scope)

This method drops the configuration data associated with this plugin given the scope identified and reverts to th MT defaults.

Handles loading configuration data from the plugindata table.

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

Used to load a MT::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 MT::Template constructor.

MT::Plugin->select([$class])

Return the list of plugins available for the calling class or of the given class name argument.

$plugin->needs_upgrade()

This method compares any previously stored schema version for the plugin to the current plugin schema version number to determine if an upgrade is in order.

$plugin->translate($phrase [, @args])

This method translate the $phrase to the currently selected language using the localization module for the plugin. The @args parameters are passed through if given.

$plugin->translate_templatized($text)

This method calls the plugin's translate method on any <MT_TRANS> tags inside $text.

$plugin->l10n_filter($text)

This method is an alias for the translate_templatized method.

$plugin->l10n_class()

This method returns the l10n_class attribute of the plugin or MT::L10N if not defined.

$plugin->register_importer()

This method gives plugins access to registry of importers. Detailed information can be found in MT::Import document.

Additional Accessor Methods

The following are plugin attributes with accompanying get/set methods.

key
name
author_name
author_link
plugin_link
version
schema_version
config_link
doc_link
description
envelope
settings
icon
callbacks
upgrade_functions
object_classes
junk_filters
text_filters
template_tags
conditional_tags
log_classes
container_tags
global_filters
app_methods
app_action_links
app_itemset_actions
tasks

LOCALIZATION

Proper localization of a plugin requires a bit of structure and discipline. First of all, your plugin should declare a 'l10n_class' element upon registration. This defines the base L10N package to use for any translation done by the plugin:

    # file l10nplugin.pl, in MT_DIR/plugins/l10nplugin

    my $plugin = new MT::Plugin({
        name => "My Localized Plugin",
        l10n_class => "l10nplugin::L10N",
    });

Then, you should have a file like this in MT_DIR/plugins/l10nplugin/lib/l10nplugin:

    # file L10N.pm, in MT_DIR/plugins/l10nplugin/lib/l10nplugin

    package l10nplugin::L10N;
    use base 'MT::Plugin::L10N';
    1;

And then your actual localization modules in MT_DIR/plugins/l10nplugin/lib/l10nplugin/L10N:

    # file en_us.pm, in MT_DIR/plugins/l10nplugin/lib/l10nplugin/L10N

    package l10n::L10N::en_us;

    use base 'l10nplugin::L10N';

    1;

Here's a French module, to localize the plugin name:

    # file fr.pm, in MT_DIR/plugins/l10nplugin/lib/l10nplugin/L10N

    package l10nplugin::L10N::fr;

    use base 'l10nplugin::L10N::en_us';

    our %Lexicon = (
        "My Localized Plugin" => "Mon Plugin Localise",
    );

    1;

And, the following methods of the plugin object are automatically translated for you, so you don't need to invoke translate on them yourself:

name
author_name
description

To translate individual strings of text from within your plugin code is done like this:

    my $rebuild_str = $plugin->translate("Publish");

Note that if your plugin does not translate a phrase, it may be translated by the MT translation matrix if the phrase is found there. So common MT phrases like "Weblog", "User", etc., are already handled and you should not have to duplicate the translation of such terms in your plugin's localization modules.

To translate a template that has embedded <MT_TRANS> tags in them, use the translate_templatized method of the plugin object.

    $tmpl = $plugin->load_tmpl("my_template.tmpl");
    $tmpl->param(\%param);
    my $html = $plugin->translate_templatized($tmpl->output());

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

Movable Type 4 Beta

Search This Blog

Browse Site by Category

Subscribe to MT4 News

movabletype.org

Get Help

Get Updates