CHANGELOG.rdoc @@ -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]. README.rdoc @@ -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'). Rakefile @@ -9,29 +9,29 @@ require 'active_support' # 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 @@ module WillPaginate 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 @@ module WillPaginate 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) lib/will_paginate.rb @@ -33,12 +33,12 @@ module WillPaginate # # 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 @@ module WillPaginate # 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 @@ module WillPaginate 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 lib/will_paginate/collection.rb @@ -94,8 +94,8 @@ module WillPaginate # 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 lib/will_paginate/finder.rb @@ -3,20 +3,21 @@ require 'will_paginate/core_ext' 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 WillPaginate # 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 @@ module WillPaginate # # 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 @@ module WillPaginate 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: lib/will_paginate/view_helpers.rb CHANGELOG 9a93720c9f27c763ed58ec3a4d3a2e6b1a02379f Mislav Marohnić mislav.marohnic@gmail.com http://github.com/agile/will_paginate/commit/48d409a2f4d1ff11021aab217791b818703a8c59 48d409a2f4d1ff11021aab217791b818703a8c59 2008-08-13T16:22:44-07:00 2008-08-13T16:22:44-07:00 RDoc love (now live at http://mislav.caboo.se/static/will_paginate/doc/) 01917c72464d5d34e8f47abc798177c12bea3d93 Mislav Marohnić mislav.marohnic@gmail.com