# errational

Supports Rails 3 only

## Summary

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.

## Install

Add to your Gemfile:

```ruby
gem 'errational'
```

## Run Generators

```bash
$ rails generate errational:install <app_name>
```

This will generate three files, there is documentation within the generated files:
> lib/errational/<app_name>_error.rb
> lib/errational/<app_name>_exception.rb
> config/initializers/errational_configuration.rb

## Usage

This gem will generate exception classes based on the error constants defined in the generated
<app_name>_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:

```ruby
 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/<app_name>_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.


Example:

```ruby
 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
```

## Configuration

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.

Example:

``` ruby
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
```