<<

NAME

MT - Movable Type

SYNOPSIS

    use MT;
    my $mt = MT->new;
    $mt->rebuild(BlogID => 1)
        or die $mt->errstr;

DESCRIPTION

The MT class is the main high-level rebuilding/pinging interface in the Movable Type library. It handles all rebuilding operations. It does not handle any of the application functionality--for that, look to MT::App and MT::App::CMS, both of which subclass MT to handle application requests.

PLUGIN APPLICATIONS

At any given time, the user of the Movable Type platform is interacting with either the core Movable Type application, or a plugin application (or "sub-application").

A plugin application is a plugin with a user interface that inherits functionality from Movable Type, and appears to the user as a component of Movable Type. A plugin application typically has its own templates displaying its own special features; but it inherits some templates from Movable Type, such as the navigation chrome and error pages.

The MT Root and the Application Root

To locate assets of the core Movable Type application and any plugin applications, the platform uses two directory paths, mt_dir and app_dir. These paths are returned by the MT class methods with the same names, and some other methods return derivatives of these paths.

Conceptually, mt_dir is the root of the Movable Type installation, and app_dir is the root of the "currently running application", which might be Movable Type or a plugin application. It is important to understand the distinction between these two values and what each is used for.

The mt_dir is the absolute path to the directory where MT itself is located. Most importantly, the MT configuration file and the CGI scripts that bootstrap an MT request are found here. This directory is also the default base path under which MT's core templates are found (but this can be overridden using the TemplatePath configuration setting).

Likewise, the app_dir is the directory where the "current" application's assets are rooted. The platform will search for application templates underneath the app_dir, but this search also searches underneath the mt_dir, allowing the application to make use of core headers, footers, error pages, and possibly other templates.

In order for this to be useful, the plugin's templates and code should all be located underneath the same directory. The relative path from the app_dir to the application's templates is configurable. For details on how to indicate the location of your plugin's templates, see MT::App.

Finding the Root Paths

When a plugin application initializes its own application class (a subclass of MT::App), the mt_dir should be discovered and passed constructor. This comes either from the Directory parameter or the Config parameter.

Since plugins are loaded from a descendent of the MT root directory, the plugin bootstrap code can discover the MT configuration file (and thus the MT root directory) by traversing the filesystem; the absolute path to that file can be passed as the Config parameter to MT::App::new. Working code to do this can be found in the examples/plugins/mirror/mt-mirror.cgi file.

The app_dir, on the other hand, always derives from the location of the currently-running program, so it typically does not need to be specified.

USAGE

MT has the following interface. On failure, all methods return undef and set the errstr for the object or class (depending on whether the method is an object or class method, respectively); look below at the section "ERROR HANDLING" for more information.

MT->new( %args )

Constructs a new MT instance and returns that object. Returns undef on failure.

