This extra allows your app to automatically change the number of items per page depending on the page number. Instead of generating all the pages with a fixed number of items, the app can serve pages with an increasing number of items in order to speed things up for wild-browsing and improving the user experience.
You can set this up by simply setting the
:gearbox_items variable to an array of integers. For example, you would set the
[10, 20, 40, 80] to have page
10 items, page
40 and all the other pages with
The content of the array is not restricted neither in length nor in direction: you can pass any arbitrary sequence of integer you like, although it makes more sense to have an increasing progression of items.
Even after requiring this extra, the regular fixed pagination is still supported: you have just to temporarily disable
gearbox_extra: false in the instances that need the fixed pagination.
You can also use it in presence of the items extra if you follow a simple logic. The
gearbox extra automatically handles the items per page, while the
items extra allows the user to explicitly request a specific number of items. That’s why the
items extra takes priority over the
gearbox extra if both are enabled.
If you want to use the
gearbox in some instances, you can temporarily set
items_extra: false and the
gearbox will be used instead. That is a common scenario when you use the
items extra in an API controller, while you want to use the
gearbox in an infinite scroll pagination in another controller.
See extras for general usage info.
# pagy.rb initializer require 'pagy/extras/gearbox' # optional: set a different default in the pagy.rb initializer # Pagy::DEFAULT[:gearbox_extra] = false # will make it opt-in only # Pagy::DEFAULT[:gearbox_items] = [15, 30, 60, 100] # default Pagy::DEFAULT[:gearbox_items] = [10, 20, 50] # your own default # controller action # or pass the :gearbox_items variable to a constructor to have it only for that instance @pagy, @records = pagy(Product.all, gearbox_items: [30, 60, 100], ...) # You can still use instances with fixed pagination even after requiring the extra # use the default Pagy::DEFAULT[:items] @pagy, @records = pagy(Product.all, gearbox_extra: false) # use the passed items: 30 @pagy, @records = pagy(Product.all, gearbox_extra: false, items: 30) # If you use also the items extra it must be disabled in the instance that use the gearbox # use the default Pagy::DEFAULT[:gearbox_items] @pagy, @records = pagy(Product.all, items_extra: false) # use the passed gearbox_items: [30, 60, 100] @pagy, @records = pagy(Product.all, items_extra: false, gearbox_items: [30, 60, 100])
||enable or disable the feature||
||array of positive integers||
gearbox extra overrides the
setup_items_var and the
setup_pages_vars methods in the
Pagy class. You don’t have to use them directly.
The idea behind this extra comes from the Geared Pagination.
The main differences are:
ActiveRecordso it works in any environment