kaminari 0.12.4 → 0.13.0

data/.travis.yml

@@ -0,0 +1,6 @@
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - ruby-head
+
+script: bundle exec rake spec

data/CHANGELOG

@@ -1,3 +1,65 @@
+== 0.13.0
+
+* Rails 3.2 ready! #180 [slbug]
+
+* DataMapper support! #149 [NoICE, Ragmaanir]
+
+* Sinatra & Padrino support! #179 [udzura, mlightner, aereal]
+
+* Added mongoid embedded documents support! #155 [yuki24]
+
+* Added `each_relevant_page` that only visits pages in the inner or outer
+windows #154 [cbeer]
+  Performance improved, particularly with very large number of pages.
+
+* Memoize count for AR when calling `total_count` #138 [sarmiena]
+  Increases performance for large datasets.
+
+* Added `page_entries_info` view helper #140 [jeffreyiacono]
+  Example:
+  <%= page_entries_info @posts %>
+  #=> Displaying posts 6 - 10 of 26 in total
+
+* Added `link_to_next_page` helper method that simply links to the next page
+  Example:
+  <%= link_to_next_page @posts, 'More' %>
+	#=> <a href="/posts?page=7" rel="next">More</a>
+
+* Let one override the `rel` attribute for 'link_to_next_page` helper #177
+[webmat]
+
+* Added `total_count` param for PaginatableArray. Useful for when working with
+RSolr #141 [samdalton]
+
+* Changed `Kaminari.paginate_array` API to take a Hash `options`
+  And specifying :limit & :offset immediately builds a pagination ready object
+	Example:
+  # the following two are equivalent. Use whichever you like
+  Kaminari.paginate_array((1..100).to_a, limit: 10, offset: 10)
+  Kaminari.paginate_array((1..100).to_a).page(2).per(10)
+
+* Added `padding` method to skip an arbitrary record count #60 [aaronjensen]
+  Example:
+  User.page(2).per(10).padding(3)  # this will return users 14..23
+
+* Made the pagination method name (defaulted to `page`) configurable #57, #162
+  Example:
+  # you can use the config file and its generator for this
+	Kaminari.config.page_method_name = :paging
+	Article.paging(3).per(30)
+
+* Only add extensions to direct descendents of ActiveRecord::Base #108
+[seejohnrun]
+
+* AR models that were subclassed before Kaminari::ActiveRecordExtension is
+included pick up the extensions #119 [pivotal-casebook]
+
+* Avoid overwriting AR::Base inherited method #165 [briandmcnabb]
+
+* Stopped depending on Rails gem #159 [alsemyonov]
+
+* introduced Travis CI #181 [hsbt]
+
 == 0.12.4
 
 * Support for config.param_name as lambda #102 [ajrkerr]

data/README.rdoc

@@ -1,6 +1,6 @@
 = Kaminari
 
-A Scope & Engine based, clean, powerful, customizable and sophisticated paginator for Rails 3
+A Scope & Engine based, clean, powerful, customizable and sophisticated paginator for modern web app frameworks and ORMs
 
 
 == Features
@@ -19,7 +19,7 @@ No special collection class or anything for the paginated values, instead using
 As the whole pagination helper is basically just a collection of links and non-links, Kaminari renders each of them through its own partial template inside the Engine. So, you can easily modify their behaviour, style or whatever by overriding partial templates.
 
 === ORM & template engine agnostic
-Kaminari supports multiple ORMs (ActiveRecord, Mongoid, MongoMapper) and multiple template engines (ERB, Haml).
+Kaminari supports multiple ORMs (ActiveRecord, Mongoid, MongoMapper) multiple web frameworks (Rails, Sinatra), and multiple template engines (ERB, Haml).
 
 === Modern
 The pagination helper outputs the HTML5 <nav> tag by default. Plus, the helper supports Rails 3 unobtrusive Ajax.
@@ -27,15 +27,17 @@ The pagination helper outputs the HTML5 <nav> tag by default. Plus, the helper s
 
 == Supported versions
 
-* Ruby 1.8.7, 1.9.2, 1.9.3 (trunk)
+* Ruby 1.8.7, 1.9.2, 1.9.3, 2.0 (trunk)
 
-* Rails 3.0.x, 3.1 (edge)
+* Rails 3.0.x, 3.1, 3.2, 4.0 (edge)
 
