will_paginate 2.1.0

data/CHANGELOG

@@ -0,0 +1,3 @@
+== 2.1.0 2008-01-20
+
+* created a gem version from Rails plugin

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2008 PJ Hyett and 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/Manifest.txt

@@ -0,0 +1,34 @@
+CHANGELOG
+LICENSE
+Manifest.txt
+README
+Rakefile
+config/release.rb
+lib/will_paginate.rb
+lib/will_paginate/collection.rb
+lib/will_paginate/core_ext.rb
+lib/will_paginate/finder.rb
+lib/will_paginate/version.rb
+lib/will_paginate/view_helpers.rb
+setup.rb
+test/array_pagination_test.rb
+test/boot.rb
+test/console
+test/finder_test.rb
+test/fixtures/admin.rb
+test/fixtures/developer.rb
+test/fixtures/developers_projects.yml
+test/fixtures/project.rb
+test/fixtures/projects.yml
+test/fixtures/replies.yml
+test/fixtures/reply.rb
+test/fixtures/schema.rb
+test/fixtures/topic.rb
+test/fixtures/topics.yml
+test/fixtures/user.rb
+test/fixtures/users.yml
+test/helper.rb
+test/lib/activerecord_test_case.rb
+test/lib/activerecord_test_connector.rb
+test/lib/load_fixtures.rb
+test/pagination_test.rb

data/README

