peiji-san 0.1.1 → 1.0.0

data/README.rdoc

@@ -1,22 +1,42 @@
 = Peiji-San
 
-Peiji-San uses named scopes to create a thin pagination layer.
+Peiji-San uses scopes to create a thin pagination layer.
 
-Model:
+We try to stay out of the way of your application as much as possible. That's
+why you need to include Peiji in the places where you actually use it.
 
   class Member < ActiveRecord::Base
     extend PeijiSan
     self.entries_per_page = 32
   end
 
-Controller:
+After that a special extended scope is defined on the model and you will be
+able to select a collection that contains only records on that page.
 
   @collection = Member.active.page(2)
 
-View:
+In the view you can either build your own links to the pages or you can use
+the helpers shipped with Peiji. Like with the model extension the view
+helpers aren't defined by default, you will need to include them in another
+helper class.
+
+  class ApplicationHelper
+    include PeijiSan::ViewHelper
+  end
+
+After that the helpers will be usable in your view.
 
   <% if @collection.page_count > 1 %>
-    <% pages_to_link_to(@collection).each do |page %>
+    <% pages_to_link_to(@collection).each do |page| %>
       <%= page.is_a?(String) ? page : link_to_page(page, @collection) %>
     <% end %>
   <% end %>
+
+== Rails 2.3 and earlier
+
+The latest version of Peiji only works in Rails 3 because of extensive
+changes to the scope API. However, earlier version work just fine in
+Rails 2.3. Rails 3 support starts at version 1.0, so put the following
+in environment.rb:
+
+  config.gem "peiji-san", :lib => "peiji_san", :version => "< 1.0"

data/TODO

@@ -1,2 +1 @@
-* Merge Scope and Array methods
 * Make it possible to use this pattern: http://www.percona.com/ppc2009/PPC2009_mysql_pagination.pdf

data/VERSION.yml

@@ -1,4 +1,5 @@
 --- 
-:major: 0
-:minor: 1
-:patch: 1
+:patch: 0
+:major: 1
+:build: 
+:minor: 0

data/lib/peiji_san/view_helper.rb

@@ -1,11 +1,13 @@
 module PeijiSan
-  # Include this module into your view helper module, for instance
-  # ApplicationController, for super paginating cow powers.
-  #
-  # Optionally define the peiji_san_options method in your helper to override
+  # Optionally defines the peiji_san_options method in your helper to override
   # the default options.
   #
-  # Example:
+  # Include the PeijiSan::ViewHelper into one of your view helpers to acquire
+  # PeijiSan superpowers in your view.
+  #
+  #   class ApplicationHelper
+  #     include PeijiSan::ViewHelper
+  #   end
   #
   #   @collection = Member.active.page(2)
   #
