From 5902e8a4f5bfd3b056dc326c32f5a9d728b59c3d Mon Sep 17 00:00:00 2001
From: Domizio Demichelis
Date: Sat, 16 Jun 2018 20:24:55 +0200
Subject: [PATCH] passed instance variables are not deleted from the vars hash
---
docs/api/pagy.md | 35 +++++++++++++++-----------
lib/pagy.rb | 6 ++---
lib/pagy/extras/initializer_example.rb | 4 +--
3 files changed, 25 insertions(+), 20 deletions(-)
diff --git a/docs/api/pagy.md b/docs/api/pagy.md
index 270f0f112..bccb9cb2d 100644
--- a/docs/api/pagy.md
+++ b/docs/api/pagy.md
@@ -51,19 +51,26 @@ Pagy::VARS[:my_option] = 'my option'
This method returns the `pathname` of the `pagy/lib` root dir. It is useful to get the absolute path of template, locale and javascript files installed with the gem.
-### Pagy.new
+### Pagy.new(vars)
_Notice_: If you use the `Pagy::Backend` its `pagy` method will instantiate and return the Pagy object for you.
-The `Pagy.new` method accepts a single hash of variables that will be merged with the `Pagy::Vars` hash and will be used to create the object. The only mandatory variable is the `:count` of the collection to paginate: all the other variables are optional and have sensible defaults. Of course you will also have to pass the `page` or you will always get the default page number 1.
+The `Pagy.new` method accepts a single hash of variables that will be merged with the `Pagy::Vars` hash and will be used to create the object.
-All the variables not explicitly in the list of core-variables (the non-core variables) passed/merged to the new method will be kept in the object, passed around with it and accessible through the `pagy.vars` hash.
+### Variables
-**Notice**: Pagy replaces the blank values of the passed variables with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
+All the variables passed to the new method will be merged with the `Pagy::VARS` hash and will be kept in the object, passed around with it and accessible through the `pagy.vars` hash.
-### Core Variables
+They can be set globally by using the `Pagy::VARS` hash or passed to the `Pagy.new` method and are accessible through the `vars` reader.
-These are the core-variables (i.e. instance variables that define the pagination object itself) consumed by the `new` method. They are all integers:
+**Notice**: Pagy replaces the blank values of the passed variables with their default values coming from the `Pagy::VARS` hash. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
+
+### Instance Variables
+
+A few variables are particularly important for the calculation of the pagination, and therefore are validated and used to initialize a few instance variables.
+
+The only mandatory instance variable to be passed is the `:count` of the collection to paginate: all the other variables are optional and have sensible defaults. Of course you will also have to pass the `page` or you will always get the default page number 1.
+They are all integers:
| Variable | Description | Default |
| --------- | ---------------------------------------------------------------------------------------------- | ------- |
@@ -72,20 +79,18 @@ These are the core-variables (i.e. instance variables that define the pagination
| `:items` | the _requested_ number of items for the page | `20` |
| `:outset` | the initial offset of the collection to paginate: pass it only if the collection had an offset | `0` |
-### Non-core Variables
-
-These are the non-core variables: as for the core-variables they can be set globally by using the `Pagy::VARS` hash or passed to the `Pagy.new` method, but they don't become instance variables. Instead they are items of the `@vars` instance variable hash and are accessible through the `vars` reader.
+### Other Variables
| Variable | Description | Default |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. (see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |
| `:page_param` | the name of the page param name used in the url. (see [Customizing the page param](../how-to.md#customizing-the-page-param) | `:page` |
| `:params` | the arbitrary param hash to add to the url. (see [Customizing the params](../how-to.md#customizing-the-params) | `{}` |
-| `:anchor` | the arbitrary anchor string (including the "#") to add to the url. (see [Customizing the page param](../how-to.md#customizing-the-params) | `""` |
-| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links | `""` |
-| `:item_path` | the dictionary path used by the `pagy_info` method to lookup the item/model name | `""` |
+| `:anchor` | the arbitrary anchor string (including the "#") to add to the url. (see [Customizing the page param](../how-to.md#customizing-the-params) | `""` |
+| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links | `""` |
+| `:item_path` | the dictionary path used by the `pagy_info` method to lookup the item/model name | `""` |
-There is no specific default nor validation for non-core variables.
+There is no specific validation for non-instance variables.
### Attribute Readers
@@ -93,7 +98,7 @@ Pagy exposes all the instance variables needed for the pagination through a few
| Reader | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------ |
-| `count` | the untouched `:count` variable |
+| `count` | the collection `:count` |
| `page` | the current page number |
| `items` | the _actual_ number of items in the current page (can be less than the requested `:items` variable) |
| `pages` | the number of total pages in the collection (same as `last` but with cardinal meaning) |
@@ -103,7 +108,7 @@ Pagy exposes all the instance variables needed for the pagination through a few
| `to` | the collection-position of the last item in the page (`:outset` excluded) |
| `prev` | the previous page number or `nil` if there is no previous page |
| `next` | the next page number or `nil` if there is no next page |
-| `vars` | the non-core variables hash |
+| `vars` | the variables hash |
### series(...)
diff --git a/lib/pagy.rb b/lib/pagy.rb
index a30d6de97..7b14c5568 100644
--- a/lib/pagy.rb
+++ b/lib/pagy.rb
@@ -16,9 +16,9 @@ def self.root; Pathname.new(__FILE__).dirname end
# Merge and validate the options, do some simple aritmetic and set the instance variables
def initialize(vars)
- @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == ''.freeze }) # default vars + cleaned instance vars
- { count:0, items:1, outset:0, page:1 }.each do |k,min| # validate core variables
- (@vars[k] && instance_variable_set(:"@#{k}", @vars.delete(k).to_i) >= min) \
+ @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == ''.freeze }) # default vars + cleaned vars
+ { count:0, items:1, outset:0, page:1 }.each do |k,min| # validate instance variables
+ (@vars[k] && instance_variable_set(:"@#{k}", @vars[k].to_i) >= min) \
or raise(ArgumentError, "expected :#{k} >= #{min}; got #{instance_variable_get(:"@#{k}").inspect}")
end
@pages = @last = [(@count.to_f / @items).ceil, 1].max # cardinal and ordinal meanings
diff --git a/lib/pagy/extras/initializer_example.rb b/lib/pagy/extras/initializer_example.rb
index 3b91a1f4c..a801bc4ae 100644
--- a/lib/pagy/extras/initializer_example.rb
+++ b/lib/pagy/extras/initializer_example.rb
@@ -32,10 +32,10 @@
# All the Pagy::VARS here are set for all the Pagy instances but can be
# overridden by just passing them to Pagy.new or the #pagy controller method
-# Core variables (See https://ddnexus.github.io/pagy/api/pagy#core-variables)
+# Instance variables (See https://ddnexus.github.io/pagy/api/pagy#instance-variables)
# Pagy::VARS[:items] = 20 # default
-# Non Core Variables (See https://ddnexus.github.io/pagy/api/pagy#non-core-variables)
+# Other Variables (See https://ddnexus.github.io/pagy/api/pagy#other-variables)
# Pagy::VARS[:size] = [1,4,4,1] # default
# Pagy::VARS[:page_param] = :page # default
# Pagy::VARS[:params] = {} # default