Skip to content
This repository

A Rails plugin to use exceptions for generating HTTP status responses.

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 tasks
Octocat-spinner-32 .gitignore
Octocat-spinner-32 MIT-LICENSE
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 http_status_exceptions.gemspec
Octocat-spinner-32 init.rb
README.rdoc

WARNING: the gem version that Github currently serves is faulty. The issue is already fixes in the repository, but Github is not yet building new gem versions. As soon as this is fixed, I will release a new version that resolves the issue. For now, install version 0.1.5 which is unaffected:

sudo gem install wvanbergen-http_status_exceptions \
    --source http://gems.github.com --version "= 0.1.5"

HTTP status exception

This simple plugin will register exception classes for all HTTP status. These exceptions can then be raised from your controllers, after which a response will be send back to the client with the desired HTTP status, possible with some other content.

You can use this plugin to access control mechanisms. You can simply raise a HTTPStatus::Forbidden if a user is not allowed to perform a certain action. A nice looking error page will be the result. See the example below:

See the project wiki (github.com/wvanbergen/http_status_exceptions/wikis) for additional documentation.

Installation

Installation is simple. Simply add the gem in your environment.rb:

Rails::Initializer.run do |config|
  ...
  config.gem 'wvanbergen-http_status_exceptions', :lib => 'http_status_exceptions', :source => 'http://gems.github.com'
end

Run rake gems:install to install the gem if needed.

Configuration

You can modify where HTTP status exception looks for its template files like so:

class ApplicationController < ActionController::Base
  ...
  HTTPStatus::Base.template_path = 'path_to/http_status_templates'
end

You can also modify which layout is used when rendering a template by setting the template_layout:

class ApplicationController < ActionController::Base
  ...
  HTTPStatus::Base.template_layout = 'exception'
end

If you don't set a template_layout the current layout for the requested action will be used.

Usage

class BlogController < ApplicationController

  def destroy
    raise HTTPStatus::Forbidden, 'You cannot delete blogs!' unless current_user.can_delete_blogs?
    @blog.destroy
  end
end

By default, this will return an empty response with the “forbidden” status code (403). If you want to add content to the response as well, create the following view: shared/http_status/forbidden.html.erb. You can use the @exception-object in your view:

<h1>Forbidden</h1>
<p> <%= h(@exception.message) %> </p>
<hr />
<p>HTTP status code <small> <%= @exception.status_code %>: <%= @exception.status.to_s.humanize %></small></p>

The response will only be sent if the request format is HTML because of the name of the view file. In theory you could make a response for XML requests as well by using shared/http_status/forbidden.xml.builder as filename

Something went wrong with that request. Please try again.