CatalystX::Widget::Paginator - HTML widget for digg-style paginated DBIx::ResulSet
Version 0.07
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 Catalyst::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. Checks for constructor arguments: page, rows. If specified, uses them.
page
rows
2. Checks for already paginated resultset (see DBIx::Class::ResultSet rows and page attributes for details). 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.
page_auto
page_arg
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.
invalid
Created instance of a widget can be queried about its attributes. For example: last, pages, objects, etc.
last
pages
objects
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.
style
style_prefix
Typical usage pattern in the controller:
sub index :Path :Args(0) { my ( $self,$c ) = @_; my $pg = $c->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 (overall 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( 'Paginator', rs => $c->model('Schema::User'), rows => 3, page => 15 );
With paginated DBIx::Class::ResultSet instance:
my $pg = $c->widget( 'Paginator', rs => $c->model('Schema::User')->search_rs( undef, { rows => 3, page => 15 ) );
Handling invalid page:
use Try::Tiny; my $pg = try { $c->widget( 'Paginator', rs => 'Schema::User', invalid => 'raise' ) } except { $c->detach('/error404') if /PAGE_OUT_OF_RANGE/; die $_; };
The same effect:
my $pg = $c->widget( 'Paginator', rs => 'Schema::User', invalid => sub { $c->detach('/error404' ) };
Subclassing in your application:
package YourApp::Widget::SimplePager; use Moose; extends 'CatalystX::Widget::Paginator'; has '+edges' => ( is => 'ro', default => undef ); has '+invalid' => ( is => 'ro', default => 'last' ); has '+page_arg' => ( is => 'ro', default => 'page' ); has '+prefix' => ( is => 'ro', default => undef ); has '+side' => ( is => 'ro', default => 0 ); has '+suffix' => ( is => 'ro', default => undef ); __PACKAGE__->meta->make_immutable; 1;
Usage subclassed widget in the controller:
$c->widget( '~SimplePager', rs => 'Schema::User' );
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 ... 7 >8< 9 ... 40 41 >> Total:x ----------------------------------------------------------------------
Table has HTML class attribute with a style value. Cells HTML class attribute consists from style_prefix and block name, where the names of the blocks the same as in example above. Current page framed with HTML span tag, others with links.
DBIx::Class::ResultSet name or instance
Delimeter string or undef (default: '...'). See "RENDERING" for details.
undef
Two element array of strings for left and right edges respectively or undef (default: ['<<','>>']). See "RENDERING" for details.
Determines the constructor behavior in the case of an invalid page. Could be arbitrary code block or one of predefined words:
Force set page to first (default).
first
Force set page to last.
Raise exception PAGE_OUT_OF_RANGE.
PAGE_OUT_OF_RANGE
Code reference for build link. Receives page number as argument and returns target URI.
Size of 'main' pages group (default: 10). See "RENDERING" for details.
Current page number.
Name of query string parameter for page number extracting (default: 'p').
Try or not to extract page_arg from Catalyst::Request automatically (default: 1).
First cell content (default: 'Pages'). See "RENDERING" for details.
Number of objects per page (default: 10).
Size of 'side' pages groups (default: 2). See "RENDERING" for details.
CSS class name for table tag (default: 'pages'). See "RENDERING" for details.
CSS class name prefix for table cells (default: 'p_'). See "RENDERING" for details.
Last cell content (default: 'Total: x'). See "RENDERING" for details.
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.
First page number.
Last page number.
Paged DBIx::Class::ResulSet instance.
Total number of pages.
Total objects count (overall pages).
Formatting linked page item.
Overriden Catalyst::Plugin::Widget render method.
render
Oleg A. Mamontov, <oleg at mamontov.net>
<oleg at mamontov.net>
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.
bug-catalystx-widget-paginator at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc CatalystX::Widget::Paginator
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=CatalystX-Widget-Paginator
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/CatalystX-Widget-Paginator
CPAN Ratings
http://cpanratings.perl.org/d/CatalystX-Widget-Paginator
Search CPAN
http://search.cpan.org/dist/CatalystX-Widget-Paginator/
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.
To install CatalystX::Widget::Paginator, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CatalystX::Widget::Paginator
CPAN shell
perl -MCPAN -e shell install CatalystX::Widget::Paginator
For more information on module installation, please visit the detailed CPAN module installation guide.