Permalink
Browse files

RDoc love (now live at http://mislav.caboo.se/static/will_paginate/doc/)

  • Loading branch information...
1 parent 9a93720 commit 48d409a2f4d1ff11021aab217791b818703a8c59 @mislav committed Aug 13, 2008
@@ -1,5 +1,7 @@
== master
+* Rename :prev_label to :previous_label for consistency. Old name still
+ functions, but it's deprecated
* ActiveRecord 2.1: remove :include from count query when tables are not
referenced in :conditions
View
@@ -11,32 +11,11 @@ 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].
-* The will_paginate project page: http://github.com/mislav/will_paginate
-* How to report bugs: http://github.com/mislav/will_paginate/wikis/report-bugs
-* Ryan Bates made an awesome screencast[http://railscasts.com/episodes/51],
- check it out.
-
-== Installation
-
-The recommended way is that you get the gem:
-
- gem install mislav-will_paginate --source http://gems.github.com/
-
-After that you don't need the will_paginate <i>plugin</i> in your Rails
-application anymore. Just add a simple require to the end of
-"config/environment.rb":
-
- gem 'mislav-will_paginate', '~> 2.2'
- require 'will_paginate'
-
-That's it. Remember to install the gem on <b>all</b> machines that you are
-deploying to.
-
-<i>There are extensive
-{installation instructions}[http://github.com/mislav/will_paginate/wikis/installation]
-on {the wiki}[http://github.com/mislav/will_paginate/wikis].</i>
+* {How to report bugs}[http://github.com/mislav/will_paginate/wikis/report-bugs]
== Example usage
@@ -54,8 +33,7 @@ pagination, just stick this in:
<%= will_paginate @posts %>
-You're done. (Copy and paste the example fancy CSS styles from the bottom.) You
-can find the option list at WillPaginate::ViewHelpers.
+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:
@@ -115,16 +93,13 @@ Lourens Naudé, Rick Olson, Russell Norris, Piotr Usewicz, Chris Eppstein.
== Usable pagination in the UI
There are some CSS styles to get you started in the "examples/" directory. They
-are showcased in the <b>"examples/index.html"</b> file.
+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
+* {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].
View
@@ -14,7 +14,7 @@ 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.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG.rdoc').
include('lib/**/*.rb').
exclude('lib/will_paginate/named_scope*').
exclude('lib/will_paginate/array.rb').
View
@@ -9,29 +9,29 @@
# Happy paginating!
module WillPaginate
class << self
- # shortcut for <tt>enable_actionpack; enable_activerecord</tt>
+ # shortcut for <tt>enable_actionpack</tt> and <tt>enable_activerecord</tt> combined
def enable
enable_actionpack
enable_activerecord
end
- # mixes in WillPaginate::ViewHelpers in ActionView::Base
+ # hooks WillPaginate::ViewHelpers into ActionView::Base
def enable_actionpack
return if ActionView::Base.instance_methods.include? 'will_paginate'
require 'will_paginate/view_helpers'
- ActionView::Base.class_eval { include ViewHelpers }
+ ActionView::Base.send :include, ViewHelpers
if defined?(ActionController::Base) and ActionController::Base.respond_to? :rescue_responses
ActionController::Base.rescue_responses['WillPaginate::InvalidPage'] = :not_found
end
end
- # mixes in WillPaginate::Finder in ActiveRecord::Base and classes that deal
+ # hooks WillPaginate::Finder into ActiveRecord::Base and classes that deal
# with associations
def enable_activerecord
return if ActiveRecord::Base.respond_to? :paginate
require 'will_paginate/finder'
- ActiveRecord::Base.class_eval { include Finder }
+ ActiveRecord::Base.send :include, Finder
# support pagination on associations
a = ActiveRecord::Associations
@@ -41,10 +41,8 @@ def enable_activerecord
classes << a::HasManyThroughAssociation
end
}.each do |klass|
- klass.class_eval do
- include Finder::ClassMethods
- alias_method_chain :method_missing, :paginate
- end
+ klass.send :include, Finder::ClassMethods
+ klass.class_eval { alias_method_chain :method_missing, :paginate }
end
end
@@ -61,13 +59,11 @@ def enable_named_scope(patch = true)
require 'will_paginate/named_scope'
require 'will_paginate/named_scope_patch' if patch
- ActiveRecord::Base.class_eval do
- include WillPaginate::NamedScope
- end
+ ActiveRecord::Base.send :include, WillPaginate::NamedScope
end
end
- module Deprecation #:nodoc:
+ module Deprecation # :nodoc:
extend ActiveSupport::Deprecation
def self.warn(message, callstack = caller)
@@ -33,12 +33,12 @@ def initialize(page, page_num)
#
# 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 "will_paginate" gem:
+ # make your plugin/gem dependant on the "mislav-will_paginate" gem:
#
- # gem 'will_paginate'
+ # gem 'mislav-will_paginate'
# require 'will_paginate/collection'
#
- # # now use WillPaginate::Collection directly or subclass it
+ # # WillPaginate::Collection is now available for use
class Collection < Array
attr_reader :current_page, :per_page, :total_entries, :total_pages
@@ -98,7 +98,7 @@ def out_of_bounds?
# 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
- # besides your records: simply start with offset + 1.
+ # side by side with records in the view: simply start with offset + 1.
def offset
(current_page - 1) * per_page
end
@@ -112,7 +112,8 @@ def previous_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
@@ -94,8 +94,8 @@ def paginate(*args, &block)
# You can specify a starting page with <tt>:page</tt> (default is 1). Default
# <tt>:order</tt> is <tt>"id"</tt>, override if necessary.
#
- # See http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord where
- # Jamis Buck describes this and also uses a more efficient way for MySQL.
+ # See {Faking Cursors in ActiveRecord}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
+ # where Jamis Buck describes this and a more efficient way for MySQL.
def paginated_each(options = {}, &block)
options = { :order => 'id', :page => 1 }.merge options
options[:page] = options[:page].to_i
@@ -3,20 +3,21 @@
module WillPaginate
# = Will Paginate view helpers
#
- # Currently there is only one view helper: +will_paginate+. It renders the
+ # 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 link renderer instantiation; the
+ # and serves only as a wrapper around LinkRenderer instantiation; the
# renderer then does all the hard work of generating the HTML.
#
# == Global options for helpers
#
# 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
+ # <tt>WillPaginate::ViewHelpers.pagination_options</tt> 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 your environment.rb you can easily translate link texts to previous
+ # 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.
module ViewHelpers
# default options that can be overridden on the global level
@@ -40,32 +41,37 @@ module ViewHelpers
# rendering the pagination in that case...
#
# ==== Options
- # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
+ # Display options:
# * <tt>:previous_label</tt> -- default: "« Previous"
# * <tt>:next_label</tt> -- default: "Next »"
+ # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
# * <tt>:inner_window</tt> -- how many links are shown around the current page (default: 4)
# * <tt>:outer_window</tt> -- how many links are around the first and the last page (default: 1)
# * <tt>:separator</tt> -- string separator for page HTML elements (default: single space)
- # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
- # * <tt>:params</tt> -- additional parameters when generating pagination links
- # (eg. <tt>:controller => "foo", :action => nil</tt>)
- # * <tt>:renderer</tt> -- class name, class or instance of a link renderer (default:
- # <tt>WillPaginate::LinkRenderer</tt>)
- # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
+ #
+ # HTML options:
+ # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
# * <tt>:container</tt> -- toggles rendering of the DIV container for pagination links, set to
# false only when you are rendering your own pagination markup (default: true)
# * <tt>:id</tt> -- HTML ID for the container (default: nil). Pass +true+ to have the ID
# automatically generated from the class name of objects in collection: for example, paginating
# ArticleComment models would yield an ID of "article_comments_pagination".
#
- # All options beside listed ones are passed as HTML attributes to the container
+ # Advanced options:
+ # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
+ # * <tt>:params</tt> -- additional parameters when generating pagination links
+ # (eg. <tt>:controller => "foo", :action => nil</tt>)
+ # * <tt>:renderer</tt> -- class name, class or instance of a link renderer (default:
+ # <tt>WillPaginate::LinkRenderer</tt>)
+ #
+ # 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, :id => 'wp_posts' %>
+ # <%= will_paginate @posts, :style => 'font-size: small' %>
#
# ... will result in:
#
- # <div class="pagination" id="wp_posts"> ... </div>
+ # <div class="pagination" style="font-size: small"> ... </div>
#
# ==== Using the helper without arguments
# If the helper is called without passing in the collection object, it will
@@ -147,7 +153,7 @@ def paginated_section(*args, &block)
#
# 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 <tt>:entry_name</tt> parameter:
+ # Override this with the <tt>:entry_name</tt> parameter:
#
# <%= page_entries_info @posts, :entry_name => 'item' %>
# #-> Displaying items 6 - 10 of 26 in total
@@ -187,7 +193,7 @@ def total_pages; page_count; end
end
# This class does the heavy lifting of actually building the pagination
- # links. It is used by +will_paginate+ helper internally.
+ # links. It is used by the <tt>will_paginate</tt> helper internally.
class LinkRenderer
# The gap in page links is represented by:

0 comments on commit 48d409a

Please sign in to comment.