@@ -17,7 +19,7 @@ module PeijiSan
     DEFAULT_PEIJI_SAN_OPTIONS = {
       # For link_to_page
       :page_parameter => :page,
-      :anchor => :explore,
+      :anchor => nil,
       :current_class => :current,
       # For pages_to_link_to
       :max_visible => 11,
@@ -65,8 +67,6 @@ module PeijiSan
     #     The separator string used to indicate a range between the first or last
     #     page and the ones surrounding the current page.
     #
-    # Example:
-    #
     #   collection = Model.all.page(40)
     #   collection.page_count # => 80
     #

data/lib/peiji_san.rb

@@ -1,7 +1,5 @@
 # Peiji-San uses named scopes to create a thin pagination layer.
 #
-# Example:
-#
 #   class Member < ActiveRecord::Base
 #     extend PeijiSan
 #     self.entries_per_page = 32
@@ -13,16 +11,18 @@
 #
 # Which will return 32 records with an offset of 32, as that's the second page.
 #
-# See PeijiSan::PageScope and PeijiSan::ViewHelper for more info.
+# See PeijiSan::PaginationMethods and PeijiSan::ViewHelper for more info.
 module PeijiSan
-  class PageScope < ActiveRecord::NamedScope::Scope
-    attr_reader :current_page
-    
-    def initialize(proxy_scope, options)
-      @current_page = (options[:page].blank? ? 1 : options[:page]).to_i
-      @entries_per_page = options[:entries_per_page]
-      super(proxy_scope, :offset => ((@current_page - 1) * @entries_per_page), :limit => @entries_per_page)
-    end
+  ENTRIES_PER_PAGE = 32
+  
+  # The page scope is extended with the PaginationMethods. This means that all
+  # methods defined on this module will be available on the resulting
+  # collection.
+  #
+  #   collection = Member.active.page(1)
+  #   collection.has_next_page?
+  module PaginationMethods
+    attr_accessor :current_page, :entries_per_page, :scope_without_pagination
     
     # Returns whether or not the given page is the current page.
     def current_page?(page)
@@ -53,13 +53,13 @@ module PeijiSan
     
     # Returns the row count for all the rows that would match the current
     # scope, so not only on the current page.
-    def count
-      @proxy_scope.count
+    def unpaged_count
+      scope_without_pagination.count
     end
     
     # Returns the number of pages for the current scope.
     def page_count
-      (count.to_f / @entries_per_page).ceil
+      (unpaged_count.to_f / @entries_per_page).ceil
     end
   end
   
@@ -67,7 +67,7 @@ module PeijiSan
   #
   #   class Member < ActiveRecord::Base
   #     extend PeijiSan
-  #     entries_per_page 32
+  #     self.entries_per_page = 32
   #   end
   def entries_per_page=(entries)
     @entries_per_page = entries
@@ -77,7 +77,7 @@ module PeijiSan
   #
   #   class Member < ActiveRecord::Base
   #     extend PeijiSan
-  #     entries_per_page 32
+  #     self.entries_per_page = 32
   #   end
   #   Member.entries_per_page #=> 32
   def entries_per_page
@@ -90,7 +90,7 @@ module PeijiSan
   #
   #   class Member < ActiveRecord::Base
   #     extend PeijiSan
-  #     entries_per_page 32
+  #     self.entries_per_page = 32
   #   end
   #
   # This adds <tt>{ :limit => 32, :offset => 0 }</tt> to the scope:
@@ -105,20 +105,16 @@ module PeijiSan
   # second argument:
   #
   #   Member.page(2, 5) # Page 2, 5 entries
-  def page(page, entries_per_page = nil)
-    scopes[:page].call(self, page, entries_per_page)
-  end
-  
-  # Defines the page named_scope when it extends a model class.
-  #
-  #   Member.respond_to? :page # => false
-  #
-  #   class Member < ActiveRecord::Base
-  #     extend PeijiSan
-  #   end
-  #
-  #   Member.respond_to? :page # => true
-  def self.extended(klass)
-    klass.scopes[:page] = lambda { |parent_scope, *args| PageScope.new(parent_scope, :page => args[0], :entries_per_page => args[1] || klass.entries_per_page) }
+  def page(page, entries_per_page=nil)
+    page = page.blank? ? 1 : page.to_i
+    entries_per_page = entries_per_page || self.entries_per_page || ENTRIES_PER_PAGE
+    
+    entries = scoped
+    entries.extend(PeijiSan::PaginationMethods)
+    entries.current_page = page
+    entries.entries_per_page = entries_per_page
+    entries.scope_without_pagination = scoped
+    
+    entries.limit(entries_per_page).offset((page - 1) * entries_per_page)
   end
 end

data/rdoc/classes/PeijiSan/PaginationMethods.html

@@ -0,0 +1,344 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Module: PeijiSan::PaginationMethods</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Module</strong></td>
+          <td class="class-name-in-header">PeijiSan::PaginationMethods</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../../files/lib/peiji_san_rb.html">
+                lib/peiji_san.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+    <div id="description">
+      <p>
+The page scope is extended with the <a
+href="PaginationMethods.html">PaginationMethods</a>. This means that all
+methods defined on this module will be available on the resulting
+collection.
+</p>
+<pre>
+  collection = Member.active.page(1)
+  collection.has_next_page?
+</pre>
+
+    </div>
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000007">current_page?</a>&nbsp;&nbsp;
+      <a href="#M000008">has_next_page?</a>&nbsp;&nbsp;
+      <a href="#M000009">has_previous_page?</a>&nbsp;&nbsp;
+      <a href="#M000010">next_page</a>&nbsp;&nbsp;
+      <a href="#M000013">page_count</a>&nbsp;&nbsp;
+      <a href="#M000011">previous_page</a>&nbsp;&nbsp;
+      <a href="#M000012">unpaged_count</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+
+    <div id="section">
+
+
+
+
+
+    <div id="attribute-list">
+      <h3 class="section-bar">Attributes</h3>
+
+      <div class="name-list">
+        <table>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">current_page</td>
+          <td class="context-item-value">&nbsp;[RW]&nbsp;</td>
+          <td class="context-item-desc"></td>
+        </tr>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">entries_per_page</td>
+          <td class="context-item-value">&nbsp;[RW]&nbsp;</td>
+          <td class="context-item-desc"></td>
+        </tr>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">scope_without_pagination</td>
+          <td class="context-item-value">&nbsp;[RW]&nbsp;</td>
+          <td class="context-item-desc"></td>
+        </tr>
+        </table>
+      </div>
+    </div>
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Instance methods</h3>
+
+      <div id="method-M000007" class="method-detail">
+        <a name="M000007"></a>
+
+        <div class="method-heading">
+          <a href="#M000007" class="method-signature">
+          <span class="method-name">current_page?</span><span class="method-args">(page)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns whether or not the given page is the current page.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000007-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000007-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 30</span>
+30:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">current_page?</span>(<span class="ruby-identifier">page</span>)
+31:       <span class="ruby-ivar">@current_page</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">page</span>
+32:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000008" class="method-detail">
+        <a name="M000008"></a>
+
+        <div class="method-heading">
+          <a href="#M000008" class="method-signature">
+          <span class="method-name">has_next_page?</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns whether or not there is a next page for the current scope.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000008-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000008-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 35</span>
+35:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">has_next_page?</span>
+36:       <span class="ruby-ivar">@current_page</span> <span class="ruby-operator">&lt;</span> <span class="ruby-identifier">page_count</span>
+37:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000009" class="method-detail">
+        <a name="M000009"></a>
+
+        <div class="method-heading">
+          <a href="#M000009" class="method-signature">
+          <span class="method-name">has_previous_page?</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns whether or not there is a previous page for the current scope.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000009-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000009-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 40</span>
+40:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">has_previous_page?</span>
+41:       <span class="ruby-ivar">@current_page</span> <span class="ruby-operator">!=</span> <span class="ruby-value">1</span>
+42:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000010" class="method-detail">
+        <a name="M000010"></a>
+
+        <div class="method-heading">
+          <a href="#M000010" class="method-signature">
+          <span class="method-name">next_page</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the next page number if there is a next page, returns <tt>nil</tt>
+otherwise.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000010-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000010-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 46</span>
+46:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">next_page</span>
+47:       <span class="ruby-ivar">@current_page</span> <span class="ruby-operator">+</span> <span class="ruby-value">1</span> <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">has_next_page?</span>
+48:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000013" class="method-detail">
+        <a name="M000013"></a>
+
+        <div class="method-heading">
+          <a href="#M000013" class="method-signature">
+          <span class="method-name">page_count</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the number of pages for the current scope.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000013-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000013-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 63</span>
+63:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">page_count</span>
+64:       (<span class="ruby-identifier">unpaged_count</span>.<span class="ruby-identifier">to_f</span> <span class="ruby-operator">/</span> <span class="ruby-ivar">@entries_per_page</span>).<span class="ruby-identifier">ceil</span>
+65:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000011" class="method-detail">
+        <a name="M000011"></a>
+
+        <div class="method-heading">
+          <a href="#M000011" class="method-signature">
+          <span class="method-name">previous_page</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the previous page number if there is a previous page, returns
+<tt>nil</tt> otherwise.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000011-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000011-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 52</span>
+52:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">previous_page</span>
+53:       <span class="ruby-ivar">@current_page</span> <span class="ruby-operator">-</span> <span class="ruby-value">1</span> <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">has_previous_page?</span>
+54:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000012" class="method-detail">
+        <a name="M000012"></a>
+
+        <div class="method-heading">
+          <a href="#M000012" class="method-signature">
+          <span class="method-name">unpaged_count</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the row count for all the rows that would match the current scope,
+so not only on the current page.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000012-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000012-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/peiji_san.rb, line 58</span>
+58:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">unpaged_count</span>
+59:       <span class="ruby-identifier">scope_without_pagination</span>.<span class="ruby-identifier">count</span>
+60:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>