README in egregious-0.1.0 vs README in egregious-0.1.2

- old
+ new

@@ -1,16 +1,16 @@ Egregious is a rails based exception handling gem for well defined http exception handling for json, xml and html. If you have a json or xml api into your rails application, you probably have added your own exception handling to map -exceptions to a http status and formatting your json and xml output. We did to. We were tired of doing it over and -over. We decided to create egregious. One of the major goals is to start providing a more consistent api error -experience for all rails applications. As of the creation of egregious the behavior of rails was to return html when an -exception is thrown with the status code of 500. With egregious proper json and html of the error will be returned -with a good default mapping of exceptions to http status codes. This allows api developers to respond to the status -code properly, instead of scratching their head with 500's coming back all the time. If the problem was yours then the -result codes are in the 300 range. If the problem was the server then the status codes are in the 500's. With the -message and exception type providing more context information. +exceptions to a http status and formatting your json and xml output. We decided to create egregious. One of the goals +is to start providing a more consistent api error experience for all rails applications. As of the creation of +egregious the behavior of rails was to return html when an exception is thrown with the status code of 500. With +egregious proper json and html of the error will be returned with a good default mapping of exceptions to http status +codes. This allows api developers to respond to the status code properly, instead of scratching their head with 500's +coming back all the time. If the problem was the api caller then the result codes are in the 300 range. If the problem +was on the server then the status codes are in the 500 range. The returned exception message and exception type +provide the caller context information. What egregious can do: * Defines default exception handling for most common ruby, rails, warden and cancan exceptions. (warden and cancan are optional) @@ -18,10 +18,12 @@ and well structured json, xml * For html production requests attempts to load the html error pages for the mapped status code, falling back to the 500.html page. * Defines exceptions for all http status codes allowing you to throw these exceptions anywhere in your code. * Allows you to change the exception mapping to fit your needs, adding exceptions and changing status mapping. + * If Hoptoad is defined it will send the errors to Hoptoad/Airbrake. + * The error will be logged with stack trace REQUIRES: Rails 3.x @@ -42,6 +44,39 @@ In your code if you want to send an error back just throw an exception. For example: raise Egregious::BadRequest.new("You can not created an order without a customer.") unless customer_id All the http status codes have exception classes named after them in the Egregious module. You can throw any exception, -or define your own exceptions. You can find a list in the Rack::Utils::HTTP_STATUS_CODES class. +or define your own exceptions. You can find a list in the Rack::Utils::HTTP_STATUS_CODES class. + +If you want to change the behavior then you can override the following methods in your ApplicationController. + +# override this if you want your flash to behave differently +def egregious_flash(exception) + flash.now[:alert] = exception.message +end + +# override this if you want your logging to behave differently +def egregious_log(exception) + logger.fatal( + "\n\n" + exception.class.to_s + ' (' + exception.message.to_s + '):\n ' + + clean_backtrace(exception).join("\n ") + + "\n\n") + HoptoadNotifier.notify(exception) if defined?(HoptoadNotifier) +end + +# override this if you want to change your respond_to behavior +def egregious_respond_to(exception) + respond_to do |format| + status = status_code_for_exception(exception) + format.xml { render :xml=> exception.to_xml, :status => status } + format.json { render :json=> exception.to_json, :status => status } + # render the html page for the status we are returning it exists...if not then render the 500.html page. + format.html { render :file => File.exists?(build_html_file_path(status)) ? + build_html_file_path(status) : build_html_file_path('500')} + end +end + +# override this if you want to change what html static file gets returned. +def build_html_file_path(status) + File.expand_path(Rails.root, 'public', status + '.html') + end \ No newline at end of file