Koha/REST/Plugin/Pagination.pm

   1 package Koha::REST::Plugin::Pagination;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it
   6 # under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Plugin';
  21
  22 =head1 NAME
  23
  24 Koha::REST::Plugin::Pagination
  25
  26 =head1 API
  27
  28 =head2 Mojolicious::Plugin methods
  29
  30 =head3 register
  31
  32 =cut
  33
  34 sub register {
  35     my ( $self, $app ) = @_;
  36
  37 =head2 Helper methods
  38
  39 =head3 add_pagination_headers
  40
  41     my $patrons = Koha::Patrons->search( ... );
  42     $c->add_pagination_headers({
  43         total  => $patrons->count,
  44         params => {
  45             _page     => ...
  46             _per_page => ...
  47             ...
  48         }
  49     });
  50
  51 Adds a Link header to the response message $c carries, following RFC5988, including
  52 the following relation types: 'prev', 'next', 'first' and 'last'.
  53 It also adds X-Total-Count containing the total results count, and X-Base-Total-Count containing the total of the non-filtered results count.
  54
  55 If page size is omitted, it defaults to the value of the RESTdefaultPageSize syspref.
  56
  57 =cut
  58
  59     $app->helper(
  60         'add_pagination_headers' => sub {
  61             my ( $c, $args ) = @_;
  62
  63             my $total    = $args->{total};
  64             my $base_total = $args->{base_total};
  65             my $req_page = $args->{params}->{_page} // 1;
  66             my $per_page = $args->{params}->{_per_page} //
  67                             C4::Context->preference('RESTdefaultPageSize') // 20;
  68
  69             my $pages;
  70             if ( $per_page == -1 ) {
  71                 $req_page = 1;
  72                 $pages    = 1;
  73             }
  74             else {
  75                 $pages = int $total / $per_page;
  76                 $pages++
  77                     if $total % $per_page > 0;
  78             }
  79
  80             my @links;
  81
  82             if ( $per_page != -1 and $pages > 1 and $req_page > 1 ) {    # Previous exists?
  83                 push @links,
  84                     _build_link(
  85                     $c,
  86                     {   page     => $req_page - 1,
  87                         per_page => $per_page,
  88                         rel      => 'prev',
  89                         params   => $args->{params}
  90                     }
  91                     );
  92             }
  93
  94             if ( $per_page != -1 and $pages > 1 and $req_page < $pages ) {    # Next exists?
  95                 push @links,
  96                     _build_link(
  97                     $c,
  98                     {   page     => $req_page + 1,
  99                         per_page => $per_page,
 100                         rel      => 'next',
 101                         params   => $args->{params}
 102                     }
 103                     );
 104             }
 105
 106             push @links,
 107                 _build_link( $c,
 108                 { page => 1, per_page => $per_page, rel => 'first', params => $args->{params} } );
 109             push @links,
 110                 _build_link( $c,
 111                 { page => $pages, per_page => $per_page, rel => 'last', params => $args->{params} } );
 112
 113             # Add Link header
 114             foreach my $link (@links) {
 115                 $c->res->headers->add( 'Link' => $link );
 116             }
 117
 118             # Add X-Total-Count header
 119             $c->res->headers->add( 'X-Total-Count' => $total );
 120             $c->res->headers->add( 'X-Base-Total-Count' => $base_total );
 121             return $c;
 122         }
 123     );
 124
 125 =head3 dbic_merge_pagination
 126
 127     $filter = $c->dbic_merge_pagination({
 128         filter => $filter,
 129         params => {
 130             page     => $params->{_page},
 131             per_page => $params->{_per_page}
 132         }
 133     });
 134
 135 Adds I<page> and I<rows> elements to the filter parameter.
 136
 137 =cut
 138
 139     $app->helper(
 140         'dbic_merge_pagination' => sub {
 141             my ( $c, $args ) = @_;
 142             my $filter = $args->{filter};
 143
 144             $filter->{page} = $args->{params}->{_page};
 145             $filter->{rows} = $args->{params}->{_per_page};
 146
 147             return $filter;
 148         }
 149     );
 150 }
 151
 152 =head2 Internal methods
 153
 154 =head3 _build_link
 155
 156     my $link = _build_link( $c, { page => 1, per_page => 5, rel => 'prev' });
 157
 158 Returns a string, suitable for using in Link headers following RFC5988.
 159
 160 =cut
 161
 162 sub _build_link {
 163     my ( $c, $args ) = @_;
 164
 165     my $params = $args->{params};
 166
 167     $params->{_page}     = $args->{page};
 168     $params->{_per_page} = $args->{per_page};
 169
 170     my $link = '<'
 171         . $c->req->url->clone->query(
 172             $params
 173         )->to_abs
 174         . '>; rel="'
 175         . $args->{rel} . '"';
 176
 177     # TODO: Find a better solution for this horrible (but needed) fix
 178     $link =~ s|api/v1/app\.pl/||;
 179
 180     return $link;
 181 }
 182
 183 1;