folio-pagination 0.0.2

data/lib/folio/will_paginate/active_record.rb

@@ -0,0 +1,132 @@
+begin
+  require 'will_paginate/active_record'
+rescue LoadError
+  raise "folio-pagination's activerecord support requires will_paginate"
+end
+
+require 'folio/page'
+require 'folio/ordinal'
+require 'folio/ordinal/page'
+
+module Folio
+  module WillPaginate
+    # enhances model_or_scope.page(n) method from WillPaginate to behave like a
+    # Folio::Ordinal::Page. replaces model_or_scope.paginate(...) method to
+    # behave like that from Folio while preserving basic mechanics of the
+    # version from WillPaginate.
+    #
+    # differences:
+    #
+    #  * total_entries loading via count is *not* deferred as it was under
+    #    WillPaginate.
+    #
+    #  * paginate does *not* recognize any parameters beyond those described in
+    #    for Folio's paginate (e.g. finder options, count options).
+    #
+    module ActiveRecord
+      module RelationMethods
+        include Folio::Page
+        include Folio::Ordinal::Page
+
+        # overrides Folio::Page's per_page similar to WillPaginate's version,
+        # but uses correct semantics for per_page(nil) (vs. per_page()).
+        def per_page(*args)
+          if args.size > 0
+            raise ArgumentError if args.size > 1
+            value ||= @klass.per_page
+            limit(value)
+          end
+          limit_value
+        end
+
+        # overrides WillPaginate's weird "ignore limit when counting" behavior.
+        # I can't fall back on super in the branch with a limit_value, since
+        # that would fall into WillPaginate's lap, but since there is a
+        # limit_value, safe enough to just instantiate and check length
+        def count
+          if limit_value
+            to_a.size
+          else
+            super
+          end
+        end
+      end
+
+      module Pagination
+        # turns the sequence of calls made by Folio::Ordinal#paginate into the
+        # construction of an appropriate relation
+        class PageProxy
+          def initialize(target)
+            @target = target
+          end
+
+          # needed to prevent Folio::Ordinal#configure_pagination from trying
+          # to decorate it
+          include Folio::Ordinal::Page
+
+          # called during Folio#configure_pagination, used to build up @rel
+          # from @target and the arguments
+          attr_writer :current_page
+
+          def per_page=(per_page)
+            @rel = @target.limit(per_page.to_i).page(@current_page)
+            @rel.limit_value
+          end
+
+          def total_entries=(total_entries)
+            @rel.total_entries = total_entries
+          end
+
+          # called during Folio::Ordinal#configure_pagination for bounds
+          # checking, before the proxy has been replaced by its result
+          def current_page
+            @rel.current_page
+          end
+
+          def out_of_bounds?
+            @rel.out_of_bounds?
+          end
+
+          # get the result of the construction back out during fill_page
+          def result
+            @rel
+          end
+        end
+
+        # set up the proxy to receive the calls
+        def build_page
+          PageProxy.new(self)
+        end
+
+        # pull the result out of the proxy
+        def fill_page(proxy)
+          proxy.result
+        end
+
+        # make sure the relation coming out of page(...) is folio-compatible
+        def page(num)
+          super.extending(RelationMethods)
+        end
+
+        # don't try and look at Class (ActiveRecord::Base.class, etc.) for
+        # defaults
+        def default_per_page
+          Folio.per_page
+        end
+
+        include ::Folio::Ordinal
+      end
+
+      # mix into Active Record. these are the same ones that WillPaginate mixes
+      # its version of Pagination into.
+      ::ActiveRecord::Base.extend Pagination
+      klasses = [::ActiveRecord::Relation]
+      if defined? ::ActiveRecord::Associations::CollectionProxy
+        klasses << ::ActiveRecord::Associations::CollectionProxy
+      else
+        klasses << ::ActiveRecord::Associations::AssociationCollection
+      end
+      klasses.each { |klass| klass.send(:include, Pagination) }
+    end
+  end
+end

data/lib/folio/will_paginate/collection.rb