new will also read your MT configuration file (provided that it can find it--if you find that it can't, take a look at the Config directive, below). It will also initialize the chosen object driver; the default is the DBM object driver.

%args can contain:

• Config

  Path to the MT configuration file.

  If you do not specify a path, MT will try to find your MT configuration file in the current working directory.

• Directory

  Path to the MT home directory.

  If you do not specify a path, MT will try to find the MT directory using the discovered path of the MT configuration file.

$mt->init

Initializes the Movable Type instance, including registration of basic resources and callbacks. This method also invokes the init_config and init_plugins methods.

MT->instance

MT and all it's subclasses are now singleton classes, meaning you can only have one instance per package. MT->instance() returns the active instance. MT->new() is now an alias to instance_of.

$class->instance_of

Returns the singleton instance of the MT subclass identified by $class.

$class->construct

Constructs a new instance of the MT subclass identified by $class.

MT->set_instance

Assigns the active MT instance object. This value is returned when MT->instance is invoked.

$mt->find_config($params)

Handles the discovery of the MT configuration file. The path and filename for the configuration file is returned as the result. The $params parameter is a reference to the hash of settings passed to the MT constructor.

$mt->init_config($params)

Reads the MT configuration settingss from the MT configuration file and settings from database (MT::Config).

The $params parameter is a reference to the hash of settings passed to the MT constructor.

$mt->init_plugins

Loads any discoverable plugins that are available. This is called from the init method, after the init_config method has loaded the configuration settings.

$mt->init_tasks

Registers the standard set of periodic tasks that Movable Type provides and then invokes the init_tasks method for each available plugin.

MT->add_task

An alias for MT::TaskMgr->add_task. Refer to the MT::TaskMgr documentation for more information.

MT->run_tasks

Initializes the tasks, running init_tasks and invokes the task system through MT::TaskMgr to run any registered tasks that are pending execution. See MT::TaskMgr for further documentation.

MT->unplug

Removes the global reference to the MT instance.

MT::log( $message ) or $mt->log( $message )

Adds an entry to the application's log table. Also writes message to STDERR which is typically routed to the web server's error log.

$mt->server_path, $mt->mt_dir

Both of these methods return the physical file path to the directory that is the home of the MT installation. This would be the value of the 'Directory' parameter given in the MT constructor, or would be determined based on the path of the configuration file.

$mt->app_dir

Returns the physical file path to the active application directory. This is determined by the directory of the active script.

$mt->config_dir

Returns the path to the MT configuration file.

$mt->config([$setting[, $value]])

This method is used to get and set configuration settings. When called without any parameters, it returns the active MT::ConfigMgr instance used by the application.

Specifying the $setting parameter will return the value for that setting. When passing the $value parameter, this will update the config object, assigning that value for the named $setting.

$mt->user_class

Returns the package name for the class used for user authentication. This is typically MT::Author.

$mt->request([$element[,$data]])

The request method provides a request-scoped storage object. It is an access interface for the MT::Request package. Calling without any parameters will return the MT::Request instance.

When called with the $element parameter, the data stored for that element is returned (or undef, if it didn't exist). When called with the $data parameter, it will store the data into the specified element in the request object.

All values placed in the request object are lost at the end of the request. If the running application is not a web-based application, the request object exists for the lifetime of the process and is released when the process ends.

See the MT::Request package for more information.

MT->new_ua

Returns a new LWP::UserAgent instance that is configured according to the Movable Type configuration settings (specifically HTTPInterface, HTTPTimeout, HTTPProxy and HTTPNoProxy). The agent string is set to "MovableType/(version)" and is also limited to receiving a response of 100,000 bytes by default (you can override this by using the 'max_size' method on the returned instance). Using this method is recommended for any HTTP requests issued by Movable Type since it uses the MT configuration settings to prepare the UserAgent object.

$mt->ping( %args )

Sends all configured XML-RPC pings as a way of notifying other community sites that your blog has been updated.

%args can contain:

• Blog

  An MT::Blog object corresponding to the blog for which you would like to send the pings.

  Either this or BlogID is required.

• BlogID

  The ID of the blog for which you would like to send the pings.

  Either this or Blog is required.

$mt->ping_and_save( %args )

Handles the task of issuing any pending ping operations for a given entry and then saving that entry back to the database.

The %args hash should contain an element named Entry that is a reference to a MT::Entry object.

$mt->needs_ping(%param)

Returns a list of URLs that have not been pinged for a given entry. Named parameters for this method are:

Entry

The MT::Entry object to examine.

Blog

The MT::Blog object that is the parent of the entry given.

The return value is an array reference of URLs that have not been pinged for the given entry.

An empty list is returned for entries that have a non 'RELEASE' status.

$mt->update_ping_list($blog)

Returns a list of URLs for ping services that have been configured to be notified when posting new entries.

$mt->set_language($tag)

Loads the localization plugin for the language specified by $tag, which should be a valid and supported language tag--see supported_languages to obtain a list of supported languages.

The language is set on a global level, and affects error messages and all text in the administration system.

This method can be called as either a class method or an object method; in other words,

    MT->set_language($tag)

will also work. However, the setting will still be global--it will not be specified to the $mt object.

The default setting--set when MT::new is called--is U.S. English. If a DefaultLanguage is set in the MT configuration file, the default is then set to that language.

MT->translate($str[, $param, ...])

Translates $str into the currently-set language (set by set_language), and returns the translated string. Any parameters following $str are passed through to the maketext method of the active localization module.

MT->translate_templatized($str)

Translates a string that has embedded <MT_TRANS> tags. These tags identify the portions of the string that require localization. Each tag is processed separately and passed through the MT->translate method. Examples (used in your application's HTML::Template templates):

    <p><MT_TRANS phrase="Hello, world"></p>

and

    <p><MT_TRANS phrase="Hello, [_1]" params="<TMPL_VAR NAME=NAME>"></p>

$mt->trans_error( $str[, $arg1, $arg2] )

Translates $str into the currently-set language (set by set_language), and assigns it as the active error for the MT instance. It returns undef, which is the usual return value upon generating an error in the application. So when an error occurs, the typical return result would be:

    if ($@) {
        return $app->trans_error("An error occurred: [_1]", $@);
    }

The optional $arg1 (and so forth) parameters are passed as parameters to any parameterized error message.

$mt->current_language

Returns the language tag for the currently-set language.

MT->supported_languages

Returns a reference to an associative array mapping language tags to their proper names. For example:

    use MT;
    my $langs = MT->supported_languages;
    print map { $_ . " => " . $langs->{$_} . "\n" } keys %$langs;

MT->language_handle

Returns the active MT::L10N language instance for the active language.

MT->add_plugin($plugin)

Adds the plugin described by $plugin to the list of plugins displayed on the welcome page. The argument should be an object of the MT::Plugin class.

MT->add_plugin_action($where, $action_link, $link_text)

An alias to the active MT::App instance add_plugin_action method. Please refer to the MT::App module for further documentation.

MT->add_itemset_action(\%options)

An alias to the active MT::App::CMS instance add_itemset_action method. Please refer to the MT::App::CMS module for further documentation.

MT->add_text_filter($key, \%options)

Adds a text filter with the short name $key and the options in \%options.

The text filter will be added to MT's list of text filtering options in the new/edit entry screen, and will be used for filtering all of the entry fields, if the user has enabled filtering for those fields in the template (for example, by default the entry body and extended text are both run through the filter, but the excerpt is not).

$key should be a lower-case identifier containing only alphanumerics and _ (that is, matching /\w+/). Since $key is stored as the filter name on a per-entry basis, it should not change. (In other words, don't call if foo in one version and foo_bar in the next, if the filter does the same thing in each version.)

The flip side of this, though, is that if your filter acts differently from one version to the next, you should change $key, and you should also change the filename of your plugin, so that the old implementation--which may be associated with all of the entries in the user's system--still works as usual. For example, if your foo plugin changes semantics drastically so that paragraph breaks are represented as two <br /> tags, rather than <p> tags, you should change the key of the new version to foo_2 (for example), and the filename to foo_2.pl.

%options can contain:

• label

  The short-but-descriptive label for the filter. This will be displayed in the Movable Type UI as the name of the text filter.

• on_format

  A reference to a subroutine that will be executed to filter a string of text. The subroutine will always receive one argument, the string of text to filter, and should return the filtered string. In some cases--for example, when called while building a template--the subroutine will receive a second argument, the MT::Template::Context object handling the build.

  See the example below.

• docs

  The URL (or filename) of a document containing documentation on your filter. This will be displayed in a popup window when the user selects your filter on the New/Edit Entry screen, then clicks the Help link ((?)).

  If the value is a full URL (starting with http://), the popup window will open with that URL; otherwise, it is treated as a filename, assumed to be in the user's docs folder.

Here's an example of adding a text filter for Wiki formatting, using the Text::WikiFormat CPAN module:

    MT->add_text_filter(wiki => {
        label => 'Wiki',
        on_format => sub {
            require Text::WikiFormat;
            Text::WikiFormat::format($_[0]);
        },
        docs => 'http://www.foo.com/mt/wiki.html',
    });

MT->all_text_filters

Returns a reference to a hash containing the registry of text filters.

MT->apply_text_filters($str, \@filters)

Applies the set of filters \@filters to the string $str and returns the result (the filtered string).

\@filters should be a reference to an array of filter keynames--these are the short names passed in as the first argument to add_text_filter. $str should be a scalar string to be filtered.

If one of the filters listed in \@filters is not found in the list of registered filters (that is, filters added through add_text_filter), it will be skipped silently. Filters are executed in the order in which they appear in \@filters.

As it turns out, the MT::Entry::text_filters method returns a reference to the list of text filters to be used for that entry. So, for example, to use this method to apply filters to the main entry text for an entry $entry, you would use

    my $out = MT->apply_text_filters($entry->text, $entry->text_filters);

MT->add_log_class($class)

Registers a new MT::Log subclass with MT, which is used for presenting specific types of log records in the activity log and activity feeds. See MT::Log for further documentation on custom log classes.

MT->add_callback($meth, $priority, $plugin, $code)

Registers a new callback handler for a particular registered callback.

The first parameter is the name of the callback method. The second parameter is a priority (a number in the range of 1-10) which will control the order that the handler is executed in relation to other handlers. If two handlers register with the same priority, they will be executed in the order that they registered. The third parameter is a MT::Plugin object reference that is associated with the handler (this parameter is optional). The fourth parameter is a code reference that is invoked to handle the callback. For example:

    MT->add_callback('BuildFile', 1, undef, \&rebuild_file_hdlr);

The code reference should expect to receive an object of type MT::Callback as its first argument. This object is used to communicate errors to the caller:

    sub rebuild_file_hdlr {
        my ($cb, ...) = @_;
        if (something bad happens) {
            return $cb->error("Something bad happened!");
        }
    }

Other parameters to the callback function depend on the callback point.

The treatment of the error string depends on the callback point. Typically, either it is ignored or the user's action fails and the error message is displayed.

The value returned from this method is the new MT::Callback object.

MT->remove_callback($callback)

Removes a callback that was previously registered.

MT->register_callbacks([...])

Registers several callbacks simultaneously. Each element in the array parameter given should be a hashref containing these elements: name, priority, plugin and code.

MT->run_callbacks($meth[, $arg1, $arg2, ...])

Invokes a particular callback, running any associated callback handlers.

The first parameter is the name of the callback to execute. This is one of the global callback methods (see Callbacks section) or can be a class-specific method that includes the package name associated with the callback.

The remaining arguments are passed through to any callback handlers that are invoked.

For "Filter"-type callbacks, this routine will return a 0 if any of the handlers return a false result. If all handlers return a true result, a value of 1 is returned.

Example:

    MT->run_callbacks('MyClass::frobnitzes', \@whirlygigs);

Which would execute any handlers that registered in this fashion:

    MT->add_callback('MyClass::frobnitzes', 4, $plugin, \&frobnitz_hdlr);

MT->register_junk_filter( $filter )

Registers a new MT::JunkFilter with Movable Type. Junk filters are used to identify spam for incoming feedback. Please see documentation for MT::JunkFilter for more information.

Example:

    require MT::JunkFilter;
    MT->register_junk_filter(new MT::JunkFilter({
        name => "My Junk Filter",
        code => sub { $plugin->my_junk_filter(@_) },
        plugin => $plugin,
    }));

MT->run_callback($cb[, $arg1, $arg2, ...])

An internal routine used by run_callbacks to invoke a single MT::Callback.

callback_error($str)

This routine is used internally by MT::Callback to set any error response that comes from invoking a callback.

callback_errstr

This internal routine returns the error response stored using the callback_error routine.

MT->product_code

The product code identifying the Movable Type product that is installed. This is either 'MTE' for Movable Type Enterprise or 'MT' for the non-Enterprise product.

MT->product_name

The name of the Movable Type product that is installed. This is either 'Movable Type Enterprise' or 'Movable Type Publishing Platform'.

MT->product_version

The version number of the product. This is different from the version_id and version_number methods as they report the API version information.

MT->version_id

Returns the API version of MT (including any beta/alpha designations).

MT->version_number

Returns the numeric API version of MT (without any beta/alpha designations). For example, if version_id returned 2.5b1, version_number would return 2.5.

MT->schema_version

Returns the version of the MT database schema.

MT->version_slug

Returns a string of text that is appended to emails sent through the build_email method.

$mt->publisher

Returns the MT::WeblogPublisher object that is used for managing the MT publishing process. See MT::WeblogPublisher for more information.

$mt->rebuild

An alias to MT::WeblogPublisher::rebuild. See MT::WeblogPublisher for documentation of this method.

$mt->rebuild_entry

An alias to MT::WeblogPublisher::rebuild_entry. See MT::WeblogPublisher for documentation of this method.

$mt->rebuild_indexes

An alias to MT::WeblogPublisher::rebuild_indexes. See MT::WeblogPublisher for documentation of this method.

$mt->build_email($file, $param)

Loads a template from the application's 'email' template directory and processes it as a HTML::Template. The $param argument is a hash reference of parameter data for the template. The return value is the output of the template.

MT::get_next_sched_post_for_user($author_id, @blog_ids)

This is an internal routine used by MT::XMLRPCServer and the getNextScheduled XMLRPC method to determine the timestamp for the next entry that is scheduled for publishing. The return value is the timestamp in UTC time in the format "YYYY-MM-DDTHH:MM:SSZ".

ERROR HANDLING

On an error, all of the above methods return undef, and the error message can be obtained by calling the method errstr on the class or the object (depending on whether the method called was a class method or an instance method).

For example, called on a class name:

    my $mt = MT->new or die MT->errstr;

Or, called on an object:

    $mt->rebuild(BlogID => $blog_id)
        or die $mt->errstr;

DEBUGGING

MT has a package variable $MT::DebugMode which is assigned through your MT configuration file (DebugMode setting). If this is set to any non-zero value, MT applications will display any warn'd statements to a panel that is displayed within the app.

The DebugMode is a bit-wise setting and offers the following options:

    1 - Display debug messages
    2 - Display a stack trace for messages captured
    4 - Lists queries issued by Data::ObjectDriver
    8 - Reports on MT templates that take more than 1/4 second to build*
    128 - Outputs app-level request/response information to STDERR.

These can be combined, so if you want to display queries and debug messages, use a DebugMode of 5 for instance.

You may also use the local statement to temporarily apply a particular bit, if you want to scope the debug messages you receive to a block of code:

    local $MT::DebugMode |= 4;  # show me the queries for the following
    my $obj = MT::Entry->load({....});

*DebugMode bit 8 actually outputs it's messages to STDERR (which typically is sent to your web server's error log).

CALLBACKS

Movable Type has a variety of hook points at which a plugin can attach a callback.

In each case, the first parameter is an MT::Callback object which can be used to pass error information back to the caller.

The app-level callbacks related to rebuilding are documented in MT::WeblogPublisher. The specific apps document the callbacks which they invoke.

NewUserProvisioning($cb, $user)

This callback is invoked when a user is being added to Movable Type. Movable Type itself registers for this callback (with a priority of 5) to provision the user with a new weblog if the system has been configured to do so.

LICENSE

The license that applies is the one you agreed to when downloading Movable Type.

AUTHOR & COPYRIGHT

Except where otherwise noted, MT is Copyright 2001-2007 Six Apart. All rights reserved.

<<