Help interpret will_paginate docs?

Question

Trying to understand the options for will_paginate's paginate method:

:page — REQUIRED, but defaults to 1 if false or nil
:per_page — defaults to CurrentModel.per_page (which is 30 if not overridden)
:total_entries — use only if you manually count total entries
:count — additional options that are passed on to count
:finder — name of the ActiveRecord finder used (default: “find”)

page, per_page, and finder are straightforward.

total_entries and count -- don't understand "use only if you manually count entries?" Are they envisioning a scenario where you'd run a separate count query, then pass the result to paginate as an option? What would be the circumstances where you'd do that?

"additional options that are passed on to count" -- What options are available? "Pass on" to the count method of ???

Answer 1

The total_entries and count parameters can be used when you want to paginate different models in the same list, or if you want to perform a complex query. As long as you don't need it, don't worry about it. When you run into problems you can't seem to solve, check back.

Answer 2

By default will_paginate uses count (from ActiveRecord::Calculations) to figure out the total number of objects you're paging through. But if you know better, or straight count won't work, you can calculate and provide :total_entries yourself.

The :count parameter is for extra arguments to the ActiveRecord::Calculations#count method, like :distinct. You can look at the docs for the complete list.