diff --git a/CHANGELOG.rdoc b/CHANGELOG.rdoc index 590d07323..305440647 100644 --- a/CHANGELOG.rdoc +++ b/CHANGELOG.rdoc @@ -1,4 +1,4 @@ -= 2.3.16 += 2.3.16, released 2011-08-09 * added global WillPaginate.per_page = 30 setting * added i18n capabilities to previous/next labels and page_entries_info diff --git a/README.md b/README.md new file mode 100644 index 000000000..aae1b28db --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +# will_paginate + +will_paginate v2.3 is a pagination plugin for Rails and Active Record. + +Installation: + +~~~ ruby +## environment.rb +Rails::Initializer.run do |config| + config.gem 'will_paginate', :version => '~> 2.3.16' +end +~~~ + +See [installation instructions][install] on the wiki for more info. + + +## Basic will_paginate use + +~~~ ruby +## perform a paginated query: +@posts = Post.paginate(:page => params[:page]) + +# or, use an explicit "per page" limit: +Post.paginate(:page => params[:page], :per_page => 30) + +## render page links in the view: +<%= will_paginate @posts %> +~~~ + +And that's it! You're done. You just need to add some CSS styles to [make those pagination links prettier][css]. + +You can customize the default "per_page" value: + +~~~ ruby +# for the Post model +class Post + self.per_page = 10 +end + +# set per_page globally +WillPaginate.per_page = 10 +~~~ + +See [the wiki][wiki] for more documentation. [Ask on the group][group] if you have usage questions. [Report bugs][issues] on GitHub. + +Happy paginating. + + +[wiki]: https://github.com/mislav/will_paginate/wiki +[install]: https://github.com/mislav/will_paginate/wiki/Installation "will_paginate installation" +[group]: http://groups.google.com/group/will_paginate "will_paginate discussion and support group" +[issues]: https://github.com/mislav/will_paginate/issues +[css]: http://mislav.uniqpath.com/will_paginate/ diff --git a/README.rdoc b/README.rdoc deleted file mode 100644 index 017fd73db..000000000 --- a/README.rdoc +++ /dev/null @@ -1,103 +0,0 @@ -= WillPaginate - -Pagination is just limiting the number of records displayed. Why should you let -it get in your way while developing, then? This plugin makes magic happen. Did -you ever want to be able to do just this on a model: - - Post.paginate :page => 1, :order => 'created_at DESC' - -... and then render the page links with a single view helper? Well, now you -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]. -* {How to report bugs}[http://github.com/mislav/will_paginate/wikis/report-bugs] - - -== Example usage - -Use a paginate finder in the controller: - - @posts = Post.paginate_by_board_id @board.id, :page => params[:page], :order => 'updated_at DESC' - -Yeah, +paginate+ works just like +find+ -- it just doesn't fetch all the -records. Don't forget to tell it which page you want, or it will complain! -Read more on WillPaginate::Finder::ClassMethods. - -Render the posts in your view like you would normally do. When you need to render -pagination, just stick this in: - - <%= will_paginate @posts %> - -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 per_page class method. You can set a custom value like this: - - class Post < ActiveRecord::Base - self.per_page = 10 - end - -... or don't worry about it at all. WillPaginate defines it to be 30 by default. -You can always specify the count explicitly when calling +paginate+: - - @posts = Post.paginate :page => params[:page], :per_page => 10 - -You can also set `per_page` globally, which will affect all models that haven't got a -custom value. Use this if you're unhappy with 30 as the default: - - WillPaginate.per_page = 10 - -The +paginate+ finder wraps the original finder and returns your resultset that now has -some new properties. You can use the collection as you would with any ActiveRecord -resultset. WillPaginate view helpers also need that object to be able to render pagination: - -
    - <% for post in @posts -%> -
  1. Render `post` in some nice way.
    2. - <% end -%> -
- -

Now let's render us some pagination!

- <%= will_paginate @posts %> - -More detailed documentation: - -* WillPaginate::Finder::ClassMethods for pagination on your models; -* WillPaginate::ViewHelpers for your views. - - -== Authors and credits - -Authors:: Mislav Marohnić, PJ Hyett -Original announcement:: http://errtheblog.com/post/929 -Original PHP source:: http://www.strangerstudios.com/sandbox/pagination/diggstyle.php - -All these people helped making will_paginate what it is now with their code -contributions or just simply awesome ideas: - -Chris Wanstrath, Dr. Nic Williams, K. Adam Christensen, Mike Garey, Bence -Golda, Matt Aimonetti, Charles Brian Quinn, Desi McAdam, James Coglan, Matijs -van Zuijlen, Maria, Brendan Ribera, Todd Willey, Bryan Helmkamp, Jan Berkel, -Lourens Naudé, Rick Olson, Russell Norris, Piotr Usewicz, Chris Eppstein, -Denis Barushev, Ben Pickles. - - -== Usable pagination in the UI - -There are some CSS styles to get you started in the "examples/" directory. They -are {showcased online here}[http://mislav.uniqpath.com/will_paginate/]. - -More reading about pagination as design pattern: - -* {Pagination 101}[https://gist.github.com/622561] -* {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]. - diff --git a/lib/will_paginate/version.rb b/lib/will_paginate/version.rb index b7de1ad36..30ac11041 100644 --- a/lib/will_paginate/version.rb +++ b/lib/will_paginate/version.rb @@ -2,7 +2,7 @@ module WillPaginate module VERSION MAJOR = 2 MINOR = 3 - TINY = 15 + TINY = 16 STRING = [MAJOR, MINOR, TINY].join('.') end diff --git a/will_paginate.gemspec b/will_paginate.gemspec index 1bf3c263e..cd2c2bcfa 100644 --- a/will_paginate.gemspec +++ b/will_paginate.gemspec @@ -5,15 +5,15 @@ Gem::Specification.new do |gem| gem.name = 'will_paginate' gem.version = WillPaginate::VERSION::STRING - gem.summary = "Pagination for Rails" - gem.description = "The will_paginate library provides a simple, yet powerful and extensible API for ActiveRecord pagination and rendering of pagination links in ActionView templates." + gem.summary = "Easy pagination for Rails" + gem.description = "will_paginate provides a simple API for Active Record pagination and rendering of pagination links in Rails templates." gem.authors = ['Mislav Marohnić', 'PJ Hyett'] gem.email = 'mislav.marohnic@gmail.com' - gem.homepage = 'http://github.com/mislav/will_paginate/wikis' + gem.homepage = 'https://github.com/mislav/will_paginate/wiki' - gem.rdoc_options = ['--main', 'README.rdoc', '--charset=UTF-8'] - gem.extra_rdoc_files = ['README.rdoc', 'LICENSE', 'CHANGELOG.rdoc'] + gem.rdoc_options = ['--main', 'README.md', '--charset=UTF-8'] + gem.extra_rdoc_files = ['README.md', 'LICENSE', 'CHANGELOG.rdoc'] gem.files = Dir['Rakefile', '{bin,lib,rails,test,spec}/**/*', 'README*', 'LICENSE*'] & `git ls-files -z`.split("\0") end