Exceptionally Beautiful

A Rails engine for handling error pages.

Getting up-and-running is simple. Just use the built-in generator:

bundle exec rails g exceptionally_beautiful:install

The generator will:

• Add the route helper to config/routes.rb
• Add an initializer that you can customize in config/initializers/exceptionally_beautiful.rb
• Copy over the translation data to config/locales/exceptionally_beautiful.en.yml

Exceptionally Beautiful can handle any three-digit status code you throw at it. It comes with translation data for the following common errors:

If the default errors, controller, action, and/or layout don't suit your fancy, you can override any of them in the initializer provided by the generator:

ExceptionallyBeautiful.setup do |config|
  config.errors = [403, 404, 422, 500, 502]
  config.layout = 'errors'
  config.controller = 'exceptionally_beautiful/errors'
  config.action = 'show'
end

Important: If you want Exceptionally Beautiful to handle an error code other than the defaults specified, it must be added to config.errors.

You can customize and add new errors to the translation file copied over by the initializer (config/locales/exceptionally_beautiful.en.yml). Error codes missing translation data will fall back to default messaging.

Make sure that all new error codes in your translation file are prefixed with a :. This is needed for I18n translation lookups to work properly when using keys that are integers. See this for more information. e.g.

en:
  exceptionally_beautiful:
    default:
      title: "There's been an error"
      message: "Something has gone wrong. Please try again shortly."
    :401:
      title: "Unauthorized"
      message: "Leave and never come back!"

The message for each error can be formatted using Markdown. e.g.

  exceptionally_beautiful:
    default:
      title: "There's been an error"
      message: |
        Something has **gone wrong**. Please try again shortly.

        Or just go [back to our home page](/)...

Using Rails' rescue_from in your controllers? You can use Exceptionally Beautiful's error handler there too:

class ApplicationController < ActionController::Base
  include ExceptionallyBeautiful::ErrorHandler

  rescue_from Mongoid::Errors::DocumentNotFound do |exception|
    error_handler(404)
  end
end

This library comes with a Rake task that caches your beautiful error pages as static HTML files in your application's public folder.

bundle exec rake exceptionally_beautiful:cache

Want to cache your error pages as part of your deployment workflow? Use the included Capistrano 3 task:

# In your Capfile
require 'exceptionally_beautiful/capistrano'

# In your config/deploy.rb
after 'deploy:compile_assets', 'exceptionally_beautiful:cache'

By default, the exceptionally_beautiful:cache task is only run on servers with the :app role, however you can override that by setting the :exceptionally_beautiful_roles option.

This is by no means the first library to tackle this problem. Check out these other alternatives before deciding what to use.

• Ryan Bates' Railscast
• errship
• error_pages_engine
• dynamic_error_pages

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

bundle exec guard