Module: Warped::Controllers::Pageable

Extended by:
ActiveSupport::Concern
Included in:
Ui, Tabulatable
Defined in:
lib/warped/controllers/pageable.rb,
lib/warped/controllers/pageable/ui.rb

Overview

Provides functionality for paginating records from an ActiveRecord::Relation in a controller.

Example usage:

class UsersController < ApplicationController
include Pageable

def index
  scope = paginate(User.all)
  render json: scope, root: :users, meta: pagination
end
end

Example requests:

GET /users?page=1&per_page=10
GET /users?page=2&per_page=50

The per_page parameter is optional. If not provided, the default value will be used.

The default value can be set at a controller level using the default_per_page class attribute. Example:

class UsersController < ApplicationController
include Pageable

self.default_per_page = 50

def index
  scope = paginate(User.all)
  render json: scope, root: :users, meta: pagination
end
end

Or by overriding the default_per_page controller instance method. Example:

class UsersController < ApplicationController
include Pageable

def index
  scope = paginate(User.all)
  render json: scope, root: :users, meta: pagination
end

private

def default_per_page
  50
end
end

The per_page value can also be set at action level, by passing the per_page parameter to the paginate method. Example:

class UsersController < ApplicationController
include Pageable

def index
  scope = paginate(User.all, per_page: 50)
  render json: scope, root: :users, meta: pagination
end

def other_index
  # The default per_page value is used.
  scope = paginate(User.all)
  render json: scope, root: :users, meta: pagination
end
end

The pagination metadata can be accessed by calling the pagination method. It includes the following keys:

  • total_count: The total number of records in the collection.
  • total_pages: The total number of pages.
  • next_page: The next page number.
  • prev_page: The previous page number.
  • page: The current page number.
  • per_page: The number of records per page. Warning: The pagination method will raise an ArgumentError if the method paginate was not called within the action.

Defined Under Namespace

Modules: Ui

Instance Method Summary collapse

Instance Method Details

#page ⇒ String?

Retrieves the page number from the request parameters.

Returns:

  • (String, nil) —

    The page number if present, otherwise nil.



106
107
108
 
# File 'lib/warped/controllers/pageable.rb', line 106

def page
  params[:page]&.to_i || 1
end

#paginate(scope, page: self.page, per_page: self.per_page) ⇒ ActiveRecord::Relation

Paginates the given scope.

Parameters:

  • scope (ActiveRecord::Relation) —

    The scope to be paginated.

  • page (String, Integer, nil) (defaults to: self.page) —

    The page number.

  • per_page (String, Integer, nil) (defaults to: self.per_page) —

    The number of records per page.

Returns:

  • (ActiveRecord::Relation) —

    The paginated scope.



98
99
100
101
 
# File 'lib/warped/controllers/pageable.rb', line 98

def paginate(scope, page: self.page, per_page: self.per_page)
  @pagination, paginated_scope = Queries::Paginate.call(scope, page:, per_page:)
  paginated_scope
end

#pagination ⇒ Hash

Retrieves pagination metadata.

Returns:

  • (Hash) —

    Metadata about the pagination.

Raises:

  • (ArgumentError) —

    If pagination was not performed.

See Also:

  • Queries::Paginate#metadata


123
124
125
126
127
 
# File 'lib/warped/controllers/pageable.rb', line 123

def pagination
  return @pagination if @pagination.present?

  raise ActionController::BadRequest, "Pagination was not performed"
end

#per_page ⇒ String, Integer

Retrieves the number of records per page from the request parameters or defaults to the controller's default value.

Returns:

  • (String, Integer) —

    The number of records per page.



114
115
116
 
# File 'lib/warped/controllers/pageable.rb', line 114

def per_page
  params[:per_page].presence || default_per_page
end