@@ -0,0 +1,152 @@
+= WillPaginate
+
+Pagination is just limiting the number of records displayed. Why should you let
+it get in your way while developing, then? This plugin makes magic happen. Did
+you ever want to be able to do just this on a model:
+
+  Post.paginate :page => 1, :order => 'created_at DESC'
+
+... and then render the page links with a single view helper? Well, now you
+can.
+
+Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51],
+check it out.
+
+Your mind reels with questions? Join our Google
+group[http://groups.google.com/group/will_paginate].
+
+You can find more documentation on the wiki[http://github.com/mislav/will_paginate/wikis].
+
+== Example usage
+
+Use a paginate finder in the controller:
+
+    @posts = Post.paginate_by_board_id @board.id, :page => params[:page], :order => 'updated_at DESC'
+
+Yeah, +paginate+ works just like +find+ -- it just doesn't fetch all the
+records.  Don't forget to tell it which page you want, or it will complain!
+Read more on WillPaginate::Finder::ClassMethods.
+
+Render the posts in your view like you would normally do. When you need to render
+pagination, just stick this in:
+
+    <%= will_paginate @posts %>
+
+You're done. (Copy and paste the example fancy CSS styles from the bottom.) You
+can find the option list at WillPaginate::ViewHelpers.
+
+How does it know how much items to fetch per page? It asks your model by calling
+its <tt>per_page</tt> class method. You can define it like this:
+
+    class Post < ActiveRecord::Base
+      cattr_reader :per_page
+      @@per_page = 50
+    end
+
+... or like this:
+
+    class Post < ActiveRecord::Base
+      def self.per_page
+        50
+      end
+    end
+
+... or don't worry about it at all. WillPaginate defines it to be <b>30</b> by default.
+But you can always specify the count explicitly when calling +paginate+:
+
+    @posts = Post.paginate :page => params[:page], :per_page => 50
+
+The +paginate+ finder wraps the original finder and returns your resultset that now has
+some new properties. You can use the collection as you would with any ActiveRecord
+resultset. WillPaginate view helpers also need that object to be able to render pagination:
+
+    <ol>
+      <% for post in @posts -%>
+        <li>Render `post` in some nice way.</li>
+      <% end -%>
+    </ol>
+
+    <p>Now let's render us some pagination!</p>
+    <%= will_paginate @posts %>
+
+More detailed documentation:
+
+* WillPaginate::Finder::ClassMethods for pagination on your models;
+* WillPaginate::ViewHelpers for your views.
+
+== Oh noes, a bug!
+
+Tell us what happened so we can fix it, quick! Issues are filed on the Lighthouse project:
+http://err.lighthouseapp.com/projects/466-plugins/tickets?q=tagged:will_paginate
+
+Steps to make an awesome bug report:
+
+1. Run <tt>rake test</tt> in the <i>will_paginate</i> directory. (You will need SQLite3.)
+   Copy the output if there are failing tests.
+2. Register on Lighthouse to create a new ticket.
+3. Write a descriptive, short title. Provide as much info as you can in the body.
+   Assign the ticket to Mislav and tag it with meaningful tags, <tt>"will_paginate"</tt>
+   being among them.
+4. Yay! You will be notified on updates automatically.
+
+Here is an example of a great bug report and patch:
+http://err.lighthouseapp.com/projects/466/tickets/172-total_entries-ignored-in-paginate_by_sql
+
+== Authors, credits, contact
+
+Want to discuss, request features, ask questions? Join the Google group:
+http://groups.google.com/group/will_paginate
+
+Authors::                Mislav Marohnić, PJ Hyett
+Original announcement::  http://errtheblog.com/post/929 
+Original PHP source::    http://www.strangerstudios.com/sandbox/pagination/diggstyle.php
+
+All these people helped making will_paginate what it is now with their code
+contributions or simply awesome ideas:
+
+Chris Wanstrath, Dr. Nic Williams, K. Adam Christensen, Mike Garey, Bence
+Golda, Matt Aimonetti, Charles Brian Quinn, Desi McAdam, James Coglan, Matijs
+van Zuijlen, Maria, Brendan Ribera, Todd Willey, Bryan Helmkamp, Jan Berkel.
+
+== Usable pagination in the UI
+
+Copy the following CSS into your stylesheet for a good start:
+
+  .pagination {
+    padding: 3px;
+    margin: 3px;
+  }
+  .pagination a {
+    padding: 2px 5px 2px 5px;
+    margin: 2px;
+    border: 1px solid #aaaadd;
+    text-decoration: none;
+    color: #000099;
+  }
+  .pagination a:hover, .pagination a:active {
+    border: 1px solid #000099;
+    color: #000;
+  }
+  .pagination span.current {
+    padding: 2px 5px 2px 5px;
+    margin: 2px;
+    border: 1px solid #000099;
+    font-weight: bold;
+    background-color: #000099;
+    color: #FFF;
+  }
+  .pagination span.disabled {
+    padding: 2px 5px 2px 5px;
+    margin: 2px;
+    border: 1px solid #eee;
+    color: #ddd;
+  }
+
+More reading about pagination as design pattern:
+
+* Pagination 101:
+  http://kurafire.net/log/archive/2007/06/22/pagination-101
+* Pagination gallery:
+  http://www.smashingmagazine.com/2007/11/16/pagination-gallery-examples-and-good-practices/
+* Pagination on Yahoo Design Pattern Library:
+  http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination

data/Rakefile

@@ -0,0 +1,65 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'config/release'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the will_paginate plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+# I want to specify environment variables at call time
+class EnvTestTask < Rake::TestTask
+  attr_accessor :env
+
+  def ruby(*args)
+    env.each { |key, value| ENV[key] = value } if env
+    super
+    env.keys.each { |key| ENV.delete key } if env
+  end
+end
+
+for configuration in %w( sqlite3 mysql postgres )
+  EnvTestTask.new("test_#{configuration}") do |t|
+    t.pattern = 'test/finder_test.rb'
+    t.verbose = true
+    t.env = { 'DB' => configuration }
+  end
+end
+
+task :test_databases => %w(test_mysql test_sqlite3 test_postgres)
+
+desc %{Test everything on SQLite3, MySQL and PostgreSQL}
+task :test_full => %w(test test_mysql test_postgres)
+
+desc %{Test everything with Rails 1.2.x and 2.0.x gems}
+task :test_all do
+  all = Rake::Task['test_full']
+  ENV['RAILS_VERSION'] = '~>1.2.6'
+  all.invoke 
+  # reset the invoked flag
+  %w( test_full test test_mysql test_postgres ).each do |name|
+    Rake::Task[name].instance_variable_set '@already_invoked', false
+  end
+  # do it again
+  ENV['RAILS_VERSION'] = '~>2.0.2'
+  all.invoke 
+end
+
+desc 'Generate RDoc documentation for the will_paginate plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  files = ['README', 'LICENSE', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README" # page to start on
+  rdoc.title = "will_paginate"
+  
+  templates = %w[/Users/chris/ruby/projects/err/rock/template.rb /var/www/rock/template.rb]
+  rdoc.template = templates.find { |t| File.exists? t }
+  
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--inline-source'
+  rdoc.options << '--charset=UTF-8'
+end

data/config/release.rb

@@ -0,0 +1,82 @@
+require 'rubyforge'
+require 'rake/gempackagetask'
+require 'lib/will_paginate/version.rb'
+
+RUBYFORGE_NAME = 'will-paginate'
+NAME = 'will_paginate'
+version = WillPaginate::VERSION::STRING
+
+DESCRIPTION = <<-DESC
+  A Rails plugin that provides pagination solutions
+  for querying models and rendering pagination links in views.
+DESC
+DESCRIPTION.strip!.gsub! /\s+/, ' '
+
+changes = nil
+
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.version = version
+  s.summary = s.description = DESCRIPTION
+  s.authors = ['Mislav Marohnić', 'PJ Hyett']
+  s.email = 'mislav.marohnic@gmail.com'
+  s.homepage = 'http://github.com/mislav/will_paginate/wikis'
+  s.rubyforge_project = RUBYFORGE_NAME
+
+  s.add_dependency 'activesupport', '>=1.4.4'
+
+  s.files = File.read("Manifest.txt").split("\n")
+  s.executables = s.files.grep(/^bin/) { |f| File.basename(f) }
+
+  s.bindir = "bin"
+  dirs = Dir['{lib,ext}']
+  s.require_paths = dirs unless dirs.empty?
+
+  s.rdoc_options = ['--main', 'README', '--inline-source', '--charset=UTF-8']
+  s.extra_rdoc_files = %w(README LICENSE) # + s.files.grep(/\.txt$/) - %w(Manifest.txt)
+  s.has_rdoc = true
+end
+
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = false
+  pkg.need_zip = false
+end
+
+desc 'Package and upload the release to rubyforge.'
+task :release => [:clean, :package] do |t|
+  v = ENV["VERSION"] or abort "Must supply VERSION=x.y.z"
+  abort "Version doesn't match #{version}" if v != version
+  files = Dir["pkg/#{NAME}-#{version}.*"]
+
+  rf = RubyForge.new
+  puts "Logging in to RubyForge"
+  rf.login
+
+  c = rf.userconfig
+  c["release_notes"] = DESCRIPTION
+  c["release_changes"] = changes if changes
+  c["preformatted"] = true
+
+  puts "Releasing #{NAME} v. #{version}"
+  p files
+  rf.add_release RUBYFORGE_NAME, RUBYFORGE_NAME, version, *files
+end
+
+task :clean => [ :clobber_rdoc, :clobber_package ] do
+  removed = []
+  %w(diff diff.txt email.txt ri *.gem **/*~ **/.DS_Store).each do |pattern|
+    files = Dir[pattern]
+    next if files.empty?
+    FileUtils.rm_rf files
+    removed.concat files
+  end
+  puts "Removed files: #{removed.inspect}" unless removed.empty?
+end
+
+# desc 'Upload website files to rubyforge'
+# task :website_upload do
+#   host = "#{rubyforge_username}@rubyforge.org"
+#   remote_dir = "/var/www/gforge-projects/#{PATH}/"
+#   local_dir = 'website'
+#   sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+# end

data/lib/will_paginate/collection.rb

@@ -0,0 +1,132 @@
+require 'will_paginate'
+
+module WillPaginate
+  # = OMG, invalid page number!
+  # This is an ArgumentError raised in case a page was requested that is either
+  # zero or negative number. You should decide how do deal with such errors in
+  # the controller.
+  #
+  # This error is *not* raised when a page further than the last page is
+  # requested. Use <tt>WillPaginate::Collection#out_of_bounds?</tt> method to
+  # check for those cases and manually deal with them as you see fit.
+  class InvalidPage < ArgumentError
+    def initialize(page, page_num)
+      super "#{page.inspect} given as value, which translates to '#{page_num}' as page number"
+    end
+  end
+  
+  # Arrays returned from paginating finds are, in fact, instances of this.
+  # 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+.
+  #
+  class Collection < Array
+    attr_reader :current_page, :per_page, :total_entries
+
+    # Arguments to this 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, total = nil)
+      @current_page = page.to_i
+      raise InvalidPage.new(page, @current_page) if @current_page < 1
+      @per_page     = per_page.to_i
+      raise ArgumentError, "`per_page` setting cannot be less than 1 (#{@per_page} given)" if @per_page < 1
+      
+      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
+    #
+    def self.create(page, per_page, total = nil, &block)
+      pager = new(page, per_page, total)
+      yield pager
+      pager
+    end
+
+    # The total number of pages.
+    def page_count
+      @total_pages
+    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 > page_count
+    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
+    # besides your records: simply start with offset + 1.
+    #
+    def offset
+      (current_page - 1) * per_page
+    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 < page_count ? (current_page + 1) : nil
+    end
+
+    def total_entries=(number)
+      @total_entries = number.to_i
+      @total_pages   = (@total_entries / per_page.to_f).ceil
+    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)
+      returning super do
+        # 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 > 0 and length < per_page
+          self.total_entries = offset + length
+        end
+      end
+    end
+  end
+end

data/lib/will_paginate/core_ext.rb

@@ -0,0 +1,80 @@
+require 'will_paginate'
+require 'set'
+
+unless Hash.instance_methods.include? 'except'
+  Hash.class_eval do
+    # Returns a new hash without the given keys.
+    def except(*keys)
+      rejected = Set.new(respond_to?(:convert_key) ? keys.map { |key| convert_key(key) } : keys)
+      reject { |key,| rejected.include?(key) }
+    end
+ 
+    # Replaces the hash without only the given keys.
+    def except!(*keys)
+      replace(except(*keys))
+    end
+  end
+end
+
+unless Hash.instance_methods.include? 'slice'
+  Hash.class_eval do
+    # Returns a new hash with only the given keys.
+    def slice(*keys)
+      allowed = Set.new(respond_to?(:convert_key) ? keys.map { |key| convert_key(key) } : keys)
+      reject { |key,| !allowed.include?(key) }
+    end
+
+    # Replaces the hash with only the given keys.
+    def slice!(*keys)
+      replace(slice(*keys))
+    end
+  end
+end
+
+unless Hash.instance_methods.include? 'rec_merge!'
+  Hash.class_eval do
+    # Same as Hash#merge!, but recursively merges sub-hashes
+    # (stolen from Haml)
+    def rec_merge!(other)
+      other.each do |key, other_value|
+        value = self[key]
+        if value.is_a?(Hash) and other_value.is_a?(Hash)
+          value.rec_merge! other_value
+        else
+          self[key] = other_value
+        end
+      end
+      self
+    end
+  end
+end
+
+require 'will_paginate/collection'
+
+unless Array.instance_methods.include? 'paginate'
+  # http://www.desimcadam.com/archives/8
+  Array.class_eval do
+    def paginate(options_or_page = {}, per_page = nil)
+      if options_or_page.nil? or Fixnum === options_or_page
+        if defined? WillPaginate::Deprecation
+          WillPaginate::Deprecation.warn <<-DEPR
+            Array#paginate now conforms to the main, ActiveRecord::Base#paginate API.  You should \
+            call it with a parameters hash (:page, :per_page).  The old API (numbers as arguments) \
+            has been deprecated and is going to be unsupported in future versions of will_paginate.
+          DEPR
+        end
+        page = options_or_page
+        options = {}
+      else
+        options = options_or_page
+        page = options[:page]
+        raise ArgumentError, "wrong number of arguments (1 hash or 2 Fixnums expected)" if per_page
+        per_page = options[:per_page]
+      end
+
+      WillPaginate::Collection.create(page || 1, per_page || 30, options[:total_entries] || size) do |pager|
+        pager.replace self[pager.offset, pager.per_page].to_a
+      end
+    end
+  end
+end