SYNOPSIS

    package MyApp::Controller::Foo;
    use Moose;
    BEGIN { extends 'Catalyst::Controller' }
    with 'Catalyst::TraitFor::Controller::DBIC::DoesPaging';

    sub people {
       my ($self, $c) = @_;
       my $people = $self->page_and_sort(
          $self->search( $self->model('DB::People') )
       );
       # ...
    }

DESCRIPTION

   This module helps you to map various DBIx::Class features to CGI
   parameters. For the most part that means it will help you search, sort,
   and paginate with a minimum of effort and thought.

METHODS

   All methods take the context and a ResultSet as their arguments. All
   methods return a ResultSet.

page_and_sort

    my $result_rs  = $self->page_and_sort($c, $c->model('DB::Foo'));

   This is a helper method that will first "sort" your data and then
   "paginate" it.

paginate

    my $result_rs  = $self->paginate($c, $c->model('DB::Foo'));

   Paginates the passed in resultset based on the following CGI
   parameters:

    start - first row to display
    limit - amount of rows per page

search

    my $searched_rs = $self->search($c, $c->model('DB::Foo'));

   If the $resultset has a controller_search method it will call that
   method on the passed in resultset with all of the CGI parameters. I
   like to have this method look something like the following:

    # Base search dispatcher, defined in MyApp::Schema::ResultSet
    sub _build_search {
       my ($rs, $dispatch_table, $q) = @_;

       foreach ( keys %{$q} ) {
          if ( my $fn = $dispatch_table->{$_} and $q->{$_} ) {
             my ( $search, $meta ) = $fn->( $q->{$_} );
             $rs = $rs->search($search, $meta);
          }
       }

       return $rs;
    }

    # search method in specific resultset
    sub controller_search {
       my $self   = shift;
       my $params = shift;
       return $self->_build_search({
          status => sub {
             return { 'repair_order_status' => shift }, {};
          },
          part_id => sub {
             return {
                'lineitems.part_id' => { -like => q{%}.shift( @_ ).q{%} }
             }, { join => 'lineitems' };
          },
       },$params);
    }

   If the controller_search method does not exist, this method will call
   "simple_search" instead.

sort

    my $result_rs  = $self->sort($c, $c->model('DB::Foo'));

   Exactly the same as search, except calls controller_sort or
   "simple_sort". Here is how I use it:

    # Base sort dispatcher, defined in MyApp::Schema::ResultSet
    sub _build_sort {
       my ($self, $dispatch_table, $default, $q) = @_;

       my %search = ();
       my %meta   = ();

       my $direction = $q->{dir};
       my $sort      = $q->{sort};

       if ( my $fn = $dispatch_table->{$sort} ) {
          my ( $tmp_search, $tmp_meta ) = $fn->( $direction );
          $self = $self->search( $tmp_search, $tmp_meta );
       } elsif ( $sort && $direction ) {
          my ( $tmp_search, $tmp_meta ) = $default->( $sort, $direction );
          $self = $self->search( $tmp_search, $tmp_meta );
       }

       return $self;
    }

    # sort method in specific resultset
    sub controller_sort {
       my $self = shift;
       my $params = shift;
       return $self->_build_sort({
          first_name => sub {
             my $direction = shift;
             return {}, {
                order_by => { "-$direction" => [qw{last_name first_name}] },
             };
          },
       }, sub {
          my $param = shift;
          my $direction = shift;
          return {}, {
             order_by => { "-$direction" => $param },
          };
       },$params);
    }

simple_deletion

    my $deleted_ids = $self->simple_deletion($c, $c->model('DB::Foo'));

   Deletes from the passed in resultset based on the following CGI
   parameter:

    to_delete - values of the ids of items to delete

   This is the only method that does not return a ResultSet. Instead it
   returns an arrayref of the id's that it deleted. If the ResultSet has
   has a multipk this will expect each tuple of PK's to be separated by
   commas.

   Note that this method uses the $rs->delete method, as opposed to
   $rs->delete_all

simple_search

    my $searched_rs = $self->simple_search($c, $c->model('DB::Foo'));

   Searches the resultset based on all fields in the request, except for
   fields listed in ignored_params. Searches with $fieldname => { -like =>
   "%$value%" }. If there are multiple values for a CGI parameter it will
   use all values via an or.

simple_sort

    my $sorted_rs = $self->simple_sort($c, $c->model('DB::Foo'));

   Sorts the passed in resultset based on the following CGI parameters:

    sort - field to sort by, defaults to primarky key
    dir  - direction to sort

CONFIG VARIABLES

   page_size

     Default size of a page. Defaults to 25.

   ignored_params

     ArrayRef of params that will be ignored in simple_search, defaults
     to:

      [qw{limit start sort dir _dc rm xaction}]

SEE ALSO

   Web::Util::DBIC::Paging, which this module is a thin wrapper around

CREDITS

   Thanks to Micro Technology Services, Inc. for funding the initial
   development of this module.