vendor/plugins/will_paginate/README

   1 = WillPaginate
   2
   3 Quick quiz: Where does pagination logic belong?
   4
   5   a) in the model;
   6   b) in the controller;
   7   c) in views;
   8   d) all of the above.
   9
  10 We think you know the answer (if you think hard enough).
  11
  12 This plugin makes magic happen. You *will* paginate!
  13
  14
  15 == Example usage:
  16
  17 Use a paginate finder in the controller:
  18
  19     @posts = Post.paginate_by_board_id @board.id, :page => params[:page]
  20
  21 Yeah, +paginate+ works just like +find+ -- it just doesn't fetch all the records.
  22 Just don't forget to tell it which page you want!
  23
  24 Render the posts in your view like you would normally do. When you need to render
  25 pagination, just stick this in:
  26
  27     <%= will_paginate @posts %>
  28
  29 You're done. (Copy and paste the example fancy CSS styles from the bottom.)
  30
  31 How does it know how much items to fetch per page? It asks your model by calling
  32 +Post.per_page+. You can define it like this:
  33
  34     class Post < ActiveRecord::Base
  35       cattr_reader :per_page
  36       @@per_page = 50
  37     end
  38
  39 ... or like this:
  40
  41     class Post < ActiveRecord::Base
  42       def self.per_page
  43         50
  44       end
  45     end
  46
  47 ... or don't worry about it at all. (WillPaginate defines it to be 30 if missing.)
  48 You can also specify the count explicitly when calling +paginate+:
  49
  50     @posts = Post.paginate :page => params[:page], :per_page => 50
  51
  52 The +paginate+ finder wraps the original finder and returns your resultset that now has
  53 some new properties. You can use the collection as you would with any ActiveRecord
  54 resultset, but WillPaginate view helpers also need that object to be able to render pagination:
  55
  56     <ol>
  57       <% for post in @posts -%>
  58         <li>Render `post` in some nice way.</li>
  59       <% end -%>
  60     </ol>
  61
  62     <p>Now let's render us some pagination!</p>
  63     <%= will_paginate @posts %>
  64
  65
  66 == Authors, credits
  67
  68   Ruby port by:           PJ Hyett, Mislav Marohnić (Sulien)
  69   Contributors:           K. Adam Christensen, Chris Wanstrath, Dr. Nic Williams
  70   Original announcement:  http://errtheblog.com/post/929
  71   Original PHP source:    http://www.strangerstudios.com/sandbox/pagination/diggstyle.php
  72
  73 REPORT BUGS on Lighthouse: http://err.lighthouseapp.com/projects/466-plugins/overview
  74
  75
  76 == Want Digg style?
  77
  78 Copy the following css into your stylesheet for a good start:
  79
  80   .pagination {
  81     padding: 3px;
  82     margin: 3px;
  83   }
  84   .pagination a {
  85     padding: 2px 5px 2px 5px;
  86     margin: 2px;
  87     border: 1px solid #aaaadd;
  88     text-decoration: none;
  89     color: #000099;
  90   }
  91   .pagination a:hover, .pagination a:active {
  92     border: 1px solid #000099;
  93     color: #000;
  94   }
  95   .pagination span.current {
  96     padding: 2px 5px 2px 5px;
  97     margin: 2px;
  98     border: 1px solid #000099;
  99     font-weight: bold;
 100     background-color: #000099;
 101     color: #FFF;
 102   }
 103   .pagination span.disabled {
 104     padding: 2px 5px 2px 5px;
 105     margin: 2px;
 106     border: 1px solid #eee;
 107     color: #ddd;
 108   }