NAME

Krang::HTMLPager - Web-paginate lists of records


SYNOPSIS

    # In your Krang::CGI::* module...
    use Krang::ClassLoader 'HTMLPager';
    # In a run-mode, instantiate new pager object...
    my $pager = pkg('HTMLPager')->new(
        cgi_query  => $query,
        use_module => pkg('Contrib'),
        columns    => ['last', 'first', 'command_column', 'checkbox_column'],
        columns_sortable        => ['last', 'first'],
        command_column_commands => ['edit_contrib'],
        id_handler              => sub      { return $_[0]->contrib_id },
        row_handler => sub { $_[0]->{last} = $_[1]->last(); $_[0]->{first} = $_[1]->first(); },
    );
    # Run the pager
    my $pager_html = $pager->output();
    $template->param(pager_html => $pager_html);
    # In your HTML::Template file...
    <!-- pkg('HTMLPager') Output START -->
    <tmpl_var pager_html>
    <!-- pkg('HTMLPager') Output END -->


DESCRIPTION

The primary purpose of Krang::HTMLPager is to allow Krang-style page able lists of results to be easily created. The secondary purpose is to enforce a standard function and appearance to these lists.

The pager interface is designed to work specifically with the Krang system, and to be as simple to use as possible. It is modeled after HTML::Pager, but is more specialized for use with Krang. In particular Krang::HTMLPager provides the following functions which are unique to Krang:


INTERFACE

Krang::HTMLPager implements the following primary methods:

Krang::HTMLPager Properties

Krang::HTMLPager expects a number of parameters to be set via the new() method. These parameters set properties which are used to create a specification for your pager, such as the list of columns and which of those columns are sortable.

Following is a list of the parameters for Krang::HTMLPager. These parameters are also accessible via object methods.

Creating Custom Pager Templates

It is expected that most of the time you will use the output() method to run the pager and return a rendered block of HTML with your interface. The HTML which is returned is generated internally within Krang::HTMLPager.

In some cases, this internally-created HTML will not suffice. You may have to implement a screen which has a slightly different style to it. You may have additional functionality which is not compatible with that provided by the stock Krang::HTMLPager output. In these cases you may want to create your own custom Krang::HTMLPager template to replace the internal one.

This is not a task for the faint of heart. Your template must be structured to be fully compatible with the internal template in terms of HTML::Template structures. The easiest way to get started with a custom template is to have Krang::HTMLPager dynamically generate a template for you, which you can then customize. This can be done via the make_internal_template() method:

    my $pager    = pkg('HTMLPager')->new(%pager_props);
    my $template = $pager->make_internal_template();

Refer to make_internal_template() in this document for more details.

The template which is created contains all the variables necessary in a custom template, for the pager specification (%pager_props) you have provided. Following is a summary of the variables you will find.