<commit_before>= Kaminari {<img src="https://travis-ci.org/amatsuda/kaminari.svg"/>}[http://travis-ci.org/amatsuda/kaminari] {<img src="https://img.shields.io/codeclimate/github/amatsuda/kaminari.svg" />}[https://codeclimate.com/github/amatsuda/kaminari] {<img src="http://inch-ci.org/github/amatsuda/kaminari.svg" alt="Inline docs" />}[http://inch-ci.org/github/amatsuda/kaminari]

A Scope & Engine based, clean, powerful, customizable and sophisticated paginator for modern web app frameworks and ORMs


== Features

=== Clean
Does not globally pollute +Array+, +Hash+, +Object+ or <tt>AR::Base</tt>.

=== Easy to use
Just bundle the gem, then your models are ready to be paginated. No configuration required. Don't have to define anything in your models or helpers.

=== Simple scope-based API
Everything is method chainable with less "Hasheritis". You know, that's the Rails 3 way.
No special collection class or anything for the paginated values, instead using a general <tt>AR::Relation</tt> instance. So, of course you can chain any other conditions before or after the paginator scope.

=== Customizable engine-based I18n-aware helper
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) multiple web frameworks (Rails, Sinatra, Grape), and multiple template engines (ERB, Haml, Slim).

=== Modern
The pagination helper outputs the HTML5 <nav> tag by default. Plus, the helper supports Rails 3 unobtrusive Ajax.


== Supported versions

* Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, 2.1.x, 2.2.x

* Rails 3.0, 3.1, 3.2, 4.0, 4.1, 4.2

* Sinatra 1.4

* Haml 3+

* Mongoid 2+

== Install

Put this line in your Gemfile:
  gem 'kaminari'

Then bundle:
  % bundle


== Usage

=== Query Basics

* the +page+ scope

  To fetch the 7th page of users (default +per_page+ is 25)
    User.page(7)

* the +per+ scope

  To show a lot more users per each page (change the +per_page+ value)
    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.

  Keep in mind that +per+ utilizes internally +limit+ and so it will override any +limit+ that was set previously.
  And if you want get size for all request records you can use +total_count+ method:
    User.count                    # => 1000
    a = User.limit(5); a.count    # => 5
    a.page(1).per(20).size        # => 20
    a.page(1).per(20).total_count # => 1000

* the +padding+ scope

  Occasionally you need to pad 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.
  default_per_page  # 25 by default
  max_per_page      # nil by default
  max_pages         # nil by default
  window            # 4 by default
  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/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+

  You can specify default +per_page+ value per each model using the following declarative DSL.
    class User < ActiveRecord::Base
      paginates_per 50
    end

=== Configuring max +per_page+ value for each model

* +max_paginates_per+

  You can specify max +per_page+ value per each model using the following declarative DSL.
  If the variable that specified via +per+ scope is more than this variable, +max_paginates_per+ is used instead of it. Default value is nil, which means you are not imposing any max +per_page+ value.
    class User < ActiveRecord::Base
      max_paginates_per 100
    end

=== Controllers

* the page parameter is in <tt>params[:page]</tt>

  Typically, your controller code will look like this:
    @users = User.order(:name).page params[:page]

=== Views

* the same old helper method

  Just call the +paginate+ helper:
    <%= paginate @users %>

  This will render several <tt>?page=N</tt> pagination links surrounded by an HTML5 <+nav+> tag.

=== 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>

* specifying the "inner window" size (4 by default)

    <%= paginate @users, :window => 2 %>
  This would output something like <tt>... 5 6 7 8 9 ...</tt> when 7 is the current page.

* specifying the "outer window" size (0 by default)

    <%= paginate @users, :outer_window => 3 %>
  This would output something like <tt>1 2 3 4 ...(snip)... 17 18 19 20</tt> while having 20 pages in total.

* outer window can be separately specified by +left+, +right+ (0 by default)

    <%= paginate @users, :left => 1, :right => 3 %>
  This would output something like <tt>1 ...(snip)... 18 19 20</tt> while having 20 pages in total.

* changing the parameter name (:+param_name+) for the links

    <%= paginate @users, :param_name => :pagina %>
  This would modify the query parameter name on each links.

* extra parameters (:+params+) for the links

    <%= paginate @users, :params => {:controller => 'foo', :action => 'bar'} %>
  This would modify each link's +url_option+. :+controller+ and :+action+ might be the keys in common.

* Ajax links (crazy simple, but works perfectly!)

    <%= paginate @users, :remote => true %>
  This would add <tt>data-remote="true"</tt> to all the links inside.

