hobo_will_paginate 2.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZjdmYzE1NDE1YzU4NzFkOTM2MzcyZjJkNzM5ODIyYzNiYmNmZTcxYQ==
+  data.tar.gz: !binary |-
+    Mzc3MTg1ZDhkNTE1YmM4ZmQ3YzIwMGMzYTM2MTRmNTBkMmQxZmY2Zg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YmJmMzQ1ZWZkMGZkY2Y5ZjMwODg3YjA3ODY1ZDE1YTQzMmVhMzFiZDljMGJi
+    ODA5YTBhNzdjZWEyYWZiYWU1MzcwZTBiNWIxM2E3Y2QwZWM2NTUxNTRlOWZl
+    ODBhMmIwOWViMjcyY2NmNTNjZDUwNTBmZDljYTk1NzQ2NWM5MDU=
+  data.tar.gz: !binary |-
+    N2ZmNWM4MDBiM2IxOWRlNGMxOTU5MTQxMjIyMThlOTdiYjhiNTExZTNhZWRl
+    NDExY2Y5YWMxOGQ5OWEwZjQyYmVmNGIwZWE5MjhhMmRiOTJlMTVlN2QyOWJl
+    NDA2ZDMxODhlOGYzYzkwYzg0YzBlZmJkMTU0YzQ0YzMyMzFlNTI=

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2009 Mislav Marohnić
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
+the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+# will_paginate
+
+will_paginate is a pagination library that integrates with Ruby on Rails, Sinatra, Merb, DataMapper and Sequel.
+
+Installation:
+
+``` ruby
+## Gemfile for Rails 3, Sinatra, and Merb
+gem 'will_paginate', '~> 3.0'
+```
+
+See [installation instructions][install] on the wiki for more info.
+
+
+## Basic will_paginate use
+
+``` ruby
+## perform a paginated query:
+@posts = Post.paginate(:page => params[:page])
+
+# or, use an explicit "per page" limit:
+Post.paginate(:page => params[:page], :per_page => 30)
+
+## render page links in the view:
+<%= will_paginate @posts %>
+```
+
+And that's it! You're done. You just need to add some CSS styles to [make those pagination links prettier][css].
+
+You can customize the default "per_page" value:
+
+``` ruby
+# for the Post model
+class Post
+  self.per_page = 10
+end
+
+# set per_page globally
+WillPaginate.per_page = 10
+```
+
+New in Active Record 3:
+
+``` ruby
+# paginate in Active Record now returns a Relation
+Post.where(:published => true).paginate(:page => params[:page]).order('id DESC')
+
+# the new, shorter page() method
+Post.page(params[:page]).order('created_at DESC')
+```
+
+See [the wiki][wiki] for more documentation. [Ask on the group][group] if you have usage questions. [Report bugs][issues] on GitHub.
+
+Happy paginating.
+
+
+[wiki]: https://github.com/mislav/will_paginate/wiki
+[install]: https://github.com/mislav/will_paginate/wiki/Installation "will_paginate installation"
+[group]: http://groups.google.com/group/will_paginate "will_paginate discussion and support group"
+[issues]: https://github.com/mislav/will_paginate/issues
+[css]: http://mislav.uniqpath.com/will_paginate/

data/Rakefile

@@ -0,0 +1,25 @@
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+  # no spec tasks
+else
+  task :default => :spec
+
+  desc 'Run ALL OF the specs'
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    # t.ruby_opts = '-w'
+    t.pattern = 'spec/finders/active_record_spec.rb' if ENV['DB'] and ENV['DB'] != 'sqlite3'
+  end
+
+  namespace :spec do
+    desc "Run Rails specs"
+    RSpec::Core::RakeTask.new(:rails) do |t|
+      t.pattern = %w'spec/finders/active_record_spec.rb spec/view_helpers/action_view_spec.rb'
+    end
+  end
+end
+
+desc 'Run specs against both Rails 3.1 and Rails 3.0'
+task :rails3 do |variable|
+  system 'bundle exec rake spec && BUNDLE_GEMFILE=Gemfile.rails3.0 bundle exec rake spec:rails'
+end

