Implementing a Listing Mode Handler

Ok, we are almost done. The last thing that needs to be implemented is the handler that will pull information from the database, and populate your template with the data that will be displayed. The code sample below shows you how to build the simple data structures that will later be used by the $app->listing() subroutine that ultimately outputs all the HTML for you table.

All of these data structures are then passed into the $app->listing subroutine at the very end of the mode handler. This subroutine conveniently interfaces with the database for you. Therefore, you just need to provide $app->listing with the object you are displaying, the terms and arguments it will use when constructing its query to the database, and any other input parameters needed for the template you created above. Movable Type does the rest.

Let’s take a look at a listing mode handler. The code sample below has been augmented with inline comments to instruct you on what each code fragment is responsible for.

package DemoPlugin::Plugin;
use strict;
use MT::Util qw(relative_date);

sub listing_table {
    my $app = shift;
    my %param = @_;

    # This anonymous subroutine will process each row of data returned
    # by the database and map that data into a set of columns that will
    # be displayed in the table itself. The method takes as input:
    #   * the object associated with the current row
    #   * an empty hash for the row that should be populated with content
    #     from the $obj passed to it.
    my $code = sub {
        my ($obj, $row) = @_;
        $row->{'column1'} = $obj->id;
        $row->{'column2'} = $obj->title;
        my $ts = $row->{created_on};
        $row->{date} = relative_date($ts, time);
    };

    # %terms is used in case you want to filter the query that will fetch
    # the items from the database that correspond to the rows of the table
    # being rendered to the screen
    my %terms = (
        author_id => $app->user->id,
    );

    # %args is used in case you want to sort or otherwise modify the 
    # query arguments of the table, e.g. the sort order or direction of
    # the query associated with the data being displayed in the table.
    my %args = (
        sort => 'created_on',
        direction => 'descend',
    );

    # %params is an addition hash of input parameters into the template
    # and can be used to hold an arbitrary set of name/value pairs that
    # can be displayed in your template.
    my %params = (
        some_variable => 'You can do ANYTHING in Movable Type',
    );

    # Fetch an instance of the current plugin using the plugin's key.
    # This is done as a convenience only.
    my $plugin = MT->component('DemoPlugin');

    # This is the main work horse of your handler. This subrotine will
    # actually conduct the query to the database for you, populate all
    # that is necessary for the pagination controls and more. The 
    # query is filtered and controlled using the %terms and %args 
    # parameters, with 'type' corresponding to the database table you
    # will query.
    $app->listing({
        type     => 'entry', # the ID of the object in the registry
        terms    => \%terms,
        args     => \%args,
        listing_screen => 1,
        code     => $code,
        template => $plugin->load_tmpl('my_table.tmpl'),
        params   => \%params,
    });
}