errational - nice error handling
This gem will create custom Exception classes for your rails app, rescue from them whenever they are raised, and display a nice message to the user.
- Ruby 1.9+
- Rails 3+
Add to your Gemfile:
$ rails generate errational:install <app_name>
This will generate three files, there is documentation within the generated files:
lib/errational/_error.rb lib/errational/_exception.rb config/initializers/errational_configuration.rb
This gem will generate exception classes based on the error constants defined in the generated _error.rb file. It will also rescue from these custom exceptions and use the custom defined method of displaying the string of the constant to the user. It also rescues from all Exceptions and if the exception is not one of the custom exception classes, it will display the message from the ApplicationError::General::UNEXPECTED constant.
This module contains modules of error constants, from each constant an exception class will be generated. Each submodule will be created as a class; it will be used as an intermediate ancestor between the exception class and the application exception class. All error constants must be within a module.
The constant General::UNEXPECTED is special. This is the message that will be used for all exceptions that are caught that are not from the custom exception classes.
The module Loggable is a special case. All error constants defined under Loggable (they can be within submodules) will be logged using the Logger defined in the configuration.
For example, where Application is the name of the application:
module ApplicationError module General UNEXPECTED = "An error has occurred in the application. Please try again." end module Loggable SERVICE_FAULT = "The response from the service cannot be processed. Please try again" end module Serious BAD_PROBLEM = "The server is on fire, please call the fire department" end end class FirstController < ApplicationController def index raise ApplicationException::ServiceFault # Will automatically be handled by the error handling gem with corresponding message. end def create raise RuntimeError # Will automatically be handled by error handling gem with UNEXPECTED message. end def update raise ApplicationException::BadProblem rescue ApplicationException::Parent => e # Will rescue any of the exceptions generated by the plugin. if(e.is_a? ApplicationException::Serious) # Sub modules are created as ancestor classes of exceptions, useful for special casing. call_lead_developer end end end
The exception module generated into lib/errational/_exception.rb is where you can override the default behavior of exception classes or add other exception classes. The default behavior of the exception classes is to create an exception with the message of the constant. Exception classes that override generated exception classes must be defined as children of their parent module's generated class.
module ApplicationException include Errationalify class ServiceFault < Loggable def initialize(service_name) message = sprintf(ApplicationError::SERVICE_FAULT, service_name) end end end module ApplicationError module General UNEXPECTED = "An error has occurred in the application. Please try again." end module Loggable SERVICE_FAULT = "The response from %s cannot be processed. Please try again" end end
In the file generated into config/initializers/errational_configuration.rb you will find several values that are configurable.
The error partial is the path to the partial that will be rendered as the result of xhr actions that result in an exception being thrown. The default error dialog requires jQuery >= 1.5 and jQuery UI >= 1.8.9. The error dialog will be created with an id of errational_error_dialog and a class of errational_class. These can be styled.
Errational.setup do |config| # Namespace for name of exception and error modules, based on the name given at install time. # Note, if changing, change the module names in lib/namespace_error.rb and lib/namespace_exception.rb, # , as well as the filenames config.namespace = "Application" # The response code given for exceptions that are handled. config.error_response_code = 203 # The partial to be used for exceptions handled as the result of xhr actions config.error_partial = '/errational/error_dialog' # The logger to be used for NamespaceException::Loggable exceptions and unexpected exceptions config.logger = Rails.logger end
rake appraisal:install once, then use
rake appraisal to judge whether the build will pass.