@@ -0,0 +1,19 @@
+require 'folio'
+require 'folio/ordinal/page'
+require 'will_paginate/collection'
+
+# overrides WillPaginate::Collection.create to return an ordinal folio page
+# instead of a WillPaginate::Collection; the rest of WillPaginate::Collection
+# is unused when in folio-land.
+module WillPaginate
+  class Collection
+    def self.create(current_page, per_page=nil, total_entries=nil)
+      page = ::Folio::Ordinal::Page.create
+      page.current_page = current_page
+      page.per_page = per_page
+      page.total_entries = total_entries
+      yield page if block_given?
+      page
+    end
+  end
+end

data/lib/folio/will_paginate/view_helpers/action_view.rb

@@ -0,0 +1,10 @@
+begin
+  require 'will_paginate/view_helpers/action_view'
+rescue LoadError
+  raise "folio-pagination's actionview support requires will_paginate"
+end
+
+require 'folio/will_paginate/view_helpers'
+
+# no overrides specific to action view necessary. just including the general
+# view_helper overrides as above is sufficient.

data/lib/folio/will_paginate/view_helpers/link_renderer.rb

@@ -0,0 +1,54 @@
+require 'will_paginate/view_helpers/link_renderer'
+
+module Folio
+  module WillPaginate
+    module ViewHelpers
+      module LinkRenderer
+        def previous_page_with_folio
+          # the page identifier may not be ordinal; use the value as set on the
+          # collection, instead.
+          previous_or_next_page(@collection.previous_page, @options[:previous_label], 'previous_page')
+        end
+
+        def next_page_with_folio
+          # the page identifier may not be ordinal; use the value as set on the
+          # collection, instead.
+          previous_or_next_page(@collection.next_page, @options[:next_label], 'next_page')
+        end
+
+        def link_with_folio(text, target, attributes = {})
+          if target
+            # the non-folio version only does this for Fixnums, but we want to
+            # do it for any page value. fortunately, this method only ever
+            # receives Fixnums or nil, so we can do it now for any non-nil
+            # value, and the non-folio version will happily avoid a double
+            # application because even when the page was a fixnum, it won't be
+            # anymore.
+            attributes[:rel] = rel_value(target)
+            target = url(target)
+          end
+          link_without_folio(text, target, attributes)
+        end
+
+        def rel_value_with_folio(page)
+          # don't check against mathed out values, just check the values on the
+          # collection
+          rels = []
+          rels << 'prev' if page == @collection.previous_page
+          rels << 'next' if page == @collection.next_page
+          rels << 'start' if page == @collection.first_page
+          rels.empty? ? nil : rels.join(' ')
+        end
+
+        def self.included(klass)
+          [:previous_page, :next_page, :link, :rel_value].each do |method|
+            klass.send(:alias_method, :"#{method}_without_folio", method)
+            klass.send(:alias_method, method, :"#{method}_with_folio")
+          end
+        end
+
+        ::WillPaginate::ViewHelpers::LinkRenderer.send :include, self
+      end
+    end
+  end
+end

data/lib/folio/will_paginate/view_helpers/link_renderer_base.rb

@@ -0,0 +1,44 @@
+require 'will_paginate/view_helpers/link_renderer_base'
+
+module Folio
+  module WillPaginate
+    module ViewHelpers
+      module LinkRendererBase
+        def prepare_with_folio(collection, options)
+          # only include page_links if we're in a collection with ordinal
+          # pages; otherwise stick to just prev/next.
+          options = options.merge(page_links: false) unless collection.ordinal_pages?
+          prepare_without_folio(collection, options)
+        end
+
+        def windowed_page_numbers_with_folio
+          page_numbers = windowed_page_numbers_without_folio
+          unless @collection.last_page
+            # the last page is not known, so add a trailing gap (it won't
+            # already be there, because the right range during the super call
+            # won't exist).
+            page_numbers << :gap
+          end
+          page_numbers
+        end
+
+        def total_pages_with_folio
+          # the collection may not have a known last page. if so, there must be
+          # a next page; count that as the last known page. it's ok to use
+          # these page identifiers as a page count because (after fixing
+          # LinkRenderer) it's only called when ordinal_pages is true.
+          @collection.last_page || @collection.next_page
+        end
+
+        def self.included(klass)
+          [:prepare, :windowed_page_numbers, :total_pages].each do |method|
+            klass.send(:alias_method, :"#{method}_without_folio", method)
+            klass.send(:alias_method, method, :"#{method}_with_folio")
+          end
+        end
+
+        ::WillPaginate::ViewHelpers::LinkRendererBase.send :include, self
+      end
+    end
+  end
+end

