/ 
CatalystX-Widget-Paginator-0.01
/ CatalystX::Widget::Paginator

NAME

CatalystX::Widget::Paginator - HTML widget for digg-style paginated DBIx::ResulSet

VERSION

Version 0.01

DESCRIPTION

This widget intended to solve the general problem with paginated results. Assume that we have a set of objects (DBIx::Class::ResultSet) and (probably) the request parameter indicates the current page. Created widget receives resultset and additional arguments, validates pagination and can be queried about pagination and objects presented for current page.

For the correct determination of the current page widget makes taking the following steps:

1. Check for already paginated resultset (see DBIx::Class::ResultSet rows and page for details). If specified - uses them.

2. Checks with the same name constructor arguments: page, rows. If specified, uses them.

3. Uses the default value for rows (10).

4. If attribute page_auto is enabled (default), try to get request parameter named page_arg for page value.

5. Uses the default value for page (1).

After successful identification page and rows attributes, the widget checks their validity for a specified resultset. Processing logic for non-valid attributes defined by invalid attribute.

Created instance of a widget can be queried about its attributes. For example: last, pages, objects, etc.

Widget is converted to a string represetning the HTML table with page numbers as links in the cells. Design details can be configured with style and style_prefix attributes.

SYNOPSIS

Typical usage pattern in the controller:

sub index :Path :Args(0) {
    my ( $self,$c ) = @_;

    my $pg = $c->widget( '+CatalystX::Widget::Paginator', rs => 'Schema::User' );

    my $current = $pg->page;     # current page no
    my $first   = $pg->first;    # first page no ( 1 )
    my $last    = $pg->last;     # last page no
    my $pages   = $pg->total;    # total pages ( $last - $first + 1 )
    my $total   = $pg->total;    # total objects (for all pages)
    my $objects = $pg->objects;  # objects for current page

    $c->res->body( "$pg" );      # render to nice HTML table
}

With DBIx::Class::ResultSet instance:

my $pg = $c->widget( '+CatalystX::Widget::Paginator',
    rs   => 'Schema::User',
    rows => 3, page => 15
);

With paginated DBIx::Class::ResultSet instance:

my $pg = $c->widget( '+CatalystX::Widget::Paginator',
    rs => $c->model('Schema::User')->search( undef, { rows => 3, page => 15 )
);

Handling invalid page:

  use Try::Tiny;

  my $pg = try {
      $c->widget( '+CatalystX::Widget::Paginator',
          rs      => 'Schema::User',
          invalid => 'raise'
      )
  } except {
      $c->detach('/error404') if /PAGE_OUT_OF_RANGE/;
	  die $_;
  };

The same effect:

my $pg = $c->widget( '+CatalystX::Widget::Paginator',
    rs      => 'Schema::User',
    invalid => sub { $c->detach('/error404' )
};

RENDERING

Widget renders (string representated) as HTML table with single row and multiple columns:

prefix  edge  side  delim     main      delim  side  edge  suffix
------------------------------------------------------------------
Pages:   <<   1  2   ...   20 21 22 23   ...   40 41  >>   Total:x

Table has style

CONSTRUCTOR

new( rs => $name|$instance, %options )

rs:

DBIx::Class::ResultSet name or instance

options:

delim

Delimeter string or undef (default: '...'). See RENDERING for details.

edges

Two element array of strings for left and right edges respectively or undef (default: ['<<','>>']). See RENDERING for details.

invalid

Determines the constructor behavior in the case of an invalid page. Could be arbitrary code block or one of predefined words:

first

Force set page to first (default).

last

Force set page to last.

raise

Raise exception PAGE_OUT_OF_RANGE.

Code reference for build link. Receives page number as argument and returns target URI.

main

Size of 'main' pages group (default: 10). See RENDERING for details.

page

Current page number.

page_arg

Name of query string parameter for page number extracting (default: 'p').

page_auto

Try or not to extract page_arg from Catalyst::Request automatically (default: 1).

prefix

First cell content (default: 'Pages'). See RENDERING for details.

rows

Number of objects per page (default: 10).

side

Size of 'side' pages groups (default: 2). See RENDERING for details.

style

CSS class name for table tag (default: 'pages'). See RENDERING for details.

style_prefix

CSS class name prefix for table cells (default: 'p_'). See RENDERING for details.

suffix

Last cell content (default: 'Total: x'). See RENDERING for details.

text

Code reference for page number formatting. Receives page number as argument and returns string. Also can be just a sprintf format string (default: '%s'). See RENDERING for details.

ATTRIBUTES

first

First page number.

last

Last page number.

objects

Paged DBIx::Class::ResulSet instance.

pages

Total number of pages.

total

Total objects count (overall pages).

METHODS

format

Formatting linked page item.

render

Overriden Catalyst::Plugin::Widget render method.

AUTHOR

Oleg A. Mamontov, <oleg at mamontov.net>

BUGS

Please report any bugs or feature requests to bug-catalystx-widget-paginator at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CatalystX-Widget-Paginator. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc CatalystX::Widget::Paginator

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Oleg A. Mamontov.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.