Installation and Basic Usage

Installation

This plugin is made available as a gem, which can simply be dropped in to your existing Rails 3 application. Simply add gem "http_status_exceptions" to you Gemfile and you’re all set. Once the plugin is installed, it will register a list of exceptions that you can raise in your controller code. See Available Exceptions for the actual list of exceptions and their corresponding status codes.

Basic Usage

You can simply raise an HTTPStatus-exception as soon as the normal execution of your code should stop.

class BlogController < ApplicationController
  def destroy
    raise HTTPStatus::Forbidden, "You cannot delete blogs!" unless user.admin?

    @blog = Blog.find(params[:id])    
    @blog.destroy
    ...
  end
end

Raising exceptions works just as well in a before_filter:

class ApplicationController < ActionController::Base
  before_filter :set_current_user

  def set_current_user
    @user = User.find(session[:user_id)
    raise HTTPStatus::PaymentRequired, "Your account is expired" if @user.is_expired?
  end
end

You can provide some additional details to the exception as well by passing an additional argument when the exception is raised. This argument can be used later on in the exception handler using the details accessor on the exception object.

begin
  raise HTTPStatus::Forbidden.new("message", :restricted_object => @blog)
rescue HTTPStatus::Base => e
  logger.error e.details[:restricted_object].inspect
end

Displaying an error page

Once an HTTPStatus exception is raised, the default the default behavior is to return an empty response with the HTTP status code corresponding to the exception raised. You may render a custom view by creating a template for that particular exception.

For instance, to create an error page for the HTTPStatus::NotFound (404) exception, you should create a template file with the following name: app/views/shared/http_status/not_found.html.erb. The current layout will be applied to the template. The view file could look something like this:

<h1>Not found</h1>
<p>The resource you requested could not be found!</p>
<p style="color:red"><%= h(@exception.message) %></p>
<hr>
<p><small>HTTP status <%= @exception.status_code %></small></p>

Note that by using the .html.erb extension, this template will only be used for HTML formatted requests; if the same exception is raised with XML as format, the response will remain empty. In theory, you could create the file app/views/shared/http_status/not_found.xml.builder to generate an error page for XML requests. A template file without a format extension, i.e. app/views/shared/http_status/not_found.erb, will be used for any format. This is basically the same way Rails handles templates.

This simple exception handler should be sufficient for most situations. However, it is easy to customize the exception handler to your own liking. See Customization for details.