typo 5.1.3 → 5.1.98

data/vendor/plugins/will_paginate/README.rdoc

@@ -0,0 +1,107 @@
+= 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.
+
+Some resources to get you started:
+
+* {Installation instructions}[http://github.com/mislav/will_paginate/wikis/installation]
+  on {the wiki}[http://github.com/mislav/will_paginate/wikis]
+* Your mind reels with questions? Join our
+  {Google group}[http://groups.google.com/group/will_paginate].
+* {How to report bugs}[http://github.com/mislav/will_paginate/wikis/report-bugs]
+
+
+== 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. (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.
+
+
+== Authors and credits
+
+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 just 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,
+Lourens Naudé, Rick Olson, Russell Norris, Piotr Usewicz, Chris Eppstein,
+Denis Barushev, Ben Pickles.
+
+
+== Usable pagination in the UI
+
+There are some CSS styles to get you started in the "examples/" directory. They
+are {showcased online here}[http://mislav.caboo.se/static/will_paginate/].
+
+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]
+
+Want to discuss, request features, ask questions? Join the
+{Google group}[http://groups.google.com/group/will_paginate].
+

data/vendor/plugins/will_paginate/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+begin
+  hanna_dir = '/Users/mislav/Projects/Hanna/lib'
+  $:.unshift hanna_dir if File.exists? hanna_dir
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake'
+  require 'rake/rdoctask'
+end
+load 'test/tasks.rake'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Generate RDoc documentation for the will_paginate plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG.rdoc').
+    include('lib/**/*.rb').
+    exclude('lib/will_paginate/named_scope*').
+    exclude('lib/will_paginate/array.rb').
+    exclude('lib/will_paginate/version.rb')
+  
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "will_paginate documentation"
+  
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--inline-source' << '--charset=UTF-8'
+  rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
+end
+
+desc %{Update ".manifest" with the latest list of project filenames. Respect\
+.gitignore by excluding everything that git ignores. Update `files` and\
+`test_files` arrays in "*.gemspec" file if it's present.}
+task :manifest do
+  list = Dir['**/*'].sort
+  spec_file = Dir['*.gemspec'].first
+  list -= [spec_file] if spec_file
+  
+  File.read('.gitignore').each_line do |glob|
+    glob = glob.chomp.sub(/^\//, '')
+    list -= Dir[glob]
+    list -= Dir["#{glob}/**/*"] if File.directory?(glob) and !File.symlink?(glob)
+    puts "excluding #{glob}"
+  end
+
+  if spec_file
+    spec = File.read spec_file
+    spec.gsub! /^(\s* s.(test_)?files \s* = \s* )( \[ [^\]]* \] | %w\( [^)]* \) )/mx do
+      assignment = $1
+      bunch = $2 ? list.grep(/^test\//) : list
+      '%s%%w(%s)' % [assignment, bunch.join(' ')]
+    end
+      
+    File.open(spec_file,   'w') {|f| f << spec }
+  end
+  File.open('.manifest', 'w') {|f| f << list.join("\n") }
+end
+
+task :examples do
+  %x(haml examples/index.haml examples/index.html)
+  %x(sass examples/pagination.sass examples/pagination.css)
+end

data/vendor/plugins/will_paginate/examples/index.haml

@@ -0,0 +1,69 @@
+!!!
+%html
+%head
+  %title Samples of pagination styling for will_paginate
+  %link{ :rel => 'stylesheet', :type => 'text/css', :href => 'pagination.css' }
+  %style{ :type => 'text/css' }
+    :sass
+      html
+        :margin 0
+        :padding 0
+        :background #999
+        :font normal 76% "Lucida Grande", Verdana, Helvetica, sans-serif
+      body
+        :margin 2em
+        :padding 2em
+        :border 2px solid gray
+        :background white
+        :color #222
+      h1
+        :font-size 2em
+        :font-weight normal
+        :margin 0 0 1em 0
+      h2
+        :font-size 1.4em
+        :margin 1em 0 .5em 0
+      pre
+        :font-size 13px
+        :font-family Monaco, "DejaVu Sans Mono", "Bitstream Vera Mono", "Courier New", monospace
+
+- pagination = '<span class="disabled prev_page">&laquo; Previous</span> <span class="current">1</span> <a href="./?page=2" rel="next">2</a> <a href="./?page=3">3</a> <a href="./?page=4">4</a> <a href="./?page=5">5</a> <a href="./?page=6">6</a> <a href="./?page=7">7</a> <a href="./?page=8">8</a> <a href="./?page=9">9</a> <span class="gap">&hellip;</span> <a href="./?page=29">29</a> <a href="./?page=30">30</a> <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>'
+- pagination_no_page_links = '<span class="disabled prev_page">&laquo; Previous</span>  <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>'
+
+%body
+  %h1 Samples of pagination styling for will_paginate
+  %p
+    Find these styles in <b>"examples/pagination.css"</b> of <i>will_paginate</i> library.
+    There is a Sass version of it for all you sassy people.
+  %p
+    Read about good rules for pagination:
+    %a{ :href => 'http://kurafire.net/log/archive/2007/06/22/pagination-101' } Pagination 101
+  %p
+    %em Warning:
+    page links below don't lead anywhere (so don't click on them).
+    
+  %h2 Unstyled pagination <span style="font-weight:normal">(<i>ewww!</i>)</span>
+  %div= pagination
+  
+  %h2 Digg.com
+  .digg_pagination= pagination
+
+  %h2 Digg-style, no page links
+  .digg_pagination= pagination_no_page_links
+  %p Code that renders this:
+  %pre= '<code>%s</code>' % %[<%= will_paginate @posts, :page_links => false %>].gsub('<', '&lt;').gsub('>', '&gt;')
+  
+  %h2 Digg-style, extra content
+  .digg_pagination
+    .page_info Displaying entries <b>1&nbsp;-&nbsp;6</b> of <b>180</b> in total
+    = pagination
+  %p Code that renders this:
+  %pre= '<code>%s</code>' % %[<div class="digg_pagination">\n  <div clas="page_info">\n    <%= page_entries_info @posts %>\n  </div>\n  <%= will_paginate @posts, :container => false %>\n</div>].gsub('<', '&lt;').gsub('>', '&gt;')
+  
+  %h2 Apple.com store
+  .apple_pagination= pagination
+  
+  %h2 Flickr.com
+  .flickr_pagination
+    = pagination
+    .page_info (118 photos)

data/vendor/plugins/will_paginate/examples/index.html

@@ -0,0 +1,92 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+</html>
+<head>
+  <title>Samples of pagination styling for will_paginate</title>
+  <link href='pagination.css' rel='stylesheet' type='text/css' />
+  <style type='text/css'>
+    html {
+      margin: 0;
+      padding: 0;
+      background: #999;
+      font: normal 76% "Lucida Grande", Verdana, Helvetica, sans-serif; }
+    
+    body {
+      margin: 2em;
+      padding: 2em;
+      border: 2px solid gray;
+      background: white;
+      color: #222; }
+    
+    h1 {
+      font-size: 2em;
+      font-weight: normal;
+      margin: 0 0 1em 0; }
+    
+    h2 {
+      font-size: 1.4em;
+      margin: 1em 0 .5em 0; }
+    
+    pre {
+      font-size: 13px;
+      font-family: Monaco, "DejaVu Sans Mono", "Bitstream Vera Mono", "Courier New", monospace; }
+  </style>
+</head>
+<body>
+  <h1>Samples of pagination styling for will_paginate</h1>
+  <p>
+    Find these styles in <b>"examples/pagination.css"</b> of <i>will_paginate</i> library.
+    There is a Sass version of it for all you sassy people.
+  </p>
+  <p>
+    Read about good rules for pagination:
+    <a href='http://kurafire.net/log/archive/2007/06/22/pagination-101'>Pagination 101</a>
+  </p>
+  <p>
+    <em>Warning:</em>
+    page links below don't lead anywhere (so don't click on them).
+  </p>
+  <h2>
+    Unstyled pagination <span style="font-weight:normal">(<i>ewww!</i>)</span>
+  </h2>
+  <div>
+    <span class="disabled prev_page">&laquo; Previous</span> <span class="current">1</span> <a href="./?page=2" rel="next">2</a> <a href="./?page=3">3</a> <a href="./?page=4">4</a> <a href="./?page=5">5</a> <a href="./?page=6">6</a> <a href="./?page=7">7</a> <a href="./?page=8">8</a> <a href="./?page=9">9</a> <span class="gap">&hellip;</span> <a href="./?page=29">29</a> <a href="./?page=30">30</a> <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>
+  </div>
+  <h2>Digg.com</h2>
+  <div class='digg_pagination'>
+    <span class="disabled prev_page">&laquo; Previous</span> <span class="current">1</span> <a href="./?page=2" rel="next">2</a> <a href="./?page=3">3</a> <a href="./?page=4">4</a> <a href="./?page=5">5</a> <a href="./?page=6">6</a> <a href="./?page=7">7</a> <a href="./?page=8">8</a> <a href="./?page=9">9</a> <span class="gap">&hellip;</span> <a href="./?page=29">29</a> <a href="./?page=30">30</a> <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>
+  </div>
+  <h2>Digg-style, no page links</h2>
+  <div class='digg_pagination'>
+    <span class="disabled prev_page">&laquo; Previous</span>  <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>
+  </div>
+  <p>Code that renders this:</p>
+  <pre>
+    <code>&lt;%= will_paginate @posts, :page_links =&gt; false %&gt;</code>
+  </pre>
+  <h2>Digg-style, extra content</h2>
+  <div class='digg_pagination'>
+    <div class='page_info'>
+      Displaying entries <b>1&nbsp;-&nbsp;6</b> of <b>180</b> in total
+    </div>
+    <span class="disabled prev_page">&laquo; Previous</span> <span class="current">1</span> <a href="./?page=2" rel="next">2</a> <a href="./?page=3">3</a> <a href="./?page=4">4</a> <a href="./?page=5">5</a> <a href="./?page=6">6</a> <a href="./?page=7">7</a> <a href="./?page=8">8</a> <a href="./?page=9">9</a> <span class="gap">&hellip;</span> <a href="./?page=29">29</a> <a href="./?page=30">30</a> <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>
+  </div>
+  <p>Code that renders this:</p>
+  <pre>
+    <code>&lt;div class="digg_pagination"&gt;
+      &lt;div clas="page_info"&gt;
+        &lt;%= page_entries_info @posts %&gt;
+      &lt;/div&gt;
+      &lt;%= will_paginate @posts, :container =&gt; false %&gt;
+    &lt;/div&gt;</code>
+  </pre>
+  <h2>Apple.com store</h2>
+  <div class='apple_pagination'>
+    <span class="disabled prev_page">&laquo; Previous</span> <span class="current">1</span> <a href="./?page=2" rel="next">2</a> <a href="./?page=3">3</a> <a href="./?page=4">4</a> <a href="./?page=5">5</a> <a href="./?page=6">6</a> <a href="./?page=7">7</a> <a href="./?page=8">8</a> <a href="./?page=9">9</a> <span class="gap">&hellip;</span> <a href="./?page=29">29</a> <a href="./?page=30">30</a> <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>
+  </div>
+  <h2>Flickr.com</h2>
+  <div class='flickr_pagination'>
+    <span class="disabled prev_page">&laquo; Previous</span> <span class="current">1</span> <a href="./?page=2" rel="next">2</a> <a href="./?page=3">3</a> <a href="./?page=4">4</a> <a href="./?page=5">5</a> <a href="./?page=6">6</a> <a href="./?page=7">7</a> <a href="./?page=8">8</a> <a href="./?page=9">9</a> <span class="gap">&hellip;</span> <a href="./?page=29">29</a> <a href="./?page=30">30</a> <a href="./?page=2" rel="next" class="next_page">Next &raquo;</a>
+    <div class='page_info'>(118 photos)</div>
+  </div>
+</body>

data/vendor/plugins/will_paginate/examples/pagination.css

@@ -0,0 +1,90 @@
+.digg_pagination {
+  background: white;
+  /* self-clearing method: */ }
+  .digg_pagination a, .digg_pagination span {
+    padding: .2em .5em;
+    display: block;
+    float: left;
+    margin-right: 1px; }
+  .digg_pagination span.disabled {
+    color: #999;
+    border: 1px solid #DDD; }
+  .digg_pagination span.current {
+    font-weight: bold;
+    background: #2E6AB1;
+    color: white;
+    border: 1px solid #2E6AB1; }
+  .digg_pagination a {
+    text-decoration: none;
+    color: #105CB6;
+    border: 1px solid #9AAFE5; }
+    .digg_pagination a:hover, .digg_pagination a:focus {
+      color: #003;
+      border-color: #003; }
+  .digg_pagination .page_info {
+    background: #2E6AB1;
+    color: white;
+    padding: .4em .6em;
+    width: 22em;
+    margin-bottom: .3em;
+    text-align: center; }
+    .digg_pagination .page_info b {
+      color: #003;
+      background: #6aa6ed;
+      padding: .1em .25em; }
+  .digg_pagination:after {
+    content: ".";
+    display: block;
+    height: 0;
+    clear: both;
+    visibility: hidden; }
+  * html .digg_pagination {
+    height: 1%; }
+  *:first-child+html .digg_pagination {
+    overflow: hidden; }
+
+.apple_pagination {
+  background: #F1F1F1;
+  border: 1px solid #E5E5E5;
+  text-align: center;
+  padding: 1em; }
+  .apple_pagination a, .apple_pagination span {
+    padding: .2em .3em; }
+  .apple_pagination span.disabled {
+    color: #AAA; }
+  .apple_pagination span.current {
+    font-weight: bold;
+    background: transparent url(apple-circle.gif) no-repeat 50% 50%; }
+  .apple_pagination a {
+    text-decoration: none;
+    color: black; }
+    .apple_pagination a:hover, .apple_pagination a:focus {
+      text-decoration: underline; }
+
+.flickr_pagination {
+  text-align: center;
+  padding: .3em; }
+  .flickr_pagination a, .flickr_pagination span {
+    padding: .2em .5em; }
+  .flickr_pagination span.disabled {
+    color: #AAA; }
+  .flickr_pagination span.current {
+    font-weight: bold;
+    color: #FF0084; }
+  .flickr_pagination a {
+    border: 1px solid #DDDDDD;
+    color: #0063DC;
+    text-decoration: none; }
+    .flickr_pagination a:hover, .flickr_pagination a:focus {
+      border-color: #003366;
+      background: #0063DC;
+      color: white; }
+  .flickr_pagination .page_info {
+    color: #aaa;
+    padding-top: .8em; }
+  .flickr_pagination .prev_page, .flickr_pagination .next_page {
+    border-width: 2px; }
+  .flickr_pagination .prev_page {
+    margin-right: 1em; }
+  .flickr_pagination .next_page {
+    margin-left: 1em; }

data/vendor/plugins/will_paginate/examples/pagination.sass

@@ -0,0 +1,91 @@
+.digg_pagination
+  :background white
+  a, span
+    :padding .2em .5em
+    :display block
+    :float left
+    :margin-right 1px
+  span.disabled
+    :color #999
+    :border 1px solid #DDD
+  span.current
+    :font-weight bold
+    :background #2E6AB1
+    :color white
+    :border 1px solid #2E6AB1
+  a
+    :text-decoration none
+    :color #105CB6
+    :border 1px solid #9AAFE5
+    &:hover, &:focus
+      :color #003
+      :border-color #003
+  .page_info
+    :background #2E6AB1
+    :color white
+    :padding .4em .6em
+    :width 22em
+    :margin-bottom .3em
+    :text-align center
+    b
+      :color #003
+      :background = #2E6AB1 + 60
+      :padding .1em .25em
+    
+  /* self-clearing method:
+  &:after
+    :content "."
+    :display block
+    :height 0
+    :clear both
+    :visibility hidden
+  * html &
+    :height 1%
+  *:first-child+html &
+    :overflow hidden
+
+.apple_pagination
+  :background #F1F1F1
+  :border 1px solid #E5E5E5
+  :text-align center
+  :padding 1em
+  a, span
+    :padding .2em .3em
+  span.disabled
+    :color #AAA
+  span.current
+    :font-weight bold
+    :background transparent url(apple-circle.gif) no-repeat 50% 50%
+  a
+    :text-decoration none
+    :color black
+    &:hover, &:focus
+      :text-decoration underline
+
+.flickr_pagination
+  :text-align center
+  :padding .3em
+  a, span
+    :padding .2em .5em
+  span.disabled
+    :color #AAA
+  span.current
+    :font-weight bold
+    :color #FF0084
+  a
+    :border 1px solid #DDDDDD
+    :color #0063DC
+    :text-decoration none
+    &:hover, &:focus
+      :border-color #003366
+      :background #0063DC
+      :color white
+  .page_info
+    :color #aaa
+    :padding-top .8em
+  .prev_page, .next_page
+    :border-width 2px
+  .prev_page
+    :margin-right 1em
+  .next_page
+    :margin-left 1em

data/vendor/plugins/will_paginate/init.rb

@@ -0,0 +1 @@
+require 'will_paginate'

data/vendor/plugins/will_paginate/lib/will_paginate/array.rb

@@ -0,0 +1,16 @@
+require 'will_paginate/collection'
+
+# http://www.desimcadam.com/archives/8
+Array.class_eval do
+  def paginate(options = {})
+    raise ArgumentError, "parameter hash expected (got #{options.inspect})" unless Hash === options
+    
+    WillPaginate::Collection.create(
+        options[:page] || 1,
+        options[:per_page] || 30,
+        options[:total_entries] || self.length
+    ) { |pager|
+      pager.replace self[pager.offset, pager.per_page].to_a
+    }
+  end
+end

data/vendor/plugins/will_paginate/lib/will_paginate/collection.rb

@@ -0,0 +1,146 @@
+module WillPaginate
+  # = Invalid page number error
+  # 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.
+  #
+  # If you're using Rails 2, then this error will automatically get handled like
+  # 404 Not Found. The hook is in "will_paginate.rb":
+  #
+  #   ActionController::Base.rescue_responses['WillPaginate::InvalidPage'] = :not_found
+  #
+  # If you don't like this, use your preffered method of rescuing exceptions in
+  # public from your controllers to handle this differently. The +rescue_from+
+  # method is a nice addition to Rails 2.
+  #
+  # 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
+  
+  # = The key to pagination
+  # Arrays returned from paginating finds are, in fact, instances of this little
+  # class. 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+.
+  # 
+  # If you are writing a library that provides a collection which you would like
+  # to conform to this API, you don't have to copy these methods over; simply
+  # make your plugin/gem dependant on the "mislav-will_paginate" gem:
+  #
+  #   gem 'mislav-will_paginate'
+  #   require 'will_paginate/collection'
+  #   
+  #   # WillPaginate::Collection is now available for use
+  class Collection < Array
+    attr_reader :current_page, :per_page, :total_entries, :total_pages
+
+    # Arguments to the 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
+    #
+    # The Array#paginate API has since then changed, but this still serves as a
+    # fine example of WillPaginate::Collection usage.
+    def self.create(page, per_page, total = nil, &block)
+      pager = new(page, per_page, total)
+      yield pager
+      pager
+    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 > total_pages
+    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
+    # side by side with records in the view: 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 < total_pages ? (current_page + 1) : nil
+    end
+    
+    # sets the <tt>total_entries</tt> property and calculates <tt>total_pages</tt>
+    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)
+      result = super
+      
+      # 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 < per_page and (current_page == 1 or length > 0)
+        self.total_entries = offset + length
+      end
+
+      result
+    end
+  end
+end