pagination 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+/doc
+/.yardoc/

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Cyril David
+
+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,56 @@
+Pagination: Trying to make the pagination world a better place
+==============================================================
+
+Why another pagination library?
+-------------------------------
+
+Because I constantly work with designers, who prefer to have their own pagination markup customized to their heart's content. Current problems I have:
+
+1. It is very hard for me to change the markup with the current libraries out there.
+2. No Ohm / Redis support available (as far as I know).
+3. NIH? 
+
+Name the Niche:
+---------------
+
+This is currently streamlined for use with:
+
+1. Sinatra
+2. Ohm
+3. HAML
+
+How to use?
+-----------
+
+    require 'rubygems'
+    require 'sinatra'
+    require 'pagination'
+  
+    helpers Pagination::Helpers
+
+    get '/items' do
+      # Let's say current_user returns a User model with an items method
+
+      @items = paginate current_user.items, :page => params[:page]
+
+      haml :'items/index'
+    end
+
+    # then in your view index.haml
+
+    != pagination @items
+
+Customize the markup?
+---------------------
+
+    pagination haml
+    # Spits out the pagination haml markup that's being used
+
+    # Or if you prefer erb, you can also do that too...
+    pagination erb
+
+    # Then you can just use it as a partial
+    pagination haml > app/views/pagination.haml
+
+    # in your view
+    != partial :pagination, :items => @items

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "pagination"
+    gem.summary = %Q{A simplistic pagination library}
+    gem.description = %Q{Trying to make the pagination world a better place}
+    gem.email = "cyx.ucron@gmail.com"
+    gem.homepage = "http://github.com/sinefunc/pagination"
+    gem.authors = ["Cyril David"]
+    gem.add_development_dependency "contest"
+    gem.add_development_dependency "haml"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "pagination #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/pagination

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/pagination'
+
+if ['haml', 'erb'].include?(ARGV[0])
+  Pagination::Template.markup(ARGV[0])
+else
+  puts "Usage: pagination [erb|haml]"
+end

data/lib/pagination/adapters/ohm.rb

@@ -0,0 +1,29 @@
+module Pagination
+  class OhmAdapter < Collection
+    def initialize(dataset, options = {})
+      super
+
+      @dataset = dataset
+      @total   = dataset.size
+      @order   = options[:order]
+      @start   = (page - 1) * per_page
+    end
+
+  protected
+    def collection
+      if @dataset.respond_to?(:sort) 
+        @dataset.sort sort_options
+      else
+        @dataset.all @start, per_page
+      end
+    end
+
+    def sort_options
+      { :start => @start,
+        :limit => @per_page,
+        :order => 'DESC',
+        :by    => @order
+      }
+    end
+  end
+end

data/lib/pagination/collection.rb

@@ -0,0 +1,89 @@
+module Pagination
+  class Collection
+    Unimplemented = Class.new(StandardError)
+
+    include Enumerable
+
+    attr :page, :per_page, :total
+
+    # When subclassing `Pagination::Collection`, make sure you call super
+    # in order to use `page` and `per_page`.
+    def initialize(collection, options = {})
+      @page       = Integer(options[:page] || 1)
+      @per_page   = Integer(options[:per_page] || Pagination.per_page)
+    end
+
+    # When there's a valid previous page, returns that number
+    #
+    # Otherwise returns nil
+    #
+    def prev_page
+      page - 1  if pages.include?(page - 1)
+    end
+
+    # When there's a valid next page, returns that number
+    #
+    # Otherwise returns nil
+    def next_page
+      page + 1  if pages.include?(page + 1)
+    end
+  
+    # Mainly used as syntatic sugar instead of doing
+    #
+    #     if items.page == params[:page]
+    #
+    # for example, you will do
+    #
+    #     if items.current?(params[:page])
+    #
+    def current?(other_page)
+      page == other_page
+    end
+
+    # Provides dirt-simple logic for spitting out page numbers
+    # based on the current page.
+    #
+    # If we have 100 pages for example and we're at page 50,
+    # this would simple return 
+    #
+    #     [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]
+    #
+    # When we're at page 1, it displays 1 to 10.
+    #
+    # You can pass in a number to limit the total displayed pages.
+    # 1 2 3 4 5
+    def displayed_pages(limit = 10)
+      lower = [page, [pages.last - limit, 0].max + 1].min
+      upper = [page + limit - 1, pages.last].min
+
+      (lower..upper).to_a
+    end
+  
+    # Mainly used in the presentation layer as a front-line check if 
+    # we should even proceed with all the nitty-gritty details of rendering.
+    #
+    # This basically returns false when there's only 1 page for the given
+    # collection, otherwise returns true.
+    def render?
+      pages.to_a.size > 1
+    end
+
+    def each(&block)
+      collection.each(&block) 
+    end
+
+  protected
+    def collection
+      raise Unimplemented, "You must implement collection"  
+    end
+
+    def pages
+      1..last_page
+    end
+
+    def last_page
+      (total / per_page.to_f).ceil
+    end
+
+  end
+end

