foliate 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e632e2cdf928b30535057da735d185e35d5bb80
-  data.tar.gz: dcaed853a25f108a2838ad7c686a9e389e55cdb2
+  metadata.gz: 1379d91804fb3050affdd4a02ff646f2365715ac
+  data.tar.gz: ce950722db7f2aca60ee3cfa3bdd51fc738d6538
 SHA512:
-  metadata.gz: b34de5919e49576e9a4c27b84488d179a2a021e618dcbbec69707121023a12fb2ca69eb9a2d0e3058687602bbe2dcde50ffe4b5a058239fe2d2efe006f4ff32a
-  data.tar.gz: 3b8719a28e535fd8ba94b0ec5bcf78a43451d01ba34172c87389bf05217100aceb042e21888a57232dffec8732c40aa483620427fb95adcb64656128527c708d
+  metadata.gz: f7aab7c69bd58aeafcb664fb318e358c41e1fa7df0705cc5c402d8f1b53bc0114998ea4555b2439143d1d9f0635ba1371a8dee1b8afcd0ade86c785b2be2e7e3
+  data.tar.gz: efbb16cee1e2ec271223ddd8395f9ebbdae7e92e7b51e6fafb6b20321ea793c9dfd14781d31fec07f74be929f8cb57f658b0a1b6993547cdcc88bf17dc591e75

data/README.md

@@ -6,8 +6,8 @@ Pagination for Ruby on Rails.
 to a cleaner and much simpler implementation.
 
 **How is it different?**  Instead of extending ActiveRecord, or
-dynamically defining methods on objects after instantiating them,
-*foliate* adds a single method to ActionController:
+defining singleton methods on result sets at runtime, *foliate* adds a
+single method to ActionController:
 
 ```ruby
 ## app/controllers/posts_controller.rb
@@ -37,41 +37,52 @@ Do something with @posts here...
 <%= render @pagination %>
 ```
 
-**How does that look?**  By default, something like this:
+**What does it look like?**  By default, something like this:
 
 <img src="screenshots/page_input.png" alt="page input pagination">
 
 
-## More Information
+## Appearance
 
-**How do I customize the appearance of the pagination?**  Running the
-*foliate* installation generator creates
+The *foliate* installation generator creates
 "app/views/pagination/_pagination.html.erb" and
 "app/assets/stylesheets/pagination.css" in your project directory.
-These files can be edited to meet your needs.
+These files can be freely edited to suit your needs.
 
-**How many records are in each page?**  By default, *foliate* allots
-`Foliate.config.default_per_page` records per page, which is set in
-"config/initializers/foliate.rb".  However, this can be overridden by
-passing `per_page:` to `paginate`:
+## Records per page
+
+By default, *foliate* allots `Foliate.config.default_per_page` records
+per page, which can be configured in "config/initializers/foliate.rb".
+However, this can also be overridden on a per-Controller basis using the
+`per_page:` argument:
 
 ```ruby
 @posts = paginate(Post, per_page: 50)
 ```
 
-**What if I have a very large table, and don't want to incur a count of
-all records for each page?**  The `paginate` method accepts a
-`total_records:` argument, which will prevent a SQL count when set:
+## Page param name
+
+*foliate* uses the `:page` query param (i.e. `params[:page]`) to dictate
+the current page.  This can be configured by setting
+`Foliate.config.page_param` in "config/initializers/foliate.rb".  Doing
+so will properly affect both the `paginate` method and the `Pagination`
+object.
+
+## Avoiding SQL count on very large tables
+
+To determine the total number of pages, *foliate* performs a SQL count
+query.  On very large tables, count queries can have a noticeable
+performance cost.  If you have a more performant method of estimating
+total record count, you can prevent the count query by specifying the
+`total_records:` argument:
 
 ```ruby
 @posts = paginate(Post, total_records: Post.cached_count)
 ```
 
-**What if I want a different param than `:page` to dictate the current
-page?**  That can be configured with `Foliate.config.page_param`, which
-is set in "config/initializers/foliate.rb".
+## Full documentation
 
