Installation

There are four options:

• use the gem version (recommended);
• install as Rails plugin using git;
• download tarballs;
• export from SVN (old way, not recommended).

Read about the internals if you’re interested what happens when the library loads.

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.2', :lib => 'will_paginate', 
    :source => 'http://gems.github.com'
end

To install this gem (and all other missing gem dependencies), run rake gems:install (sudo might be required).

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 it 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:

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

This process is available as a Sake task.

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. 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.