will_paginate 3.0.pre4 → 3.0.0

data/lib/will_paginate/finders/base.rb

@@ -1,112 +0,0 @@
-require 'will_paginate/core_ext'
-
-module WillPaginate
-  module Finders
-    # = Database-agnostic finder module
-    # 
-    # Out of the box, will_paginate supports hooking in several ORMs to
-    # provide paginating finders based on their API. As of this writing, the
-    # supported libraries are:
-    #
-    # * ActiveRecord
-    # * DataMapper
-    # * Sequel
-    #
-    # It's easy to write your own adapter for anything that can load data with
-    # explicit limit and offset settings. DataMapper adapter is a nice and
-    # compact example of writing an adapter to bring the +paginate+ method to
-    # DataMapper models.
-    #
-    # == The importance of SQL's <tt>ORDER BY</tt>
-    #
-    # In most ORMs, <tt>:order</tt> parameter specifies columns for the
-    # <tt>ORDER BY</tt> clause in SQL. It is important to have it, since
-    # pagination only makes sense with ordered sets. Without the order clause,
-    # databases aren't required to do consistent ordering when performing
-    # <tt>SELECT</tt> queries.
-    # 
-    # Ordering by a field for which many records share the same value (e.g.
-    # "status") can still result in incorrect ordering with some databases (MS
-    # SQL and Postgres for instance). With these databases it's recommend that
-    # you order by primary key as well. That is, instead of ordering by
-    # "status DESC", use the alternative "status DESC, id DESC" and this will
-    # yield consistent results.
-    #
-    # Therefore, make sure you are doing ordering on a column that makes the
-    # most sense in the current context. Make that obvious to the user, also.
-    # For perfomance reasons you will also want to add an index to that column.
-    module Base
-      def per_page
-        @per_page ||= 30
-      end
-      
-      def per_page=(limit)
-        @per_page = limit.to_i
-      end
-      
-      # This is the main paginating finder.
-      #
-      # == Special parameters for paginating finders
-      # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
-      # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 30 if not overridden)
-      # * <tt>:total_entries</tt> -- use only if you manually count total entries
-      # * <tt>:count</tt> -- additional options that are passed on to +count+
-      # * <tt>:finder</tt> -- name of the finder method to use (default: "find")
-      #
-      # All other options (+conditions+, +order+, ...) are forwarded to +find+
-      # and +count+ calls.
-      def paginate(*args, &block)
-        options = args.pop
-        page, per_page, total_entries = wp_parse_options(options)
-
-        WillPaginate::Collection.create(page, per_page, total_entries) do |pager|
-          query_options = options.except :page, :per_page, :total_entries
-          wp_query(query_options, pager, args, &block)
-        end
-      end
-
-      # Iterates through all records by loading one page at a time. This is useful
-      # for migrations or any other use case where you don't want to load all the
-      # records in memory at once.
-      #
-      # It uses +paginate+ internally; therefore it accepts all of its options.
-      # You can specify a starting page with <tt>:page</tt> (default is 1). Default
-      # <tt>:order</tt> is <tt>"id"</tt>, override if necessary.
-      #
-      # {Jamis Buck describes this}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
-      # and also uses a more efficient way for MySQL.
-      def paginated_each(options = {}, &block)
-        options = { :order => 'id', :page => 1 }.merge options
-        options[:page] = options[:page].to_i
-        options[:total_entries] = 0 # skip the individual count queries
-        total = 0
-        
-        begin 
-          collection = paginate(options)
-          total += collection.each(&block).size
-          options[:page] += 1
-        end until collection.size < collection.per_page
-        
-        total
-      end
-      
-      protected
-        
-        def wp_parse_options(options) #:nodoc:
-          raise ArgumentError, 'parameter hash expected' unless Hash === options
-          raise ArgumentError, ':page parameter required' unless options.key? :page
-          
-          if options[:count] and options[:total_entries]
-            raise ArgumentError, ':count and :total_entries are mutually exclusive'
-          end
-
-          page     = options[:page] || 1
-          per_page = options[:per_page] || self.per_page
-          total    = options[:total_entries]
-          
-          return [page, per_page, total]
-        end
-        
-    end
-  end
-end

