Module | WillPaginate::ViewHelpers |
In: |
lib/will_paginate/view_helpers.rb
|
The main view helper, will_paginate, renders pagination links for the given collection. The helper itself is lightweight and serves only as a wrapper around LinkRenderer instantiation; the renderer then does all the hard work of generating the HTML.
Options for pagination helpers are optional and get their default values from the WillPaginate::ViewHelpers.pagination_options hash. You can write to this hash to override default options on the global level:
WillPaginate::ViewHelpers.pagination_options[:previous_label] = 'Previous page'
By putting this into "config/initializers/will_paginate.rb" (or simply environment.rb in older versions of Rails) you can easily translate link texts to previous and next pages, as well as override some other defaults to your liking.
Renders a helpful message with numbers of displayed vs. total entries. You can use this as a blueprint for your own, similar helpers.
<%= page_entries_info @posts %> #-> Displaying posts 6 - 10 of 26 in total
By default, the message will use the humanized class name of objects in collection: for instance, "project types" for ProjectType models. Override this with the :entry_name parameter:
<%= page_entries_info @posts, :entry_name => 'item' %> #-> Displaying items 6 - 10 of 26 in total
# File lib/will_paginate/view_helpers.rb, line 160 160: def page_entries_info(collection, options = {}) 161: entry_name = options[:entry_name] || 162: (collection.empty?? 'entry' : collection.first.class.name.underscore.sub('_', ' ')) 163: 164: if collection.total_pages < 2 165: case collection.size 166: when 0; "No #{entry_name.pluralize} found" 167: when 1; "Displaying <b>1</b> #{entry_name}" 168: else; "Displaying <b>all #{collection.size}</b> #{entry_name.pluralize}" 169: end 170: else 171: %{Displaying #{entry_name.pluralize} <b>%d - %d</b> of <b>%d</b> in total} % [ 172: collection.offset + 1, 173: collection.offset + collection.length, 174: collection.total_entries 175: ] 176: end 177: end
Wrapper for rendering pagination links at both top and bottom of a block of content.
<% paginated_section @posts do %> <ol id="posts"> <% for post in @posts %> <li> ... </li> <% end %> </ol> <% end %>
will result in:
<div class="pagination"> ... </div> <ol id="posts"> ... </ol> <div class="pagination"> ... </div>
Arguments are passed to a will_paginate call, so the same options apply. Don‘t use the :id option; otherwise you‘ll finish with two blocks of pagination links sharing the same ID (which is invalid HTML).
# File lib/will_paginate/view_helpers.rb, line 142 142: def paginated_section(*args, &block) 143: pagination = will_paginate(*args).to_s 144: content = pagination + capture(&block) + pagination 145: concat content, block.binding 146: end
Renders Digg/Flickr-style pagination for a WillPaginate::Collection object. Nil is returned if there is only one page in total; no point in rendering the pagination in that case…
Display options:
HTML options:
Advanced options:
All options not recognized by will_paginate will become HTML attributes on the container element for pagination links (the DIV). For example:
<%= will_paginate @posts, :style => 'font-size: small' %>
… will result in:
<div class="pagination" style="font-size: small"> ... </div>
If the helper is called without passing in the collection object, it will try to read from the instance variable inferred by the controller name. For example, calling will_paginate while the current controller is PostsController will result in trying to read from the @posts variable. Example:
<%= will_paginate :id => true %>
… will result in @post collection getting paginated:
<div class="pagination" id="posts_pagination"> ... </div>
# File lib/will_paginate/view_helpers.rb, line 89 89: def will_paginate(collection = nil, options = {}) 90: options, collection = collection, nil if collection.is_a? Hash 91: unless collection or !controller 92: collection_name = "@#{controller.controller_name}" 93: collection = instance_variable_get(collection_name) 94: raise ArgumentError, "The #{collection_name} variable appears to be empty. Did you " + 95: "forget to pass the collection object for will_paginate?" unless collection 96: end 97: # early exit if there is nothing to render 98: return nil unless WillPaginate::ViewHelpers.total_pages_for_collection(collection) > 1 99: 100: options = options.symbolize_keys.reverse_merge WillPaginate::ViewHelpers.pagination_options 101: if options[:prev_label] 102: WillPaginate::Deprecation::warn(":prev_label view parameter is now :previous_label; the old name has been deprecated.") 103: options[:previous_label] = options.delete(:prev_label) 104: end 105: 106: # get the renderer instance 107: renderer = case options[:renderer] 108: when String 109: options[:renderer].to_s.constantize.new 110: when Class 111: options[:renderer].new 112: else 113: options[:renderer] 114: end 115: # render HTML for pagination 116: renderer.prepare collection, options, self 117: renderer.to_html 118: end