-* Haml 3
+* Haml 3+
 
-* Mongoid 2
+* Mongoid 2+
 
-* MongoMapper 0.9
+* MongoMapper 0.9+
+
+* DataMapper 1.1.0+
 
 == Install
 
@@ -61,6 +63,12 @@ Then bundle:
     User.page(7).per(50)
   Note that the +per+ scope is not directly defined on the models but is just a method defined on the page scope. This is absolutely reasonable because you will never actually use +per_page+ without specifying the +page+ number.
 
+* the +padding+ scope
+
+  Occasionally you need to padding a number of records that is not a multiple of the page size.
+    User.page(7).per(50).padding(3)
+  Note that the +padding+ scope also is not directly defined on the models.
+
 === General configuration options
 
 You can configure the following default values by overriding these values using <tt>Kaminari.configure</tt> method.
@@ -69,11 +77,18 @@ You can configure the following default values by overriding these values using
   outer_window      # 0 by default
   left              # 0 by default
   right             # 0 by default
+  page_method_name  # :page by default
+  param_name        # :page by default
 
-There's a handy generator that generates the default configuration file into config/initilizers directory.
+There's a handy generator that generates the default configuration file into config/initializers directory.
 Run the following generator command, then edit the generated file.
   % rails g kaminari:config
 
+* changing +page_method_name+
+
+  You can change the method name `page` to `bonzo` or `plant` or whatever you like, in order to play nice with existing `page` method or association or scope or any other plugin that defines `page` method on your models.
+
+
 === Configuring default +per_page+ value for each model
 
 * +paginates_per+
@@ -99,7 +114,12 @@ Run the following generator command, then edit the generated file.
 
   This will render several <tt>?page=N</tt> pagination links surrounded by an HTML5 <+nav+> tag.
 
-=== Helper Options
+=== Helpers
+
+* the +paginate+ helper method
+
+    <%= paginate @users %>
+  This would output several pagination links such as <tt>« First ‹ Prev ... 2 3 4 5 6 7 8 9 10 ... Next › Last »</tt>
 
 * specifing the "inner window" size (4 by default)
 
@@ -131,16 +151,28 @@ Run the following generator command, then edit the generated file.
     <%= paginate @users, :remote => true %>
   This would add <tt>data-remote="true"</tt> to all the links inside.
 
+* the +link_to_next_page+ helper method
+
+    <%= link_to_next_page @items, 'Next Page' %>
+  This simply renders a link to the next page. This would be helpful for creating "Twitter like" pagination feature.
+
+* the +page_entries_info+ helper method
+
+    <%= page_entries_info @users %>
+  This renders a helpful message with numbers of displayed vs. total entries.
+
 === I18n and labels
 
-The default labels for 'previous', '...' and 'next' are stored in the I18n yaml inside the engine, and rendered through I18n API. You can switch the label value per I18n.locale for your internationalized application.
+The default labels for 'first', 'last', 'previous', '...' and 'next' are stored in the I18n yaml inside the engine, and rendered through I18n API. You can switch the label value per I18n.locale for your internationalized application.
 Keys and the default values are the following. You can override them by adding to a YAML file in your <tt>Rails.root/config/locales</tt> directory.
 
   en:
     views:
       pagination:
-        previous: "&laquo; Prev"
-        next: "Next &raquo;"
+        first: "&laquo; First"
+        last: "Last &raquo;"
+        previous: "&lsaquo; Prev"
+        next: "Next &rsaquo;"
         truncate: "..."
 
 === Customizing the pagination helper
@@ -191,10 +223,42 @@ Kaminari includes a handy template generator.
 === Paginating a generic Array object
 
 Kaminari provides an Array wrapper class that adapts a generic Array object to the <tt>paginate</tt> view helper.
-However, the <tt>paginate</tt> helper doesn't automatically handle your Array object (this is an intensional design).
+However, the <tt>paginate</tt> helper doesn't automatically handle your Array object (this is intentional and by design).
 <tt>Kaminari::paginate_array</tt> method converts your Array object into a paginatable Array that accepts <tt>page</tt> method.
   Kaminari.paginate_array(my_array_object).page(params[:page]).per(10)
 