data/lib/pagination/helpers.rb

@@ -0,0 +1,43 @@
+module Pagination
+  # This module is mostly intended for use with Sinatra.
+  # 
+  # The classic sinatra application follows:
+  #
+  #     require 'rubygems'
+  #     require 'sinatra'
+  #     require 'pagination'
+  #
+  #     helpers Pagination::Helpers
+  #
+  #     get '/items' do
+  #       @items = paginate current_user.items, :page => params[:page]
+  #     end
+  #
+  # and then in your view
+  #
+  #     = pagination @items
+  #
+  module Helpers
+    # This method accepts a dataset which depends entirely on your current adapter.
+    # By default the `Pagination::OhmAdapter` is used, which assumes you are
+    # passing in sets.
+    #
+    # There's nothing stopping you from building your own adapter.
+    # See Pagination::OhmAdapter for details.
+    def paginate(dataset, options = {})
+      Pagination.paginate(dataset, options) 
+    end
+  
+    # As of now this displays a canned markup. The best way to actually customize 
+    # the markup is to use a partial and just pass in the collection as a local i.e.
+    #
+    #     partial :pagination, :items => @items
+    #
+    # The actual templates used are in `views/paginate.haml` and `views/paginate.erb`
+    def pagination(paginated_collection)
+      Pagination::Template.new(paginated_collection).render 
+    end
+  end
+end
+
+

data/lib/pagination/template.rb

@@ -0,0 +1,72 @@
+module Pagination
+  # This class can be used by itself, although there's a `Pagination::Helper` 
+  # available to provide convenience methods at your disposal.
+  #
+  # Basic Usage:
+  #
+  #     collection = Pagination.paginate(dataset, :page => 1)
+  #     Pagination::Template.new(collection).render
+  #
+  class Template
+    ROOT = File.join(File.dirname(__FILE__), '..', '..', 'views')
+    
+    attr :items
+  
+    # Initialize with your paginated collection.
+    #
+    # == Paramaters:
+    # items::
+    #   a `Pagination::Collection` object return by `Pagination.paginate`.
+    def initialize(items)
+      @items = items
+    end
+  
+    # Displayed the standard pagination markup as provided by the
+    # `Pagination` library.
+    #
+    # This uses Haml if Haml is required already. Else it uses ERB.
+    #
+    # == Returns:
+    # The actual HTML for the pagination.
+    def render
+      if engine.respond_to?(:render)
+        engine.render(Object.new, :items => items)
+      else
+        engine.result(binding)
+      end
+    end
+  
+    # This is used by the command line tool to spit out the markup.
+    #
+    # == Parameters:
+    # type::
+    #   either 'haml' or 'erb'
+    #
+    # == Returns:
+    # The actual markup source.
+    def self.markup(type)
+      puts __send__(type)
+    end
+  
+  protected
+    def self.haml
+      File.read(File.join(ROOT, 'paginate.haml'))
+    end
+
+    def self.erb
+      File.read(File.join(ROOT, 'paginate.erb'))
+    end
+
+  private
+    def engine
+      @engine ||= 
+        if defined?(Haml)
+          Haml::Engine.new(self.class.haml)
+        else
+          require 'erb' if not defined?(ERB)
+          ERB.new(self.class.erb)
+        end
+    end
+
+  end
+end

data/lib/pagination.rb

