Module | WillPaginate::ViewHelpers |
In: |
lib/will_paginate/view_helpers.rb
|
Currently there is only one view helper: will_paginate. It renders the pagination links for the given collection. The helper itself is lightweight and serves only as a wrapper around link renderer 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[:prev_label] = 'Previous page'
By putting this into your environment.rb 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 to your liking 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 150 150: def page_entries_info(collection, options = {}) 151: entry_name = options[:entry_name] || 152: (collection.empty?? 'entry' : collection.first.class.name.underscore.sub('_', ' ')) 153: 154: if collection.total_pages < 2 155: case collection.size 156: when 0; "No #{entry_name.pluralize} found" 157: when 1; "Displaying <b>1</b> #{entry_name}" 158: else; "Displaying <b>all #{collection.size}</b> #{entry_name.pluralize}" 159: end 160: else 161: %{Displaying #{entry_name.pluralize} <b>%d - %d</b> of <b>%d</b> in total} % [ 162: collection.offset + 1, 163: collection.offset + collection.length, 164: collection.total_entries 165: ] 166: end 167: 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 132 132: def paginated_section(*args, &block) 133: pagination = will_paginate(*args).to_s 134: content = pagination + capture(&block) + pagination 135: concat content, block.binding 136: 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…
All options beside listed ones are passed as HTML attributes to the container element for pagination links (the DIV). For example:
<%= will_paginate @posts, :id => 'wp_posts' %>
… will result in:
<div class="pagination" id="wp_posts"> ... </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 83 83: def will_paginate(collection = nil, options = {}) 84: options, collection = collection, nil if collection.is_a? Hash 85: unless collection or !controller 86: collection_name = "@#{controller.controller_name}" 87: collection = instance_variable_get(collection_name) 88: raise ArgumentError, "The #{collection_name} variable appears to be empty. Did you " + 89: "forget to pass the collection object for will_paginate?" unless collection 90: end 91: # early exit if there is nothing to render 92: return nil unless WillPaginate::ViewHelpers.total_pages_for_collection(collection) > 1 93: 94: options = options.symbolize_keys.reverse_merge WillPaginate::ViewHelpers.pagination_options 95: 96: # get the renderer instance 97: renderer = case options[:renderer] 98: when String 99: options[:renderer].to_s.constantize.new 100: when Class 101: options[:renderer].new 102: else 103: options[:renderer] 104: end 105: # render HTML for pagination 106: renderer.prepare collection, options, self 107: renderer.to_html 108: end