module Folio
Mix into any class implementing the following two methods:
build_page
: Responsible for instantiating a Folio::Page
and configuring its ordinal_pages?, first_page, and last_page attributes; those values being common to any page returned from the folio.
fill_page
: Receives a Folio::Page
with the ordinal_pages?, first_page, last_page, current_page, per_page, and total_entries attributes configured, and populates the page with the corresponding items from the folio. Also sets appropriate values for the next_page and previous_page attributes on the page. If the value provided in the page’s current_page cannot be interpreted as addressing a page in the folio, raises Folio::InvalidPage
.
In return, ‘Folio` provides a the paginate method and per_page attributes described below.
Raised when a value passed to a Folio’s paginate method is non-sensical or out of bounds for that folio.
Mix in to a source to provide the same methods as Folio
, but with simpler build_page and fill_page methods required on the host (some responsibility is moved into the paginate method). build_page also has a default implementation.
* build_page no longer needs to configure ordinal_page?, first_page, or last_page on the instantiated page. Instead, just instantiate and return a Folio::Ordinal::Page. If not provided, the default implementation just returns a Folio::Ordinal::BasicPage. * fill_page no longer needs to configure next_page and previous_page; the ordinal page will handle them. (Note that if necessary, you can still set next_page explicitly to nil.) Also, paginate will now perform ordinal bounds checking for you, so you can focus entirely on populating the page.
Mix in to an Enumerable
to provide the same methods as Folio::Page
but with the following overrides:
* ordinal_pages is always true * first_page is always 1 * current_page is forced to an integer * previous_page is always either current_page-1 or nil, depending on how current_page relates to first_page. * next_page can only be set if total_pages is unknown. if total_pages is known, next_page will be either current_page+1 or nil, depending on how current_page relates to last_page. if total_pages is unknown and next_page is unset (vs. explicitly set to nil), it will default to current_page+1. if next_page is set to a non-nil value, that value will be forced to an integer. * last_page is deterministic: always total_pages if total_pages is known, current_page if total_pages is unknown and next_page is nil, nil otherwise (indicating the page sequence continues until next_page is nil).
Mix into any Enumerable
. The mixin gives you the eight attributes and one method described below.
ordinal_pages?, first_page, and last_page are common to all pages created by a folio and are configured, as available, when the folio creates a blank page.
current_page, per_page, and total_entries control the filling of a page and are configured from parameters to the folio’s paginate method.
next_page and previous_page are configured, as available, when the folio fills the configured page.
Constants
- VERSION
Public Instance Methods
# File lib/folio.rb, line 47 def configure_pagination(page, options) current_page = options.fetch(:page) { nil } current_page = page.first_page if current_page.nil? page.current_page = current_page page.per_page = options.fetch(:per_page) { self.per_page } page.total_entries = options.fetch(:total_entries) { self.respond_to?(:count) ? self.count : nil } page end
# File lib/folio.rb, line 56 def default_per_page self.class.per_page end
Returns a page worth of items from the folio in a Folio::Page
. accepts the following parameters:
page
: a page identifier addressing which page of the folio to return. if not present, the first page will be returned. will raise Folio::InvalidPage
if the provided value cannot be used to address a page.
per_page
: number of items to attempt to include in the page. if not present, defaults to the folio’s per_page value. should only include fewer items if the end of the folio is reached.
total_entries
: pre-calculated value for the total number of items in the folio. may be nil, indicating the returned page should have total_entries nil.
if the folio implements a count method and the total_entries parameter is not supplied, the page’s total_entries will be set from the count method.
# File lib/folio.rb, line 40 def paginate(options={}) page = self.build_page page = self.configure_pagination(page, options) page = self.fill_page(page) page end