+You can specify the `total_count` value through options Hash. This would be helpful when handling an Array-ish object that has a different `count` value from actual `count` such as RSolr search result.
+
+
+== Creating friendly URLs and caching
+
+Because of the `page` parameter and Rails 3 routing, you can easily generate SEO and user-friendly URLs. For any resource you'd like to paginate, just add the following to your `routes.rb`:
+
+    resources :my_resources do
+      get 'page/:page', :action => :index, :on => :collection
+    end
+
+This will create URLs like `/my_resources/page/33` instead of `/my_resources?page=33`. This is now a friendly URL, but it also has other added benefits...
+
+Because the `page` parameter is now a URL segment, we can leverage on Rails page caching[http://guides.rubyonrails.org/caching_with_rails.html#page-caching]!
+
+NOTE: In this example, I've pointed the route to my `:index` action. You may have defined a custom pagination action in your controller - you should point `:action => :your_custom_action` instead.
+
+
+== Sinatra/Padrino support
+
+Since version 0.13.0, kaminari started to support Sinatra or Sinatra-based frameworks experimentally.
+
+To use kaminari and its helpers with these frameworks,
+
+    require 'kaminari/sinatra'
+
+or edit gemfile:
+
+    gem 'kaminari', :require => 'kaminari/sinatra'
+
+More features are coming, and again, this is still experimental. Please let us know if you found anything wrong with the Sinatra support.
+
 
 == For more information
 
@@ -202,6 +266,9 @@ Check out Kaminari recipes on the GitHub Wiki for more advanced tips and techniq
 https://github.com/amatsuda/kaminari/wiki/Kaminari-recipes
 
 
+== Build Status {<img src="https://secure.travis-ci.org/amatsuda/kaminari.png"/>}[http://travis-ci.org/amatsuda/kaminari]
+
+
 == Questions, Feedback
 
 Feel free to message me on Github (amatsuda) or Twitter (@a_matsuda)  ☇☇☇  :)
@@ -214,4 +281,4 @@ Feel free to message me on Github (amatsuda) or Twitter (@a_matsuda)  ☇☇☇
 
 == Copyright
 
-Copyright (c) 2011 Akira Matsuda. See LICENSE.txt for further details.
+Copyright (c) 2011 Akira Matsuda. See MIT-LICENSE for further details.

data/kaminari.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ['Akira Matsuda']
   s.email       = ['ronnie@dio.jp']
   s.homepage    = 'https://github.com/amatsuda/kaminari'
-  s.summary     = 'A pagination engine plugin for Rails 3'
-  s.description = 'Kaminari is a Scope & Engine based, clean, powerful, customizable and sophisticated paginator for Rails 3'
+  s.summary     = 'A pagination engine plugin for Rails 3 or other modern frameworks'
+  s.description = 'Kaminari is a Scope & Engine based, clean, powerful, agnostic, customizable and sophisticated paginator for Rails 3'
 
   s.rubyforge_project = 'kaminari'
 
@@ -21,15 +21,28 @@ Gem::Specification.new do |s|
 
   s.licenses = ['MIT']
 
-  s.add_dependency 'rails', ['>= 3.0.0']
+  %w{ activesupport actionpack railties }.each do |gem|
+    s.add_dependency gem, ['>= 3.0.0']
+  end
   s.add_development_dependency 'bundler', ['>= 1.0.0']
   s.add_development_dependency 'sqlite3', ['>= 0']
+  %w{ activerecord activemodel }.each do |gem|
+    s.add_development_dependency gem, ['>= 3.0.0']
+  end
+  s.add_development_dependency 'sinatra', ['>= 1.3']
   s.add_development_dependency 'mongoid', ['>= 2']
   s.add_development_dependency 'mongo_mapper', ['>= 0.9']
+  s.add_development_dependency 'dm-core', ['>= 1.1.0']
+  s.add_development_dependency 'dm-migrations', ['>= 1.1.0']
+  s.add_development_dependency 'dm-aggregates', ['>= 1.1.0']
+  s.add_development_dependency 'dm-sqlite-adapter', ['>= 1.1.0']
   s.add_development_dependency 'rspec', ['>= 0']
   s.add_development_dependency 'rspec-rails', ['>= 0']
   s.add_development_dependency 'rr', ['>= 0']
-  s.add_development_dependency 'steak', ['>= 0']
-  s.add_development_dependency 'capybara', ['>= 0']
+  s.add_development_dependency 'capybara', ['>= 1.0']
   s.add_development_dependency 'database_cleaner', ['>= 0']
+  s.add_development_dependency 'padrino-helpers', ['~> 0.10']
+  s.add_development_dependency 'rack-test', ['>= 0']
+  s.add_development_dependency 'sinatra-contrib', ['~> 1.3']
+  s.add_development_dependency 'nokogiri', ['>= 0']
 end

data/lib/generators/kaminari/templates/kaminari_config.rb

@@ -4,5 +4,6 @@ Kaminari.configure do |config|
   # config.outer_window = 0
   # config.left = 0
   # config.right = 0
+  # config.page_method_name = :page
   # config.param_name = :page
 end

data/lib/generators/kaminari/views_generator.rb

@@ -6,7 +6,7 @@ module Kaminari
     class ViewsGenerator < Rails::Generators::NamedBase
       source_root File.expand_path('../../../../app/views/kaminari', __FILE__)
 
-      class_option :template_engine, :type => :string, :aliases => '-e', :desc => 'Template engine for the views. Available options are "erb" and "haml".'
+      class_option :template_engine, :type => :string, :aliases => '-e', :desc => 'Template engine for the views. Available options are "erb", "haml", and "slim".'
 
       def self.banner #:nodoc:
         <<-BANNER.chomp

data/lib/kaminari.rb

@@ -1,2 +1,73 @@
-require File.join(File.dirname(__FILE__), 'kaminari/railtie')
-require File.join(File.dirname(__FILE__), 'kaminari/engine')
+module Kaminari
+  def self.frameworks
+    frameworks = []
+    case
+      when rails?   then frameworks << 'rails'
+      when sinatra? then frameworks << 'sinatra/base'
+    end
+    frameworks
+  end
+
+  def self.load_framework!
+    show_warning if frameworks.empty?
+    frameworks.each do |framework|
+      begin
+        require framework
+      rescue NameError => e
+        raise "Failed to load framework #{framework.inspect}. Have you added it to Gemfile?"
+      end
+    end
+  end
+
+  def self.show_warning
+    $stderr.puts <<-EOC
+warning: no framework detected.
+would you check out if your Gemfile appropriately configured?
+---- e.g. ----
+when Rails:
+    gem 'rails'
+    gem 'kaminari'
+
+when Sinatra/Padrino:
+    gem 'kaminari', :require => 'kaminari/sinatra'
+
+    EOC
+  end
+
+  def self.load_kaminari!
+    require 'kaminari/config'
+    require 'kaminari/helpers/action_view_extension'
+    require 'kaminari/helpers/paginator'
+    require 'kaminari/models/page_scope_methods'
+    require 'kaminari/models/configuration_methods'
+  end
+
+  def self.hook!
+    load_framework!
+    load_kaminari!
+    require 'kaminari/hooks'
+    if rails?
+      require 'kaminari/railtie'
+      require 'kaminari/engine'
+    elsif sinatra?
+      require 'kaminari/sinatra'
+    else
+      Kaminari::Hooks.init!
+    end
+  end
+
+  def self.load!
+    hook!
+  end
+
+  private
+  def self.rails?
+    defined?(::Rails)
+  end
+
+  def self.sinatra?
+    defined?(::Sinatra)
+  end
+end
+
+Kaminari.load!

data/lib/kaminari/config.rb

@@ -22,10 +22,11 @@ module Kaminari
     config_accessor :outer_window
     config_accessor :left
     config_accessor :right
+    config_accessor :page_method_name
     config_accessor :param_name
 
     def param_name
-      config.param_name.respond_to?(:call) ? config.param_name.call() : config.param_name 
+      config.param_name.respond_to?(:call) ? config.param_name.call : config.param_name
     end
   end
 
@@ -36,6 +37,7 @@ module Kaminari
     config.outer_window = 0
     config.left = 0
     config.right = 0
+    config.page_method_name = :page
     config.param_name = :page
   end
 end

data/lib/kaminari/helpers/action_view_extension.rb

@@ -1,25 +1,79 @@
 module Kaminari
+  # = Helpers
   module ActionViewExtension
-    extend ActiveSupport::Concern
-    module InstanceMethods
-      # = Helpers
-      #
-      # A helper that renders the pagination links.
-      #
-      #   <%= paginate @articles %>
-      #
-      # ==== Options
-      # * <tt>:window</tt> - The "inner window" size (4 by default).
-      # * <tt>:outer_window</tt> - The "outer window" size (0 by default).
-      # * <tt>:left</tt> - The "left outer window" size (0 by default).
-      # * <tt>:right</tt> - The "right outer window" size (0 by default).
-      # * <tt>:params</tt> - url_for parameters for the links (:controller, :action, etc.)
-      # * <tt>:param_name</tt> - parameter name for page number in the links (:page by default)
-      # * <tt>:remote</tt> - Ajax? (false by default)
-      # * <tt>:ANY_OTHER_VALUES</tt> - Any other hash key & values would be directly passed into each tag as :locals value.
-      def paginate(scope, options = {}, &block)
-        paginator = Kaminari::Helpers::Paginator.new self, options.reverse_merge(:current_page => scope.current_page, :num_pages => scope.num_pages, :per_page => scope.limit_value, :param_name => Kaminari.config.param_name, :remote => false)
-        paginator.to_s
+    # A helper that renders the pagination links.
+    #
+    #   <%= paginate @articles %>
+    #
+    # ==== Options
+    # * <tt>:window</tt> - The "inner window" size (4 by default).
+    # * <tt>:outer_window</tt> - The "outer window" size (0 by default).
+    # * <tt>:left</tt> - The "left outer window" size (0 by default).
+    # * <tt>:right</tt> - The "right outer window" size (0 by default).
+    # * <tt>:params</tt> - url_for parameters for the links (:controller, :action, etc.)
+    # * <tt>:param_name</tt> - parameter name for page number in the links (:page by default)
+    # * <tt>:remote</tt> - Ajax? (false by default)
+    # * <tt>:ANY_OTHER_VALUES</tt> - Any other hash key & values would be directly passed into each tag as :locals value.
+    def paginate(scope, options = {}, &block)
+      paginator = Kaminari::Helpers::Paginator.new self, options.reverse_merge(:current_page => scope.current_page, :num_pages => scope.num_pages, :per_page => scope.limit_value, :param_name => Kaminari.config.param_name, :remote => false)
+      paginator.to_s
+    end
+
+    # A simple "Twitter like" pagination link that creates a link to the next page.
+    #
+    # ==== Examples
+    # Basic usage:
+    #
+    #   <%= link_to_next_page @items, 'Next Page' %>
+    #
+    # Ajax:
+    #
+    #   <%= link_to_next_page @items, 'Next Page', :remote => true %>
+    #
+    # By default, it renders nothing if there are no more results on the next page.
+    # You can customize this output by passing a block.
+    #
+    #   <%= link_to_next_page @users, 'Next Page' do %>
+    #     <span>No More Pages</span>
+    #   <% end %>
+    def link_to_next_page(scope, name, options = {}, &block)
+      params = options.delete(:params) || {}
+      param_name = options.delete(:param_name) || Kaminari.config.param_name
+      link_to_unless scope.last_page?, name, params.merge(param_name => (scope.current_page + 1)), options.reverse_merge(:rel => 'next') do
+        block.call if block
+      end
+    end
+
+    # Renders a helpful message with numbers of displayed vs. total entries.
+    # Ported from mislav/will_paginate
+    #
+    # ==== Examples
+    # Basic usage:
+    #
+    #   <%= 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 with the <tt>:entry_name</tt> parameter:
+    #
+    #   <%= page_entries_info @posts, :entry_name => 'item' %>
+    #   #-> Displaying items 6 - 10 of 26 in total
+    def page_entries_info(collection, options = {})
+      entry_name = options[:entry_name] || (collection.empty?? 'entry' : collection.first.class.name.underscore.sub('_', ' '))
+      if collection.num_pages < 2
+        case collection.total_count
+        when 0; "No #{entry_name.pluralize} found"
+        when 1; "Displaying <b>1</b> #{entry_name}"
+        else;   "Displaying <b>all #{collection.total_count}</b> #{entry_name.pluralize}"
+        end
+      else
+        offset = (collection.current_page - 1) * collection.limit_value
+        %{Displaying #{entry_name.pluralize} <b>%d&nbsp;-&nbsp;%d</b> of <b>%d</b> in total} % [
+          offset + 1,
+          offset + collection.count,
+          collection.total_count
+        ]
       end
     end
   end