@@ -0,0 +1,39 @@
+module Pagination
+  autoload :OhmAdapter, 'pagination/adapters/ohm'
+  autoload :Collection, 'pagination/collection'
+  autoload :Template,   'pagination/template'
+
+  extend self
+
+  def paginate(collection, options = {})
+    adapter.new(collection, options)
+  end
+
+  def per_page(per_page = nil)
+    @per_page = per_page if per_page
+    @per_page
+  end
+
+  def adapter(adapter = nil)
+    if adapter
+      @adapter = adapter 
+    else
+      const_get(@adapter) if @adapter
+    end
+  end
+
+  # Set the default to 15
+  # You can easily override this by putting the following somewhere in your code:
+  #     Pagination.per_page 10
+  #
+  per_page 15
+
+  # Currently we default to Ohm for various reasons.
+  #
+  # If you want to make your own adapter, simply subclass Pagination::Collection
+  # and use `OhmAdapter` as the basis to determine the requirements needed.
+  #
+  # Make sure you put your Adapter under the `Pagination` module 
+  # (i.e. Pagination::MongoAdapter).
+  adapter  :OhmAdapter
+end

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'contest'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'pagination'
+
+class Test::Unit::TestCase
+end

data/test/test_pagination.rb

@@ -0,0 +1,112 @@
+require 'helper'
+
+class TestPagination < Test::Unit::TestCase
+  should "respond to #paginate" do
+    assert_respond_to Pagination, :paginate
+  end
+  
+  context "since we're assume OhmAdapter by default" do
+    should "at minimum accept a collection" do
+      assert_nothing_raised do
+        Pagination.paginate([])
+      end
+    end
+  end
+
+  context "given an empty collection" do
+    setup do
+      @collection = Pagination.paginate([])
+    end
+
+    should "default to page 1" do
+      assert_equal 1, @collection.page 
+    end
+
+    should "be current?(1)" do
+      assert @collection.current?(1)
+    end
+
+    should "default to 15 per page" do
+      assert_equal 15, @collection.per_page
+    end
+
+    should "have no prev page sinced it's page 1" do
+      assert_nil @collection.prev_page
+    end
+
+    should "have no next page since the collection passed was empty" do
+      assert_nil @collection.next_page
+    end
+
+    should "not render" do
+      assert ! @collection.render?
+    end
+  end
+
+  context "given 2 items, page 1, per_page 1" do
+    setup do
+      @collection = Pagination.paginate(['first', 'second'], :per_page => 1)
+    end
+    
+    should "have no prev page" do
+      assert_nil @collection.prev_page
+    end
+
+    should "have a next page of 2" do
+      assert_equal 2, @collection.next_page
+    end
+
+    context 'when we set page to 2' do
+      setup do
+        @collection = Pagination.paginate(['f', 's'], :page => 2, :per_page => 1)
+      end
+      
+      should "have a prev page of 1" do
+        assert_equal 1, @collection.prev_page
+      end
+
+      should "have no next page" do
+        assert_nil @collection.next_page
+      end
+    end
+  end
+  
+  context "given we have 100 pages and we're at page 1" do
+    setup do
+      @collection = Pagination.paginate((1..100).to_a, :per_page => 1)
+    end
+    
+    should "have 1 to 10 of displayed_pages" do
+      assert_equal (1..10).to_a, @collection.displayed_pages
+    end
+  end
+
+  context "given we have 100 pages and we're at page 50" do
+    setup do
+      @collection = Pagination.paginate((1..100).to_a, :per_page => 1, :page => 50)
+    end
+    
+    should "have 50 to 59 of displayed_pages" do
+      assert_equal (50..59).to_a, @collection.displayed_pages
+    end
+  end
+
+  context "given we have 100 pages and we're at pages 91 up to 99" do
+    should "start with the 91 end with 100" do
+      (91..99).each do |p|
+        collection = Pagination.paginate((1..100).to_a, :per_page => 1, :page => p)
+        assert_equal (91..100).to_a, collection.displayed_pages
+      end
+    end
+  end
+  
+  context "given we have 5 pages and we're at page 2 up to 5" do
+    should "always display the 5 pages" do
+      (1..5).each do |p|
+        collection = Pagination.paginate((1..100).to_a, :per_page => 20, :page => p)
+        assert_equal (1..5).to_a, collection.displayed_pages
+      end
+
+    end
+  end
+end

data/test/test_pagination_template.rb

