The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CatalystX-Widget-Paginator-0.07
River stage zero No dependents
++
/ CatalystX::Widget::Paginator

NAME

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

VERSION

Version 0.07

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 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.

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.

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( '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' );

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    ...    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.

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.