Installation

There are four options when approaching will_paginate installation:

• use the gem (recommended);
• install as Rails plugin using git;
• download tarballs;
• export from SVN (obsolete, strongly discouraged).

Which option to choose? If not sure, install the gem. Latest RubyGems are a stable and powerful platform for managing Ruby libraries on your system. Plugin installation is only recommended for advanced developers who want to track it using a vendor branch management tool or hack its source within their application.

If you want to get the latest and greatest code but don’t have git, see below for a way to download tarballs. However, if you are a Ruby developer I strongly recommend you to have git on your system not just because of will_paginate, but because most popular Ruby projects (including Rails) are now developed using git and hosted on GitHub.

Also:

• See the troubleshooting section.
• Read about the internals if you’re interested what happens when the library loads.
• Report bugs.

Using Rails 2.1 gem dependencies

To enable the library your Rails 2.1 (or greater) project, use the gem configuration method in “config/environment.rb”

Rails::Initializer.run do |config|
  config.gem 'mislav-will_paginate', :version => '~> 2.3.8', :lib => 'will_paginate', 
    :source => 'http://gems.github.com'
end

To install this gem (and all other missing gem dependencies), run rake gems:install (use sudo if necessary).

Installing the gem manually

First, ensure that you’re running at least RubyGems 1.2 (check gem -v if you’re not sure).

The will_paginate gem is built by GitHub. Add GitHub to your gem sources (once per machine):

gem sources -a http://gems.github.com

Install the library:

gem install mislav-will_paginate

To enable the library your Rails 2.0.x (or even 1.2.x) project, load it in “config/environment.rb”

Rails::Initializer.run do |config|
  ...
end

require "will_paginate" 

Don’t put it before or inside the Rails::Initializer block because the Rails framework is not yet loaded at that point of execution.

That will always load the latest installed version of the gem. If you want to have control of the version loaded, you can use version constraints with the gem method:

# choose one of the following constraints:
gem 'mislav-will_paginate', '2.1.0'
gem 'mislav-will_paginate', '>=2.1.0'
gem 'mislav-will_paginate', '~>2.1' # this will load any 2.x version
                                    # (greater or equal to 2.1), but not 3.x

# finally, load the library
require 'will_paginate'

Install as plugin using git

To continuously track will_paginate development, it’s probably best to install it as a plugin using some vendor branch management tool like Braid:

gem install evilchelu-braid

Using Braid to add a Rails plugin is simple:

# (make sure you've commited everything first)
braid add git://github.com/mislav/will_paginate.git -p

# braid performs its thing in "braids/track" branch;
# merge it in your master branch like so:
git merge braid/track

# now you should have the library in vendor/plugins/will_paginate

Alternative to Braid: if you’re using Rails 2.1, you can simply use “script/plugin”. It will export all the code from GitHub into “vendor/plugins”

script/plugin install git://github.com/mislav/will_paginate.git

Export from GitHub as tarballs

Here is the download link for the latest state of the will_paginate master branch (.tar.gz archive). You can extract it into “vendor/plugins” directory manually (and rename it to “will_paginate”), or you could paste this in the console on a -nix system (requires wget):

mkdir vendor/plugins/will_paginate
wget -nv http://github.com/mislav/will_paginate/tarball/master -O- | \
  tar xzv -C vendor/plugins/will_paginate --strip 1

wget http://github.com/mislav/will_paginate/tarball/master
then untar/zip it, drop it in vendor/plugins/will_paginate

sake -i http://pastie.org/161203.txt
sake will_paginate:install

To update the plugin (and you should do that regularly!), just repeat the above command (without mkdir). That will extract new files over the old ones. Or, you could use the above Sake task. It will not remove files that are no longer used, however. You can always make a clean install: remove “vendor/plugins/will_paginate” and start over from the top.

Using SVN

Using SVN is not recommended anymore. The SVN repository contains stale code, isn’t used and will be deleted in near future. You should either switch to using the gem version, downloading tarballs (described above) or tracking the new repository with git. The old SVN repository is at svn://errtheblog.com/svn/plugins/will_paginate.