In your app/controllers/application_controller.rb, add a history line like this:

class ApplicationController < ActionController::Base
  history :default => "http://default.url.com/",
          :max => 10
end

The history function accepts a hash of options

* :default, the default URL to redirect
* :max, the maximum locations to remember (five by defaults).

None of the parameters are required. If somebody knows of a better way to obtain the default URL, he is welcomed to tell me how.

You can use the method history_skip in your controller if you want to avoid certain location to be stored in the history. By default, action resulting from a POST, PUT, DELETE request or an Ajax request are not stored in the history.

class FooController < ApplicationController
  history_skip :action_to_skip

  def action_to_skip
    # I will not be stored in the history
  end
end

In your actions, you can then use the following methods:

* last_location: returns the last visited location, can be used with one numeric argument precising how many locations to go back in the history (1 by default),
* peek_last_location: like last_location but don't remove it from the history,
* redirect_back: redirect the user to the last location in history, it takes the same arguments as last_location,
* store_location(force = false): stores the current location in the history, set force parameter to true to store location even if it would be skipped.

Note that if you want to use the plugin to create a "back" link on a page, you must go back two times. For example, using this controller

class HistoryController < ApplicationController
  def foo
  end

  def bar
  end

  def back
    redirect_back(2)
  end  
end

I'll try to explain clearly why. Let's say that in your bar view, you create a back link wich links to the back action. Now a user visits foo then bar. What you want is your user being redirected to foo when clicking your "back" link. Now your user hits the link. The controller will call the back action. From its point of view, you are in the back action so going back one time would take you to the bar action.

There is currently no advanced documentation for this plugin.