-**For even more information,** see the
+For more information, see the
 [full documentation](http://www.rubydoc.info/gems/foliate/).
 
 
@@ -86,7 +97,7 @@ gem "foliate"
 Then execute:
 
 ```bash
-$ bundle
+$ bundle install
 ```
 
 And finally, run the installation generator:

data/lib/foliate/config.rb

@@ -6,8 +6,8 @@ module Foliate
     attr_accessor :default_per_page
 
     # @return [Symbol]
-    #   URL query param name for specifying page numbers (defaults to
-    #   +:page+)
+    #   request query param name for specifying page numbers (defaults
+    #   to +:page+)
     attr_accessor :page_param
 
     def initialize
@@ -24,6 +24,7 @@ module Foliate
   end
 
   # @param c [Foliate::Config]
+  # @return [Foliate::Config]
   def self.config=(c)
     @config = c
   end

data/lib/foliate/controller.rb

@@ -20,7 +20,7 @@ module Foliate
     #
     # By default, if +records+ is an ActiveRecord::Relation, computes
     # the total number of pages by performing a SQL count query.  If the
-    # underlying table is very large, this query could have a noticeable
+    # underlying table is very large, this query can have a noticeable
     # performance cost.  This can be circumvented by specifying
     # +total_records:+, using an estimated or cached record count.
     #
@@ -28,10 +28,10 @@ module Foliate
     #   @posts = paginate(Post)
     #
     # @example paginated search
-    #   @posts = paginate(Post.where(status: params[:show_only]))
+    #   @posts = paginate(Post.where(author: params[:author]))
     #
     # @example user-specified per_page
-    #   @posts = paginate(Post, per_page: params[:at_a_time])
+    #   @posts = paginate(Post, per_page: params[:per])
     #
     # @example simple cached count
     #   count = Rails.cache.fetch("Post/count", expires_in: 5.minutes){ Post.count }

data/lib/foliate/pagination.rb

@@ -27,28 +27,54 @@ module Foliate
     #   originating request query params
     attr_accessor :query_params
 
-    # Computes the total number of pages based on +total_records+ and
-    # +per_page+.
+    # Computes the total number of pages based on {#total_records} and
+    # {#per_page}.
     #
     # @return [Integer]
     def total_pages
       (total_records / per_page.to_f).ceil
     end
 
-    # Computes the record set offset based on +current_page+ and
-    # +per_page+.
+    # Computes the record set offset based on {#current_page} and
+    # {#per_page}.
     #
     # @return [Integer]
     def offset
       (current_page - 1) * per_page
     end
 
+    # Iterates through each {#query_params} as name-value pairs.  Nested
+    # Hashes and Arrays are iterated as well.  The +name+ of nested a
+    # +value+ will reflect its nesting in the same way as when
+    # converting a nested Hash to a query string via +Hash#to_query+.
+    # Intended for use when generating form fields.
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    # @overload each_query_param
+    #   @yieldparam name [String]
+    #   @yieldparam value [String]
+    #   @return [nil]
+    #
+    # @overload each_query_param
+    #   @return [Enumerator]
+    def each_query_param
+      if block_given?
+        ParamsHelper.to_keyed_pairs(query_params).each do |pair|
+          yield pair[:name], pair[:value]
+        end
+        nil
+      else
+        to_enum(__method__)
+      end
+    end
+
     # Returns linking params for a specified +page_number+.  The
     # returned Hash is intended for use with +link_to+, +url_for+, etc.
     #
     # @example usage in view
-    #   link_to "First", pagination.params_for_page(1)
-    #   link_to "Last", pagination.params_for_page(pagination.total_pages)
+    #   link_to "First", @pagination.params_for_page(1)
+    #   link_to "Last", @pagination.params_for_page(@pagination.total_pages)
     #
     # @param page_number [Integer]
     # @return [Hash]
@@ -58,15 +84,14 @@ module Foliate
       ) }
     end
 
-    # Indicates if there is an expected page previous to the current
-    # page.
+    # Indicates if there is a page expected before the current page.
     #
     # @return [Boolean]
     def prev?
       current_page > 1
     end
 
-    # Indicates if there is an expected page beyond the current page.
+    # Indicates if there is a page expected after the current page.
     #
     # @return [Boolean]
     def next?
@@ -77,7 +102,7 @@ module Foliate
     # false.  See also {#params_for_page}.
     #
     # @example usage in view
-    #   link_to_if pagination.prev?, "Previous", pagination.prev_page_params
+    #   link_to_if @pagination.prev?, "Previous", @pagination.prev_page_params
     #
     # @return [Hash, nil]
     def prev_page_params
@@ -88,7 +113,7 @@ module Foliate
     # false.  See also {#params_for_page}.
     #
     # @example usage in view
-    #   link_to_if pagination.next?, "Next", pagination.next_page_params
+    #   link_to_if @pagination.next?, "Next", @pagination.next_page_params
     #
     # @return [Hash, nil]
     def next_page_params
@@ -107,5 +132,15 @@ module Foliate
       "pagination/pagination"
     end
 
+    module ParamsHelper
+      extend ActionView::Helpers::UrlHelper
+
+      def self.to_keyed_pairs(params)
+        to_form_params(params)
+      end
+    end
+
+    private_constant :ParamsHelper
+
   end
 end

data/lib/foliate/railtie.rb

@@ -2,6 +2,7 @@ require "rails/railtie"
 require "foliate/controller"
 
 module Foliate
+  # @!visibility private
   class Railtie < Rails::Railtie
     initializer :foliate do |app|
       ActiveSupport.on_load :action_controller do

data/lib/foliate/version.rb

@@ -1,3 +1,3 @@
 module Foliate
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/generators/foliate/install/install_generator.rb

@@ -2,6 +2,7 @@ require "foliate/config"
 require "rails/generators/base"
 
 module Foliate
+  # @!visibility private
   module Generators
     class InstallGenerator < Rails::Generators::Base
       source_root File.join(__dir__, "templates")

data/lib/generators/foliate/install/templates/views/page_input.html.erb

@@ -5,7 +5,7 @@
 
   <span class="foliate-i-of-n">
     <form method="get" class="foliate-form">
-      <% pagination.query_params.each do |name, value| %>
+      <% pagination.each_query_param do |name, value| %>
         <input type="hidden" name="<%= name %>" value="<%= value %>">
       <% end %>
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foliate
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-11 00:00:00.000000000 Z
+date: 2018-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.1.4
+        version: '5.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.1.4
+        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -93,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.5.2.1
 signing_key: 
 specification_version: 4
 summary: Rails pagination