Step 2. Implement a Mode Handler

Once you have have registered a mode in your config.yaml you will need to implement the handler it refers to.

Now there is a bit of a chicken and egg problem because in order for you to truly test that your handler is working you also need a template to render and display. So chances are you are going to bounce a lot between editing your handler and messing with your template until you get everything just right.

Let’s start however with the handler which ultimately is responsible for loading the template, populating its context with parameter input and data, and then returning its HTML. The HTML and/or text returned by your handler will be displayed directly to the user’s browser.

package Example::Plugin;
use strict;

# A convenience method for returning an instance of your plugin.
# The value passed to MT->component should be the directory name
# that contains your plugin's config.yaml file.
sub plugin {
    return MT->component('Example');
}

# Your mode handler
sub some_mode {
    my $app = shift;
    my $plugin = plugin();
    my $tmpl = $plugin->load_tmpl('some_template.tmpl');
    return $app->build_page( $tmpl );
}
1;

Your mode handler should return whatever HTML you want to be displayed in the user’s browser. The $app->build_page() method is made available to facilitate the process of parsing and displaying your template’s HTML to the user. If there is an error in processing your template, Movable Type will handle displaying an error to your user automatically for you.

Error Handling

Even though Movable Type will handle most error reporting for you automatically, some of those error messages can seem cryptic and indecipherable. Therefore, you may wish to check for specific error conditions yourself, and display more meaningful and useful error messages in the event that one of those error conditions exist. To do that, return the value returned by the $app->error() method, as in the example below:

sub some_mode {
    my $app = shift;
    if (<error condition>) {
        return $app->error("An really bad error just occurred. Help!");
    }
    # do your thing
}

Obtaining an instance of your plugin

To retrieve an instance of your plugin (an MT::Plugin instance technically) use the static method: MT->component. To that function you pass the name of your plugin. Now, the name of your plugin in this instance refers to the directory in which your plugin’s config.yaml can be found. For example, suppose your plugin’s config.yaml is in the following location:

/path/to/mt/plugins/MyCrazyPlugin/config.yaml

Then you would call MT->component like so:

my $plugin = MT->component('MyCrazyPlugin');