data/lib/folio/will_paginate/view_helpers.rb

@@ -0,0 +1,57 @@
+require 'folio'
+require 'folio/will_paginate/view_helpers/link_renderer_base'
+require 'folio/will_paginate/view_helpers/link_renderer'
+require 'will_paginate/view_helpers'
+
+module Folio
+  module WillPaginate
+    module ViewHelpers
+      # just copied from ::WillPaginate::ViewHelpers except line 14 (changed from
+      # "unless value > 1" to "if value == 1" to be friendly to unknown
+      # total_pages)
+      def will_paginate_with_folio(collection, options = {})
+        # early exit if there is nothing to render
+        return nil if collection.total_pages == 1
+
+        options = ::WillPaginate::ViewHelpers.pagination_options.merge(options)
+
+        options[:previous_label] ||= will_paginate_translate(:previous_label) { '← Previous' }
+        options[:next_label]     ||= will_paginate_translate(:next_label) { 'Next →' }
+
+        # get the renderer instance
+        renderer = case options[:renderer]
+        when nil
+          raise ArgumentError, ":renderer not specified"
+        when String
+          klass = if options[:renderer].respond_to? :constantize then options[:renderer].constantize
+            else Object.const_get(options[:renderer]) # poor man's constantize
+            end
+          klass.new
+        when Class then options[:renderer].new
+        else options[:renderer]
+        end
+        # render HTML for pagination
+        renderer.prepare collection, options, self
+        output = renderer.to_html
+        output = output.html_safe if output.respond_to?(:html_safe)
+        output
+      end
+
+      def page_entries_info_with_folio(collection, options = {})
+        # skip outputting anything unless the collection has ordinal pages (to
+        # be able to get an offset) *and* a known total count.
+        return unless collection.total_entries && collection.ordinal_pages
+        page_entries_info_without_folio(collection, options)
+      end
+
+      def self.included(klass)
+        [:will_paginate, :page_entries_info].each do |method|
+          klass.send(:alias_method, :"#{method}_without_folio", method)
+          klass.send(:alias_method, method, :"#{method}_with_folio")
+        end
+      end
+
+      ::WillPaginate::ViewHelpers.send :include, self
+    end
+  end
+end

data/lib/folio-pagination.rb

@@ -0,0 +1,3 @@
+# convenience so that you can require by the gem name and get the same effect
+# as requiring the canonical 'folio'.
+require 'folio'

data/lib/folio.rb

@@ -0,0 +1,84 @@
+require "folio/version"
+require "folio/per_page"
+
+# 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.
+module Folio
+  # 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.
+  def paginate(options={})
+    page = self.build_page
+    page = self.configure_pagination(page, options)
+    page = self.fill_page(page)
+    page
+  end
+
+  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
+
+  def default_per_page
+    self.class.per_page
+  end
+
+  include ::Folio::PerPage
+
+  # this funny pattern is so that if a module (e.g. Folio::Ordinal)
+  # includes this module, it won't get the per_page attribute, but will
+  # still be able to bestow that attribute on any class that includes
+  # *it*.
+  module PerPageIncluder
+    def included(klass)
+      if klass.is_a?(Class)
+        klass.extend ::Folio::PerPage
+      else
+        klass.extend ::Folio::PerPageIncluder
+      end
+    end
+  end
+
+  extend PerPageIncluder
+  extend PerPage
+  per_page(30)
+end
+
+# load the other commonly used portions of the gem
+require "folio/page"
+require "folio/ordinal"
+require "folio/ordinal/page"

