view release on metacpan or  search on metacpan

lib/CatalystX/Widget/Paginator.pm  view on Meta::CPAN

2. Checks for already paginated resultset (see L<DBIx::Class::ResultSet>
C<rows> and C<page> attributes for details). If specified - uses them.

3. Uses the default value for C<rows> (10).

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

5. Uses the default value for C<page> (1).

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

Created instance of a widget can be queried about its attributes.
For example: C<last>, C<pages>, C<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 C<style> and
C<style_prefix> attributes.


=head1 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 L<DBIx::Class::ResultSet> instance:

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


With paginated L<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' );

=head1 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 C<style> value. Cells HTML
class attribute consists from C<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.

=cut


# constructor
sub BUILD {
	my ( $self,$args ) = @_;