data/lib/will_paginate/finders/data_mapper.rb

@@ -1,30 +0,0 @@
-require 'will_paginate/finders/base'
-require 'dm-core'
-
-module WillPaginate::Finders
-  module DataMapper
-    include WillPaginate::Finders::Base
-
-  protected
-    
-    def wp_query(options, pager, args, &block) #:nodoc
-      find_options = options.except(:count).update(:offset => pager.offset, :limit => pager.per_page) 
-
-      pager.replace all(find_options, &block)
-      
-      unless pager.total_entries
-        pager.total_entries = wp_count(options)
-      end
-    end
-
-    def wp_count(options) #:nodoc
-      count_options = options.except(:count, :order)
-      # merge the hash found in :count
-      count_options.update options[:count] if options[:count]
-
-      count_options.empty?? count() : count(count_options)
-    end
-  end
-end
-
-DataMapper::Model.send(:include, WillPaginate::Finders::DataMapper)

data/lib/will_paginate/finders/sequel.rb

@@ -1,23 +0,0 @@
-require 'will_paginate/core_ext'
-require 'sequel'
-require 'sequel/extensions/pagination'
-
-existing_methods = Sequel::Dataset::Pagination.instance_methods
-
-Sequel::Dataset::Pagination.module_eval do
-  # it should quack like a WillPaginate::Collection
-  
-  alias :total_pages   :page_count  unless existing_methods.include_method? :total_pages
-  alias :per_page      :page_size   unless existing_methods.include_method? :per_page
-  alias :previous_page :prev_page   unless existing_methods.include_method? :previous_page
-  alias :total_entries :pagination_record_count unless existing_methods.include_method? :total_entries
-  
-  def out_of_bounds?
-    current_page > total_pages
-  end
-
-  # Current offset of the paginated collection
-  def offset
-    (current_page - 1) * per_page
-  end
-end

data/lib/will_paginate/view_helpers/base.rb

