MT::Plugin - Movable Type class holding information that describes a
plugin
=head1 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);
=head1 DESCRIPTION
An I<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 I<MT::Plugin> object and pass it
to the C<add_plugin> method of the I<MT> class:
MT->add_plugin($plugin);
This will insert a slug for that plugin on the main MT page; the slug
gives the name and description and provides links to the documentation
and configuration pages, if any.
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 I<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 I<MT::Foo> to call the function
C<callback_function> just before executing any C<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.
=head1 ARGUMENTS
=over 4
=item * name
A human-readable string identifying the plugin. This will be displayed
in the plugin's slug on the MT front page.
=item * version (optional, but recommended)
The version number for the release of the plugin. Will be displayed
next to the plugin's name wherever listed.
=item * description (optional)
A longer string giving a brief description of what the plugin does.
=item * doc_link (optional)
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.
=item * config_link (optional)
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 C<mt/plugins> where all
your plugin files live.
=item * author_name (optional)
The name of the individual or company that created the plugin.
=item * author_link (optional)
A URL pointing to the home page of the individual or company that
created the plugin.
=item * plugin_link (optional)
A URL pointing to the home page for the plugin itself.
=item * config_template (optional)
=item * system_config_template (optional)
=item * blog_config_template (optional)
=item * settings (optional)
Identifies the plugin's configuration settings.
=head1 Methods
Each of the above arguments to the constructor is also a 'getter'
method that returns the corresponding value. C<MT::Plugin> also offers
the following methods:
=head2 $plugin->init_app
For subclassed MT::Plugins that declare this method, it is invoked when
the application starts up.
=head2 $plugin->init_request
For subclassed MT::Plugins that declare this method, it is invoked when
the application begins handling a new request.
=head2 $plugin->envelope
Returns the path to the plugin, relative to the MT directory. This is
determined automatically when the plugin is loaded.
=head2 $plugin->set_config_value($key, $value[, $scope])
=head2 $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 C<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 C<name> as a different plugin.
=head2 $plugin->get_config_obj([$scope])
Retrieves the MT::PluginData object associated with this plugin
and the scope identified (which defaults to 'system' if unspecified).
=head2 $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.
=head2 $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');
=head2 $plugin->config_vars([$scope])
Returns an array of configuration setting names for the requested scope.
=head2 $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
=head2 $plugin->load_config($param[, $scope])
Handles loading configuration data from the plugindata table.
=head2 $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.
=head1 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".
