logankoester/errship - Githubissues

= => errship

The static error pages Rails comes with are nice for getting started - you can't break them, no matter what. But without your layout and navigation wrapped around them, they create a frustrating trap for your users.

The obvious solution is to render your layout into the static file, but what happens when you make a change?

Worse, what if you run a network of many Rails applications? Should they share one error page style? Should they all have their own?

You could hire your nephew to keep them all up to date... or you can use Errship.

Errship is a Rails 3.1 engine for rendering error pages inside your layout. It supports i18n, custom exceptions, and Airbrake (Hoptoad) error tracking.

You can also use the flashback method to set an error message and redirect :back safely - if a RedirectBackError is raised, the user is dropped off at the nearest error page and given the flash message anyway.

== Installation

Add this to your Gemfile gem 'errship', '~> 2.2.0'

Add this to your ApplicationController class ApplicationController < ActionController::Base include Errship::Rescuers include Errship::ActiveRecord::Rescuers # or replace 'ActiveRecord' with MongoMapper, or Mongoid

Errship is ready to go! To test it out in development, you'll need to set

config.consider_all_requests_local = false

in your config/environments/development.rb file. Just don't forget to change it back when you want useful debugging output again instead!

Alternatively, simply point your browser to /error or /not_found to get a taste.

== Configuration

Errship renders all error pages with a HTTP status of 200 by default. This is done to ensure that the error page is rendered if the web server is configured to intercept errors (e.g. proxy_intercept_errors for nginx). If you want to have the correct status codes for your errors, add the following to an initializer:

Errship.status_code_success = false

== I18n

If you want to edit the text that is rendered, add the following to your config/locales/*.yml

en:
  errship:
    '404':
      title: 'This page does not exist.'
      description: 'It could have moved, or someone (maybe you!) mistyped the URL.'
    '500':
      title: 'An error has occurred.'
      description: 'This has been reported to our development team. Thank you!'

...and so forth, for any error code you like.

== Custom Rescuers

If you want errship to rescue errors from your own custom exception class, you need to add a custom rescuer in your ApplicationController, like so:

# Render the 404 page
rescue_from MyException::SomethingMissing, :with => :render_404_error

# Render the 500 page
rescue_from MyException::SomethingWentWrong, :with => :render_error

To customize the error for a particular controller or exception class, add a rescuer like this one:

rescue_from ActiveRecord::RecordNotFound, :with => ->(e){ render_404_error e, 'monkeys' }

and then add your text for that scope to config/locales/*.yml

en:
  errship:
    '404':
      title: 'This page does not exist.'
      description: 'It could have moved, or someone (maybe you!) mistyped the URL.'
      monkeys:
        title: 'They must have escaped'
        description: 'This is now a monkey free zone.'

The following methods are provided:

render_error(exception, errship_scope = false) # Render the 500 page
render_404_error(exception = nil, errship_scope = false) # Render the 404 page
flashback(error_message) # Set the flash and redirect back (RedirectBackError-safe)

If Airbrake is installed, every rescuer will report the exception, except for 404.

== Changelog

2.2.0

Preserve correct status codes by default (Rescuers no longer force a 200 status)

2.1.3

Conditionally loading rescuers to check for specific loading ORM

2.1.2

Remove explicit Rake version dependency for 1.8.7 compatibility

2.1.1

Gemspec update

2.1.0

Removes unnecessary dependency on HAML (using ERB instead)

2.0.1

Added tests for ActiveRecord, Mongoid and MongoMapper rescuers
Fixed Mongoid module

2.0.0

Breaks out ORM error handling into submodules. Not backwards compatible.

1.1.0

Adds option to specify a custom errship_scope to use with I18n, allowing each rescuer to customize the messages displayed.

1.0.0

Upgrade to Rails 3.1 to share error page assets between applications on the asset pipeline.
Supports Airbrake as well as HoptoadNotifier
Errors are rendered directly into your layout
i18n support
No default styles - blends seamlessly into its host layout.

== Contributing to errship

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

logankoester / errship

readme