* specifying an alternative views directory (default is <tt>kaminari/</tt>)

    <%= paginate @users, :views_prefix => 'templates/' %>
  This would search for partials in <tt>app/views/templates/kaminari</tt>. This option makes it easier to do things like A/B testing pagination templates/themes, using new/old templates at the same time as well as better integration with other gems such as {cells}[https://github.com/apotonick/cells].

* the +link_to_next_page+ and +link_to_previous_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 a 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.<commit_msg>[ci skip] Fix README<commit_after>= Kaminari {<img src="https://travis-ci.org/amatsuda/kaminari.svg"/>}[http://travis-ci.org/amatsuda/kaminari] {<img src="https://img.shields.io/codeclimate/github/amatsuda/kaminari.svg" />}[https://codeclimate.com/github/amatsuda/kaminari] {<img src="http://inch-ci.org/github/amatsuda/kaminari.svg" alt="Inline docs" />}[http://inch-ci.org/github/amatsuda/kaminari]

A Scope & Engine based, clean, powerful, customizable and sophisticated paginator for modern web app frameworks and ORMs


== Features

=== Clean
Does not globally pollute +Array+, +Hash+, +Object+ or <tt>AR::Base</tt>.

=== Easy to use
Just bundle the gem, then your models are ready to be paginated. No configuration required. Don't have to define anything in your models or helpers.

=== Simple scope-based API
Everything is method chainable with less "Hasheritis". You know, that's the Rails 3 way.
No special collection class or anything for the paginated values, instead using a general <tt>AR::Relation</tt> instance. So, of course you can chain any other conditions before or after the paginator scope.

=== Customizable engine-based I18n-aware helper
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) multiple web frameworks (Rails, Sinatra, Grape), and multiple template engines (ERB, Haml, Slim).

=== Modern
The pagination helper outputs the HTML5 <nav> tag by default. Plus, the helper supports Rails 3 unobtrusive Ajax.


== Supported versions

* Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, 2.1.x, 2.2.x

* Rails 3.0, 3.1, 3.2, 4.0, 4.1, 4.2

* Sinatra 1.4

* Haml 3+

* Mongoid 2+

== Install

Put this line in your Gemfile:
  gem 'kaminari'

Then bundle:
  % bundle


== Usage

=== Query Basics

* the +page+ scope

  To fetch the 7th page of users (default +per_page+ is 25)
    User.page(7)

* the +per+ scope

  To show a lot more users per each page (change the +per_page+ value)
    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.

  Keep in mind that +per+ utilizes internally +limit+ and so it will override any +limit+ that was set previously.
  And if you want get size for all request records you can use +total_count+ method:
    User.count                    # => 1000
    a = User.limit(5); a.count    # => 5
    a.page(1).per(20).size        # => 20
    a.page(1).per(20).total_count # => 1000

* the +padding+ scope

  Occasionally you need to pad 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.
  default_per_page  # 25 by default
  max_per_page      # nil by default
  max_pages         # nil by default
  window            # 4 by default
  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/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+

  You can specify default +per_page+ value per each model using the following declarative DSL.
    class User < ActiveRecord::Base
      paginates_per 50
    end

=== Configuring max +per_page+ value for each model

* +max_paginates_per+

  You can specify max +per_page+ value per each model using the following declarative DSL.
  If the variable that specified via +per+ scope is more than this variable, +max_paginates_per+ is used instead of it. Default value is nil, which means you are not imposing any max +per_page+ value.
    class User < ActiveRecord::Base
      max_paginates_per 100
    end

=== Controllers

* the page parameter is in <tt>params[:page]</tt>

  Typically, your controller code will look like this:
    @users = User.order(:name).page params[:page]

=== Views

* the same old helper method

  Just call the +paginate+ helper:
    <%= paginate @users %>

  This will render several <tt>?page=N</tt> pagination links surrounded by an HTML5 <+nav+> tag.

=== 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>

* specifying the "inner window" size (4 by default)

    <%= paginate @users, :window => 2 %>
  This would output something like <tt>... 5 6 7 8 9 ...</tt> when 7 is the current page.

* specifying the "outer window" size (0 by default)

    <%= paginate @users, :outer_window => 3 %>
  This would output something like <tt>1 2 3 4 ...(snip)... 17 18 19 20</tt> while having 20 pages in total.

* outer window can be separately specified by +left+, +right+ (0 by default)

    <%= paginate @users, :left => 1, :right => 3 %>
  This would output something like <tt>1 ...(snip)... 18 19 20</tt> while having 20 pages in total.

* changing the parameter name (:+param_name+) for the links

    <%= paginate @users, :param_name => :pagina %>
  This would modify the query parameter name on each links.

* extra parameters (:+params+) for the links

    <%= paginate @users, :params => {:controller => 'foo', :action => 'bar'} %>
  This would modify each link's +url_option+. :+controller+ and :+action+ might be the keys in common.

* Ajax links (crazy simple, but works perfectly!)

    <%= paginate @users, :remote => true %>
  This would add <tt>data-remote="true"</tt> to all the links inside.

* specifying an alternative views directory (default is <tt>kaminari/</tt>)

    <%= paginate @users, :views_prefix => 'templates' %>
  This would search for partials in <tt>app/views/templates/kaminari</tt>. This option makes it easier to do things like A/B testing pagination templates/themes, using new/old templates at the same time as well as better integration with other gems such as {cells}[https://github.com/apotonick/cells].

* the +link_to_next_page+ and +link_to_previous_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 a 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.
{'fraction_non_alphanumeric': 0.0996002205679625, 'fraction_numerical': 0.017094017094017096, 'mean_word_length': 3.6727858293075686, 'pattern_counts': {'":': 0, '<': 87, '<?xml version=': 0, '>': 111, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6217689', 'n_tokens_mistral': 4568, 'n_tokens_neox': 4202, 'n_words': 1880}