NAME
    Catalyst::TraitFor::Controller::DBIC::DoesPaging - Helps you paginate,
    search, sort, and more easily using DBIx::Class

VERSION
    version 1.001003

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 = $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 = $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 $self           = shift;
        my $dispatch_table = shift;
        my $q              = shift;

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

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

        return $self->search(\%search, \%meta);
     }

     # 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 = $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 = shift;
        my $dispatch_table = shift;
        my $default = shift;
        my $q = shift;

        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 );
           %search = ( %search, %{$tmp_search||{}} );
           %meta   = ( %meta,   %{$tmp_meta||{}} );
        } elsif ( $sort && $direction ) {
           my ( $tmp_search, $tmp_meta ) = $default->( $sort, $direction );
           %search = ( %search, %{$tmp_search||{}} );
           %meta   = ( %meta,   %{$tmp_meta||{}} );
        }

        return $self->search(\%search, \%meta);
     }

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

AUTHOR
    Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Arthur Axel "fREW" Schmidt.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