@@ -1,126 +0,0 @@
-require 'will_paginate/core_ext'
-require 'will_paginate/view_helpers'
-
-module WillPaginate
-  module ViewHelpers
-    # = The main view helpers module
-    #
-    # This is the base module which provides the +will_paginate+ view helper.
-    module Base
-      # Renders Digg/Flickr-style pagination for a WillPaginate::Collection object. Nil is
-      # returned if there is only one page in total; pagination links aren't needed in that case.
-      # 
-      # ==== Options
-      # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
-      # * <tt>:previous_label</tt> -- default: "« Previous"
-      # * <tt>:next_label</tt> -- default: "Next »"
-      # * <tt>:inner_window</tt> -- how many links are shown around the current page (default: 4)
-      # * <tt>:outer_window</tt> -- how many links are around the first and the last page (default: 1)
-      # * <tt>:separator</tt> -- string separator for page HTML elements (default: single space)
-      # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
-      # * <tt>:params</tt> -- additional parameters when generating pagination links
-      #   (eg. <tt>:controller => "foo", :action => nil</tt>)
-      # * <tt>:renderer</tt> -- class name, class or instance of a link renderer (default:
-      #   <tt>WillPaginate::LinkRenderer</tt>)
-      # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
-      # * <tt>:container</tt> -- toggles rendering of the DIV container for pagination links, set to
-      #   false only when you are rendering your own pagination markup (default: true)
-      # * <tt>:id</tt> -- HTML ID for the container (default: nil). Pass +true+ to have the ID
-      #   automatically generated from the class name of objects in collection: for example, paginating
-      #   ArticleComment models would yield an ID of "article_comments_pagination".
-      #
-      # All options beside listed ones are passed as HTML attributes to the container
-      # element for pagination links (the DIV). For example:
-      # 
-      #   <%= will_paginate @posts, :id => 'wp_posts' %>
-      #
-      # ... will result in:
-      #
-      #   <div class="pagination" id="wp_posts"> ... </div>
-      #
-      def will_paginate(collection, options = {})
-        # early exit if there is nothing to render
-        return nil unless collection.total_pages > 1
-        
-        options = WillPaginate::ViewHelpers.pagination_options.merge(options)
-        
-        if options[:prev_label]
-          WillPaginate::Deprecation::warn(":prev_label view parameter is now :previous_label; the old name has been deprecated.")
-          options[:previous_label] = options.delete(:prev_label)
-        end
-        
-        # get the renderer instance
-        renderer = case options[:renderer]
-        when String
-          options[:renderer].constantize.new
-        when Class
-          options[:renderer].new
-        else
-          options[:renderer]
-        end
-        # render HTML for pagination
-        renderer.prepare collection, options, self
-        renderer.to_html
-      end
-      
-      # Renders a helpful message with numbers of displayed vs. total entries.
-      # You can use this as a blueprint for your own, similar helpers.
-      #
-      #   <%= page_entries_info @posts %>
-      #   #-> Displaying posts 6 - 10 of 26 in total
-      #
-      # By default, the message will use the humanized class name of objects
-      # in collection: for instance, "project types" for ProjectType models.
-      # Override this to your liking with the <tt>:entry_name</tt> parameter:
-      #
-      #   <%= page_entries_info @posts, :entry_name => 'item' %>
-      #   #-> Displaying items 6 - 10 of 26 in total
-      #
-      # Entry name is entered in singular and pluralized with
-      # <tt>String#pluralize</tt> method from ActiveSupport. If it isn't
-      # loaded, specify plural with <tt>:plural_name</tt> parameter:
-      #
-      #   <%= page_entries_info @posts, :entry_name => 'item', :plural_name => 'items' %>
-      #
-      # By default, this method produces HTML output. You can trigger plain
-      # text output by passing <tt>:html => false</tt> in options.
-      def page_entries_info(collection, options = {})
-        entry_name = options[:entry_name] || (collection.empty?? 'entry' :
-                     collection.first.class.name.underscore.gsub('_', ' '))
-        
-        plural_name = if options[:plural_name]
-          options[:plural_name]
-        elsif entry_name == 'entry'
-          plural_name = 'entries'
-        elsif entry_name.respond_to? :pluralize
-          plural_name = entry_name.pluralize
-        else
-          entry_name + 's'
-        end
-
-        unless options[:html] == false
-          b  = '<b>'
-          eb = '</b>'
-          sp = '&nbsp;'
-        else
-          b  = eb = ''
-          sp = ' '
-        end
-        
-        if collection.total_pages < 2
-          case collection.size
-          when 0; "No #{plural_name} found"
-          when 1; "Displaying #{b}1#{eb} #{entry_name}"
-          else;   "Displaying #{b}all #{collection.size}#{eb} #{plural_name}"
-          end
-        else
-          %{Displaying #{plural_name} #{b}%d#{sp}-#{sp}%d#{eb} of #{b}%d#{eb} in total} % [
-            collection.offset + 1,
-            collection.offset + collection.length,
-            collection.total_entries
-          ]
-        end
-      end
-    end
-  end
-end

data/spec/finders/active_resource_spec.rb