data/test/folio/core_ext/enumerable_test.rb

@@ -0,0 +1,55 @@
+require 'minitest/autorun'
+require 'folio/core_ext/enumerable'
+
+describe Array do
+  it "should be an ordinal folio" do
+    assert_respond_to [], :build_page
+    [].build_page.first_page.must_equal 1
+  end
+
+  describe "per_page" do
+    it "should have per_page attribute as expected on instances" do
+      assert_respond_to [], :per_page
+      assert_respond_to [], :per_page=
+    end
+
+    it "should not have per_page attribute on classes" do
+      Array.wont_respond_to :per_page
+      Array.wont_respond_to :per_page=
+    end
+
+    it "should default to Folio.per_page" do
+      was = Folio.per_page
+      Folio.per_page = 100
+      [].per_page.must_equal 100
+      Folio.per_page = was
+    end
+  end
+
+  describe "paginate" do
+    before do
+      @ary = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+    end
+
+    it "should return a page" do
+      page = @ary.paginate
+      assert_respond_to page, :current_page
+    end
+
+    it "should return appropriate slice" do
+      @ary.paginate(page: 2, per_page: 4).must_equal [5, 6, 7, 8]
+    end
+
+    it "should return partial slice at end" do
+      @ary.paginate(page: 3, per_page: 4).must_equal [9, 10]
+    end
+
+    it "should raise InvalidPage after end even if size unknown" do
+      lambda{ @ary.paginate(page: 3, per_page: 5, total_entries: nil) }.must_raise Folio::InvalidPage
+    end
+
+    it "should return empty first page if empty" do
+      [].paginate.must_equal []
+    end
+  end
+end

data/test/folio/ordinal/page_test.rb