@@ -0,0 +1,75 @@
+require 'helper'
+require 'nokogiri'
+require 'haml'
+
+HamlHere = Haml
+
+class TestPaginationTemplate < Test::Unit::TestCase
+  setup do
+    @dataset = ['one', 'two', 'three', 'four', 'five']
+    @items = Pagination.paginate(@dataset, :per_page => 1, :page => 1)
+  end
+  
+  describe "haml rendering option" do
+    setup do
+      Object.const_set(:Haml, HamlHere) unless defined?(Haml)
+      @render = lambda { Pagination::Template.new(@items).render }
+    end
+    
+    def doc
+      Nokogiri(@render.call)
+    end
+
+    should "be able to render using haml" do
+      assert_nothing_raised do
+        @render.call
+      end
+    end
+
+    should "have a ul > li.prev-link.disabled" do
+      assert_equal 1, 
+        doc.search('ul.pagination > li.prev-link.disabled > a').length
+    end
+
+    should "have a ul > li.next-link with page=2" do
+      assert_equal 1, 
+        doc.search('ul.pagination > li.next-link > a[href="?page=2"]').length
+    end
+
+    should "display the first page as the curretn page" do
+      assert_equal 1, 
+        doc.search('ul.pagination > li > ul.page-numbers > li > span').length
+
+      assert_equal '1', 
+        doc.search('ul.pagination > li > ul.page-numbers > li > span').text
+    end
+
+    should "display pages 2 to 5 as links" do
+      (2..5).each do |page|
+        assert_equal 1, 
+          doc.search(%(ul.pagination > li > 
+                       ul.page-numbers > li > a[href="?page=#{page}"])).length
+
+        assert_equal page.to_s, 
+          doc.search(%(ul.pagination > li > 
+                       ul.page-numbers > li > a[href="?page=#{page}"])).text
+      end
+    end
+  end
+
+  describe "erb rendering option" do
+    setup do
+      Object.send :remove_const, :Haml
+    end
+  
+    should "render without any errors" do
+      template = Pagination::Template.new(@items)
+      assert_kind_of ERB, template.send(:engine)
+
+      assert_nothing_raised do
+        template.render
+      end
+    end
+  end
+end
+

data/views/paginate.erb

@@ -0,0 +1,35 @@
+<ul class="pagination">
+  <% if items.prev_page %>
+    <li class="prev-link">
+      <a href='<%= "?page=%s" % items.prev_page %>'>&laquo; Prev</a>
+    </li>
+  <% else %>
+    <li class="prev-link disabled">
+      <span>&laquo; Prev</span>
+    </li>
+  <% end %>
+
+  <li>
+    <ul class="page-numbers">
+      <% items.displayed_pages.each do |page| %>
+        <li>
+          <% if items.current?(page) %>
+            <span><%= page %></span>
+          <% else %>
+            <a href='<%= "?page=%s" % page %>'><%= page %></a>
+          <% end %>
+        </li>
+      <% end %>
+    </ul>
+  </li>
+
+  <% if items.next_page %>
+    <li class="next-link">
+      <a href='<%= "?page=%s" % items.next_page %>'>Next &raquo;</a>
+    </li>
+  <% else %>
+    <li class="next-link disabled">
+      <span>Next &raquo;</span>
+    </li>
+  <% end %>
+</ul>

data/views/paginate.haml

@@ -0,0 +1,23 @@
+%ul.notList.pagination
+  - if items.prev_page
+    %li.prev-link
+      %a{:href => ("?page=%s" % items.prev_page)} « Prev
+  - else
+    %li.prev-link.disabled
+      %a(href='javascript:;') « Prev
+
+  %li
+    %ul.notList.page-numbers
+      - items.displayed_pages.each do |page|
+        %li
+          - if items.current?(page)
+            %span= page
+          - else
+            %a{:href => ("?page=%s" % page)}= page
+
+  - if items.next_page
+    %li.next-link
+      %a{:href => ("?page=%s" % items.next_page)} Next »
+  - else
+    %li.next-link.disabled
+      %a(href='javascript:;') Next »

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification 
+name: pagination
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Cyril David
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-25 00:00:00 +08:00
+default_executable: pagination
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: contest
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: haml
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Trying to make the pagination world a better place
+email: cyx.ucron@gmail.com
+executables: 
+- pagination
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- bin/pagination
+- lib/pagination.rb
+- lib/pagination/adapters/ohm.rb
+- lib/pagination/collection.rb
+- lib/pagination/helpers.rb
+- lib/pagination/template.rb
+- test/helper.rb
+- test/test_pagination.rb
+- test/test_pagination_template.rb
+- views/paginate.erb
+- views/paginate.haml
+has_rdoc: true
+homepage: http://github.com/sinefunc/pagination
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A simplistic pagination library
+test_files: 
+- test/helper.rb
+- test/test_pagination.rb
+- test/test_pagination_template.rb