data/lib/will_paginate.rb

@@ -0,0 +1,25 @@
+# You will paginate!
+module WillPaginate
+end
+
+if defined?(Rails::Railtie)
+  require 'will_paginate/railtie'
+elsif defined?(Rails::Initializer)
+  raise "will_paginate 3.0 is not compatible with Rails 2.3 or older"
+end
+
+if defined?(Merb::AbstractController)
+  require 'will_paginate/view_helpers/merb'
+
+  Merb::BootLoader.before_app_loads do
+    adapters = { :datamapper => 'data_mapper', :activerecord => 'active_record', :sequel => 'sequel' }
+    # auto-load the right ORM adapter
+    if adapter = adapters[Merb.orm]
+      require "will_paginate/#{adapter}"
+    end
+  end
+end
+
+if defined?(Sinatra) and Sinatra.respond_to? :register
+  require 'will_paginate/view_helpers/sinatra'
+end

data/lib/will_paginate/active_record.rb

@@ -0,0 +1,216 @@
+require 'will_paginate/per_page'
+require 'will_paginate/page_number'
+require 'will_paginate/collection'
+require 'active_record'
+
+module WillPaginate
+  # = Paginating finders for ActiveRecord models
+  # 
+  # WillPaginate adds +paginate+, +per_page+ and other methods to
+  # ActiveRecord::Base class methods and associations.
+  # 
+  # In short, paginating finders are equivalent to ActiveRecord finders; the
+  # only difference is that we start with "paginate" instead of "find" and
+  # that <tt>:page</tt> is required parameter:
+  #
+  #   @posts = Post.paginate :all, :page => params[:page], :order => 'created_at DESC'
+  #
+  module ActiveRecord
+    # makes a Relation look like WillPaginate::Collection
+    module RelationMethods
+      include WillPaginate::CollectionMethods
+
+      attr_accessor :current_page
+      attr_writer :total_entries, :wp_count_options
+
+      def per_page(value = nil)
+        if value.nil? then limit_value
+        else limit(value)
+        end
+      end
+
+      # TODO: solve with less relation clones and code dups
+      def limit(num)
+        rel = super
+        if rel.current_page
+          rel.offset rel.current_page.to_offset(rel.limit_value).to_i
+        else
+          rel
+        end
+      end
+
+      def offset(value = nil)
+        if value.nil? then offset_value
+        else super(value)
+        end
+      end
+
+      def total_entries
+        @total_entries ||= begin
+          if loaded? and size < limit_value and (current_page == 1 or size > 0)
+            offset_value + size
+          else
+            @total_entries_queried = true
+            result = count
+            result = result.size if result.respond_to?(:size) and !result.is_a?(Integer)
+            result
+          end
+        end
+      end
+
+      def count
+        if limit_value
+          excluded = [:order, :limit, :offset]
+          excluded << :includes unless eager_loading?
+          rel = self.except(*excluded)
+          # TODO: hack. decide whether to keep
+          rel = rel.apply_finder_options(@wp_count_options) if defined? @wp_count_options
+          rel.count
+        else
+          super
+        end
+      end
+
+      # workaround for Active Record 3.0
+      def size
+        if !loaded? and limit_value and group_values.empty?
+          [super, limit_value].min
+        else
+          super
+        end
+      end
+
+      # overloaded to be pagination-aware
+      def empty?
+        if !loaded? and offset_value
+          result = count
+          result = result.size if result.respond_to?(:size) and !result.is_a?(Integer)
+          result <= offset_value
+        else
+          super
+        end
+      end
+
+      def clone
+        copy_will_paginate_data super
+      end
+
+      # workaround for Active Record 3.0
+      def scoped(options = nil)
+        copy_will_paginate_data super
+      end
+
+      def to_a
+        if current_page.nil? then super # workaround for Active Record 3.0
+        else
+          ::WillPaginate::Collection.create(current_page, limit_value) do |col|
+            col.replace super
+            col.total_entries ||= total_entries
+          end
+        end
+      end
+
+      private
+
+      def copy_will_paginate_data(other)
+        other.current_page = current_page unless other.current_page
+        other.total_entries = nil if defined? @total_entries_queried
+        other.wp_count_options = @wp_count_options if defined? @wp_count_options
+        other
+      end
+    end
+
+    module Pagination
+      def paginate(options)
+        options  = options.dup
+        pagenum  = options.fetch(:page) { raise ArgumentError, ":page parameter required" }
+        per_page = options.delete(:per_page) || self.per_page
+        total    = options.delete(:total_entries)
+
+        count_options = options.delete(:count)
+        options.delete(:page)
+
+        rel = limit(per_page.to_i).page(pagenum)
+        rel.wp_count_options = count_options    if count_options
+        rel.total_entries = total.to_i          unless total.blank?
+        rel
+      end
+
+      def page(num)
+        rel = self.extending(RelationMethods)
+        pagenum = ::WillPaginate::PageNumber(num.nil? ? 1 : num)
+        per_page = rel.limit_value || self.per_page
+        rel = rel.offset(pagenum.to_offset(per_page).to_i)
+        rel = rel.limit(per_page) unless rel.limit_value
+        rel.current_page = pagenum
+        rel
+      end
+    end
+
+    module BaseMethods
+      # Wraps +find_by_sql+ by simply adding LIMIT and OFFSET to your SQL string
+      # based on the params otherwise used by paginating finds: +page+ and
+      # +per_page+.
+      #
+      # Example:
+      # 
+      #   @developers = Developer.paginate_by_sql ['select * from developers where salary > ?', 80000],
+      #                          :page => params[:page], :per_page => 3
+      #
+      # A query for counting rows will automatically be generated if you don't
+      # supply <tt>:total_entries</tt>. If you experience problems with this
+      # generated SQL, you might want to perform the count manually in your
+      # application.
+      # 
+      def paginate_by_sql(sql, options)
+        pagenum  = options.fetch(:page) { raise ArgumentError, ":page parameter required" } || 1
+        per_page = options[:per_page] || self.per_page
+        total    = options[:total_entries]
+
+        WillPaginate::Collection.create(pagenum, per_page, total) do |pager|
+          query = sanitize_sql(sql.dup)
+          original_query = query.dup
+          oracle = self.connection.adapter_name =~ /^(oracle|oci$)/i
+
+          # add limit, offset
+          if oracle
+            query = <<-SQL
+              SELECT * FROM (
+                SELECT rownum rnum, a.* FROM (#{query}) a
+                WHERE rownum <= #{pager.offset + pager.per_page}
+              ) WHERE rnum >= #{pager.offset}
+            SQL
+          else
+            query << " LIMIT #{pager.per_page} OFFSET #{pager.offset}"
+          end
+
+          # perfom the find
+          pager.replace find_by_sql(query)
+
+          unless pager.total_entries
+            count_query = original_query.sub /\bORDER\s+BY\s+[\w`,\s.]+$/mi, ''
+            count_query = "SELECT COUNT(*) FROM (#{count_query})"
+            count_query << ' AS count_table' unless oracle
+            # perform the count query
+            pager.total_entries = count_by_sql(count_query)
+          end
+        end
+      end
+    end
+
+    # mix everything into Active Record
+    ::ActiveRecord::Base.extend PerPage
+    ::ActiveRecord::Base.extend Pagination
+    ::ActiveRecord::Base.extend BaseMethods
+
+    klasses = [::ActiveRecord::Relation]
+    if defined? ::ActiveRecord::Associations::CollectionProxy
+      klasses << ::ActiveRecord::Associations::CollectionProxy
+    else
+      klasses << ::ActiveRecord::Associations::AssociationCollection
+    end
+
+    # support pagination on associations and scopes
+    klasses.each { |klass| klass.send(:include, Pagination) }
+  end
+end

data/lib/will_paginate/array.rb

@@ -0,0 +1,57 @@
+require 'will_paginate/collection'
+
+class Array
+  # Paginates a static array (extracting a subset of it). The result is a
+  # WillPaginate::Collection instance, which is an array with a few more
+  # properties about its paginated state.
+  #
+  # Parameters:
+  # * <tt>:page</tt> - current page, defaults to 1
+  # * <tt>:per_page</tt> - limit of items per page, defaults to 30
+  # * <tt>:total_entries</tt> - total number of items in the array, defaults to
+  #   <tt>array.length</tt> (obviously)
+  #
+  # Example:
+  #   arr = ['a', 'b', 'c', 'd', 'e']
+  #   paged = arr.paginate(:per_page => 2)      #->  ['a', 'b']
+  #   paged.total_entries                       #->  5
+  #   arr.paginate(:page => 2, :per_page => 2)  #->  ['c', 'd']
+  #   arr.paginate(:page => 3, :per_page => 2)  #->  ['e']
+  #
+  # This method was originally {suggested by Desi
+  # McAdam}[http://www.desimcadam.com/archives/8] and later proved to be the
+  # most useful method of will_paginate library.
+  def paginate(options = {})
+    page     = options[:page] || 1
+    per_page = options[:per_page] || WillPaginate.per_page
+    total    = options[:total_entries] || self.length
+
+    WillPaginate::Collection.create(page, per_page, total) do |pager|
+      pager.replace self[pager.offset, pager.per_page].to_a
+    end
+  end
+
+  attr_accessor :member_class, :origin, :origin_attribute
+
+  # Hobo Extension
+  def to_url_path
+    base_path = origin.try.to_url_path
+    "#{base_path}/#{origin_attribute}" unless base_path.blank?
+  end
+
+  # Hobo Extension
+  def typed_id
+    origin and origin_id = origin.try.typed_id and "#{origin_id}:#{origin_attribute}"
+  end
+
+  # Hobo Extension
+  def paginate_with_hobo_metadata(*args, &block)
+    collection = paginate_without_hobo_metadata(*args, &block)
+    collection.member_class     = member_class
+    collection.origin           = try.proxy_owner
+    collection.origin_attribute = try.proxy_association._?.reflection._?.name
+    collection
+  end
+  alias_method_chain :paginate, :hobo_metadata
+
+end

data/lib/will_paginate/collection.rb

@@ -0,0 +1,149 @@
+require 'will_paginate/per_page'
+require 'will_paginate/page_number'
+
+module WillPaginate
+  # Any will_paginate-compatible collection should have these methods:
+  #
+  #   current_page, per_page, offset, total_entries, total_pages
+  #
+  # It can also define some of these optional methods:
+  #
+  #   out_of_bounds?, previous_page, next_page
+  #
+  # This module provides few of these methods.
+  module CollectionMethods
+    def total_pages
+      total_entries.zero? ? 1 : (total_entries / per_page.to_f).ceil
+    end
+
+    # current_page - 1 or nil if there is no previous page
+    def previous_page
+      current_page > 1 ? (current_page - 1) : nil
+    end
+
+    # current_page + 1 or nil if there is no next page
+    def next_page
+      current_page < total_pages ? (current_page + 1) : nil
+    end
+
+    # Helper method that is true when someone tries to fetch a page with a
+    # larger number than the last page. Can be used in combination with flashes
+    # and redirecting.
+    def out_of_bounds?
+      current_page > total_pages
+    end
+  end
+
+  # = The key to pagination
+  # Arrays returned from paginating finds are, in fact, instances of this little
+  # class. You may think of WillPaginate::Collection as an ordinary array with
+  # some extra properties. Those properties are used by view helpers to generate
+  # correct page links.
+  #
+  # WillPaginate::Collection also assists in rolling out your own pagination
+  # solutions: see +create+.
+  # 
+  # If you are writing a library that provides a collection which you would like
+  # to conform to this API, you don't have to copy these methods over; simply
+  # make your plugin/gem dependant on this library and do:
+  #
+  #   require 'will_paginate/collection'
+  #   # WillPaginate::Collection is now available for use
+  class Collection < Array
+    include CollectionMethods
+
+    attr_reader :current_page, :per_page, :total_entries
+
+    # Arguments to the constructor are the current page number, per-page limit
+    # and the total number of entries. The last argument is optional because it
+    # is best to do lazy counting; in other words, count *conditionally* after
+    # populating the collection using the +replace+ method.
+    def initialize(page, per_page = WillPaginate.per_page, total = nil)
+      @current_page = WillPaginate::PageNumber(page)
+      @per_page = per_page.to_i
+      self.total_entries = total if total
+    end
+
+    # Just like +new+, but yields the object after instantiation and returns it
+    # afterwards. This is very useful for manual pagination:
+    #
+    #   @entries = WillPaginate::Collection.create(1, 10) do |pager|
+    #     result = Post.find(:all, :limit => pager.per_page, :offset => pager.offset)
+    #     # inject the result array into the paginated collection:
+    #     pager.replace(result)
+    #
+    #     unless pager.total_entries
+    #       # the pager didn't manage to guess the total count, do it manually
+    #       pager.total_entries = Post.count
+    #     end
+    #   end
+    #
+    # The possibilities with this are endless. For another example, here is how
+    # WillPaginate used to define pagination for Array instances:
+    #
+    #   Array.class_eval do
+    #     def paginate(page = 1, per_page = 15)
+    #       WillPaginate::Collection.create(page, per_page, size) do |pager|
+    #         pager.replace self[pager.offset, pager.per_page].to_a
+    #       end
+    #     end
+    #   end
+    #
+    # The Array#paginate API has since then changed, but this still serves as a
+    # fine example of WillPaginate::Collection usage.
+    def self.create(page, per_page, total = nil)
+      pager = new(page, per_page, total)
+      yield pager
+      pager
+    end
+
+    # Current offset of the paginated collection. If we're on the first page,
+    # it is always 0. If we're on the 2nd page and there are 30 entries per page,
+    # the offset is 30. This property is useful if you want to render ordinals
+    # side by side with records in the view: simply start with offset + 1.
+    def offset
+      current_page.to_offset(per_page).to_i
+    end
+
+    def total_entries=(number)
+      @total_entries = number.to_i
+    end
+
+    # This is a magic wrapper for the original Array#replace method. It serves
+    # for populating the paginated collection after initialization.
+    #
+    # Why magic? Because it tries to guess the total number of entries judging
+    # by the size of given array. If it is shorter than +per_page+ limit, then we
+    # know we're on the last page. This trick is very useful for avoiding
+    # unnecessary hits to the database to do the counting after we fetched the
+    # data for the current page.
+    #
+    # However, after using +replace+ you should always test the value of
+    # +total_entries+ and set it to a proper value if it's +nil+. See the example
+    # in +create+.
+    def replace(array)
+      result = super
+
+      # The collection is shorter then page limit? Rejoice, because
+      # then we know that we are on the last page!
+      if total_entries.nil? and length < per_page and (current_page == 1 or length > 0)
+        self.total_entries = offset + length
+      end
+
+      result
+    end
+
+    attr_accessor :member_class, :origin, :origin_attribute
+
+    # Hobo extension:  make paginate_by_sql, etc. carry metadata
+    def replace_with_hobo_metadata(array)
+      result = replace_without_hobo_metadata(array)
+      self.member_class = array.try.member_class
+      self.origin = array.try.origin
+      self.origin_attribute = array.try.origin_attribute
+      result
+    end
+    alias_method_chain :replace, :hobo_metadata
+
+  end
+end