@@ -0,0 +1,173 @@
+require 'minitest/autorun'
+require 'folio/ordinal'
+
+describe Folio::Ordinal::Page do
+  before do
+    @page = Folio::Ordinal::Page.create
+    @page.current_page = 1
+    @page.per_page = 10
+    @page.total_entries = 30
+  end
+
+  it "should have ordinal_pages=true" do
+    @page.ordinal_pages.must_equal true
+    @page.ordinal_pages?.must_equal true
+  end
+
+  it "should have first_page=1" do
+    @page.first_page.must_equal 1
+  end
+
+  it "should force current_page to an integer" do
+    @page.current_page = "3"
+    @page.current_page.must_equal 3
+  end
+
+  describe "when total pages known" do
+    it "should have last_page=total_pages" do
+      @page.last_page.must_equal @page.total_pages
+
+      @page.total_entries = 0
+      @page.last_page.must_equal @page.total_pages
+
+      @page.total_entries = nil
+      @page.last_page.must_equal @page.total_pages
+    end
+
+    it "should have next_page=current_page+1 when not at end" do
+      @page.current_page = 2
+      @page.next_page.must_equal 3
+    end
+
+    it "should still have next_page=current_page+1 when not at end, despite set value" do
+      @page.current_page = 2
+      @page.next_page = nil
+      @page.next_page.must_equal 3
+    end
+
+    it "should have next_page=nil when at end" do
+      @page.current_page = 3
+      @page.next_page.must_be_nil
+    end
+
+    it "should still have next_page=nil when at end, despite set value" do
+      @page.current_page = 3
+      @page.next_page = 4
+      @page.next_page.must_be_nil
+    end
+  end
+
+  describe "when total pages not known" do
+    before do
+      @page.total_entries = nil
+    end
+
+    it "should have last_page=nil if next_page is known or assumed" do
+      # @page.next_page unset
+      @page.last_page.must_be_nil
+
+      # @page.next_page explicitly non-nil
+      @page.next_page = 2
+      @page.last_page.must_be_nil
+    end
+
+    it "should have last_page=current_page if next_page is explicitly nil" do
+      @page.next_page = nil
+      @page.last_page.must_equal @page.current_page
+    end
+
+    it "should have next_page=current_page+1 when not explicitly set" do
+      @page.current_page = 2
+      @page.next_page.must_equal 3
+    end
+
+    it "should force non-nil set next_page to an integer" do
+      @page.next_page = "4"
+      @page.next_page.must_equal 4
+    end
+
+    it "should not force nil set next_page to an integer" do
+      @page.next_page = nil
+      @page.next_page.must_be_nil
+    end
+
+    it "should have next_page=set value when explicitly set" do
+      @page.next_page = nil
+      @page.current_page = 2
+      @page.next_page.must_be_nil
+    end
+  end
+
+  it "should have previous_page=nil when at beginning" do
+    @page.current_page = 1
+    @page.previous_page.must_be_nil
+  end
+
+  it "should have previous_page=current_page-1 when not at beginning" do
+    @page.current_page = 3
+    @page.previous_page.must_equal 2
+  end
+
+  describe "out_of_bounds?" do
+    it "should be false if in first_page..last_page range" do
+      @page.current_page = 1
+      @page.out_of_bounds?.must_equal false
+
+      @page.current_page = 3
+      @page.out_of_bounds?.must_equal false
+    end
+
+    it "should be true if negative page" do
+      @page.current_page = -1
+      @page.out_of_bounds?.must_equal true
+    end
+
+    it "should be true if zero page" do
+      @page.current_page = 0
+      @page.out_of_bounds?.must_equal true
+    end
+
+    it "should be true after known last_page" do
+      @page.current_page = 4
+      @page.out_of_bounds?.must_equal true
+    end
+
+    it "should not care about large numbers when total_pages not known" do
+      @page.total_entries = nil
+      @page.current_page = 50
+      @page.out_of_bounds?.must_equal false
+    end
+  end
+
+  describe "decorate" do
+    before do
+      @page = Folio::Ordinal::Page.decorate([])
+    end
+
+    it "should add page methods to the object" do
+      assert_respond_to @page, :current_page
+    end
+
+    it "should add ordinal page methods to the object" do
+      @page.first_page.must_equal 1
+    end
+
+    it "should preserve other methods on the object" do
+      assert_respond_to @page, :each
+    end
+  end
+
+  describe "create" do
+    before do
+      @page = Folio::Ordinal::Page.create
+    end
+
+    it "should be an Array at heart" do
+      @page.must_be :is_a?, Array
+    end
+
+    it "should be decorated as an ordinal page" do
+      @page.first_page.must_equal 1
+    end
+  end
+end

data/test/folio/ordinal_test.rb

@@ -0,0 +1,57 @@
+require 'minitest/autorun'
+require 'folio/ordinal'
+
+describe Folio::Ordinal do
+  before do
+    klass = Class.new do
+      def build_page
+        Folio::Page.create
+      end
+
+      def fill_page(page)
+        page
+      end
+
+      include Folio::Ordinal
+    end
+    @folio = klass.new
+  end
+
+  describe "paginate" do
+    it "should decorate the result of build_page" do
+      @page = @folio.paginate
+      @page.is_a?(Folio::Ordinal::Page).must_equal true
+    end
+
+    describe "bounds checking" do
+      before do
+        @folio.per_page = 10
+      end
+
+      it "should raise on non-integer page" do
+        lambda{ @folio.paginate(page: "non-integer") }.must_raise Folio::InvalidPage
+      end
+
+      it "should raise on negative page" do
+        lambda{ @folio.paginate(page: -1) }.must_raise Folio::InvalidPage
+      end
+
+      it "should raise on page of 0" do
+        lambda{ @folio.paginate(page: 0) }.must_raise Folio::InvalidPage
+      end
+
+      it "should raise on page greater than known last_page" do
+        lambda{ @folio.paginate(page: 4, total_entries: 30) }.must_raise Folio::InvalidPage
+      end
+
+      it "should not raise on page number between first_page and known last_page" do
+        @folio.paginate(page: 1, total_entries: 30)
+        @folio.paginate(page: 3, total_entries: 30)
+      end
+
+      it "should not raise on large page if last_page unknown" do
+        @folio.paginate(page: 100)
+      end
+    end
+  end
+end