@@ -1,52 +0,0 @@
-require 'spec_helper'
-require 'will_paginate/finders/active_resource'
-require 'active_resource/http_mock'
-
-class AresProject < ActiveResource::Base
-  self.site = 'http://localhost:4000'
-end
-
-describe WillPaginate::Finders::ActiveResource do
-  
-  before :all do
-    # ActiveResource::HttpMock.respond_to do |mock|      
-    #   mock.get "/ares_projects.xml?page=1&per_page=5", {}, [].to_xml
-    # end
-  end
-  
-  it "should integrate with ActiveResource::Base" do
-    ActiveResource::Base.should respond_to(:paginate)
-  end
-  
-  it "should error when no parameters for #paginate" do
-    lambda { AresProject.paginate }.should raise_error(ArgumentError)
-  end
-  
-  it "should paginate" do
-    AresProject.expects(:find_every).with(:params => { :page => 1, :per_page => 5 }).returns([])
-    AresProject.paginate(:page => 1, :per_page => 5)
-  end
-  
-  it "should have 30 per_page as default" do
-    AresProject.expects(:find_every).with(:params => { :page => 1, :per_page => 30 }).returns([])
-    AresProject.paginate(:page => 1)
-  end
-  
-  it "should support #paginate(:all)" do
-    lambda { AresProject.paginate(:all) }.should raise_error(ArgumentError)
-  end
-  
-  it "should error #paginate(:other)" do
-    lambda { AresProject.paginate(:first) }.should raise_error(ArgumentError)
-  end
-  
-  protected
-  
-    def create(page = 2, limit = 5, total = nil, &block)
-      if block_given?
-        WillPaginate::Collection.create(page, limit, total, &block)
-      else
-        WillPaginate::Collection.new(page, limit, total)
-      end
-    end  
-end

data/spec/finders_spec.rb

@@ -1,76 +0,0 @@
-require 'spec_helper'
-require 'will_paginate/finders/base'
-
-class Model
-  extend WillPaginate::Finders::Base
-end
-
-describe WillPaginate::Finders::Base do
-  it "should define default per_page of 30" do
-    Model.per_page.should == 30
-  end
-  
-  it "should allow to set custom per_page" do
-    begin
-      Model.per_page = 25
-      Model.per_page.should == 25
-    ensure
-      Model.per_page = 30
-    end
-  end
-
-  it "should result with WillPaginate::Collection" do
-    Model.expects(:wp_query)
-    Model.paginate(:page => nil).should be_instance_of(WillPaginate::Collection)
-  end
-
-  it "should delegate pagination to wp_query" do
-    Model.expects(:wp_query).with({}, instance_of(WillPaginate::Collection), [])
-    Model.paginate :page => nil
-  end
-
-  it "should complain when no hash parameters given" do
-    lambda {
-      Model.paginate
-    }.should raise_error(ArgumentError, 'parameter hash expected')
-  end
-
-  it "should complain when no :page parameter present" do
-    lambda {
-      Model.paginate :per_page => 6
-    }.should raise_error(ArgumentError, ':page parameter required')
-  end
-
-  it "should complain when both :count and :total_entries are given" do
-    lambda {
-      Model.paginate :page => 1, :count => {}, :total_entries => 1
-    }.should raise_error(ArgumentError, ':count and :total_entries are mutually exclusive')
-  end
-
-  it "should never mangle options" do
-    options = { :page => 1 }
-    options.expects(:delete).never
-    options_before = options.dup
-    
-    Model.expects(:wp_query)
-    Model.paginate(options)
-    
-    options.should == options_before
-  end
-
-  it "should provide paginated_each functionality" do
-    collection = stub('collection', :size => 5, :empty? => false, :per_page => 5)
-    collection.expects(:each).times(2).returns(collection)
-    last_collection = stub('collection', :size => 4, :empty? => false, :per_page => 5)
-    last_collection.expects(:each).returns(last_collection)
-    
-    params = { :order => 'id', :total_entries => 0 }
-    
-    Model.expects(:paginate).with(params.merge(:page => 2)).returns(collection)
-    Model.expects(:paginate).with(params.merge(:page => 3)).returns(collection)
-    Model.expects(:paginate).with(params.merge(:page => 4)).returns(last_collection)
-    
-    total = Model.paginated_each(:page => '2') { }
-    total.should == 14
-  end
-end