Skip to content

Latest commit

 

History

History
150 lines (94 loc) · 5.39 KB

README.md

File metadata and controls

150 lines (94 loc) · 5.39 KB
Raw

Rambulance build Gem Version

A simple and safe way to dynamically render error pages for Rails apps.

Features

Simple and Safe

Rambulance's exceptions app is simple, skinny and well-tested. It inherits from ActionController::Base, so it works fine even if your ApplicationController has an issue.

Flexible

You have full control of which error page to show for a specific exception. It also json rendering (perfect for API apps). It even provides a way to create a custom exceptions app.

Easy installation and development

You don't have to configure things that every single person has to do and Rambulance does everything for you.

Installation and Usage

Add this line to your application's Gemfile:

gem 'rambulance'

And then execute:

$ rails g rambulance:install

Rambulance's generator can only generate erb templates. If you want to use haml or slim templates, please see How to Convert Your .erb to .slim or html2haml.

Now you can start editing templates like app/views/errors/not_found.html.erb. Edit, run rails server and open localhost:3000/rambulance/not_found!

Setting Pairs of Exceptions and HTTP Statuses

Open config/initializers/rambulance.rb and to configure the list of pairs of exception/corresponding http status. For example, if you want to display:

  • 422(unprocessable entity) for ActiveRecord::RecordNotUnique
  • 403(forbidden) for CanCan::AccessDenied
  • 404(not found) for YourCustomException

Then do the following:

# config/initializers/rambulance.rb
config.rescue_responses = {
  "ActiveRecord::RecordNotUnique" => :unprocessable_content,
  "CanCan::AccessDenied"          => :forbidden,
  "YourCustomException"           => :not_found
}

Special case unprocessable_entity/unprocessable_content (HTTP Status 422)

Rack renamed unprocessable_entity to unprocessable_content.

Rambulance supports both, but defaults to unprocessable_content with version 3.2.0 and later. unprocessable_entity is supported with a redirect to unprocessable_content.

This means the view file is called app/views/errors/unprocessable_content.html.erb, not app/views/errors/unprocessable_entity.html.erb.

Local Development

Open localhost:3000/rambulance/*** in Your Browser

Just open one of the error pages via Rambulance:

This is useful when you want to edit templates without changing Rails configuration.

Set consider_all_requests_local to false

Change config.consider_all_requests_local to false in config/environments/development.rb.

config.consider_all_requests_local = false

This simulates how your production app displays error pages so you can actually raise an exception in your app and see how it works. Don't forget to change consider_all_requests_local back to true after you tried this strategy.

Custom Exceptions App

If you want to do some more things in a exceptions app, you can also write your own custom exceptions app:

$ rails g rambulance:exceptions_app

It will generate your own custom exceptions app. You can use most techniques you want to use in controllers like before_filter and rendering views since it's a grandchild of ActionController::Base! However there are still some restrictions, e.g. setting a flash notice works when rendering directly but not when redirecting because the ActionDispatch::Flash middleware is never hit.

Heavily customizing the exceptions app is strongly discouraged as there would be no guard against bugs that occur in the exceptions app.

Testing

Rambulance ships with a test helper that allows you to test an error page generated by Rails. All you have to do is to include Rambulance::TestHelper and you will be able to use the with_exceptions_app DSDL:

Rspec:

include Rambulance::TestHelper

it "shows an error page" do
  with_exceptions_app do
    get '/does_not_exist'
  end

  assert_equal 404, response.status
end

Minitest:

include Rambulance::TestHelper

test "it shows an error page" do
  with_exceptions_app do
    get '/does_not_exist'
  end

  assert_equal 404, response.status
end

Note that testing error pages is not encouraged in Rails as it leads to overuse of the rescue_from DSL in controllers.

Supported Versions

  • Ruby 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3 and JRuby 9.3, 9.4
  • Rails 4.2, 5.0, 5.1, 5.2, 6.0, 6.1, 7.0, 7.1 and edge

Rambulance doesn't work with Rails 3.1 and below since they don't provide a way to use a custom exceptions app.

Contributing

  1. Fork it ( https://github.com/yuki24/rambulance/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License

Copyright (c) 2014-2015 Yuki Nishijima. See LICENSE.txt for further details.