vendor/rails/railties/doc/guides/source/actioncontroller_basics/rescue.txt

   1 == Rescue ==
   2
   3 Most likely your application is going to contain bugs or otherwise throw an exception that needs to be handled. For example, if the user follows a link to a resource that no longer exists in the database, Active Record will throw the ActiveRecord::RecordNotFound exception. Rails' default exception handling displays a 500 Server Error message for all exceptions. If the request was made locally, a nice traceback and some added information gets displayed so you can figure out what went wrong and deal with it. If the request was remote Rails will just display a simple "500 Server Error" message to the user, or a "404 Not Found" if there was a routing error or a record could not be found. Sometimes you might want to customize how these errors are caught and how they're displayed to the user. There are several levels of exception handling available in a Rails application:
   4
   5 === The Default 500 and 404 Templates ===
   6
   7 By default a production application will render either a 404 or a 500 error message. These messages are contained in static HTML files in the `public` folder, in `404.html` and `500.html` respectively. You can customize these files to add some extra information and layout, but remember that they are static; i.e. you can't use RHTML or layouts in them, just plain HTML.
   8
   9 === `rescue_from` ===
  10
  11 If you want to do something a bit more elaborate when catching errors, you can use `rescue_from`, which handles exceptions of a certain type (or multiple types) in an entire controller and its subclasses. When an exception occurs which is caught by a +rescue_from+ directive, the exception object is passed to the handler. The handler can be a method or a Proc object passed to the `:with` option. You can also use a block directly instead of an explicit Proc object.
  12
  13 Here's how you can use +rescue_from+ to intercept all ActiveRecord::RecordNotFound errors and do something with them.
  14
  15 [source, ruby]
  16 -----------------------------------
  17 class ApplicationController < ActionController::Base
  18
  19   rescue_from ActiveRecord::RecordNotFound, :with => :record_not_found
  20
  21 private
  22
  23   def record_not_found
  24     render :text => "404 Not Found", :status => 404
  25   end
  26
  27 end
  28 -----------------------------------
  29
  30 Of course, this example is anything but elaborate and doesn't improve on the default exception handling at all, but once you can catch all those exceptions you're free to do whatever you want with them. For example, you could create custom exception classes that will be thrown when a user doesn't have access to a certain section of your application:
  31
  32 [source, ruby]
  33 -----------------------------------
  34 class ApplicationController < ActionController::Base
  35
  36   rescue_from User::NotAuthorized, :with => :user_not_authorized
  37
  38 private
  39
  40   def user_not_authorized
  41     flash[:error] = "You don't have access to this section."
  42     redirect_to :back
  43   end
  44
  45 end
  46
  47 class ClientsController < ApplicationController
  48
  49   # Check that the user has the right authorization to access clients.
  50   before_filter :check_authorization
  51
  52   # Note how the actions don't have to worry about all the auth stuff.
  53   def edit
  54     @client = Client.find(params[:id])
  55   end
  56
  57 private
  58
  59   # If the user is not authorized, just throw the exception.
  60   def check_authorization
  61     raise User::NotAuthorized unless current_user.admin?
  62   end
  63
  64 end
  65 -----------------------------------
  66
  67 NOTE: Certain exceptions are only rescuable from the ApplicationController class, as they are raised before the controller gets initialized and the action gets executed. See Pratik Naik's link:http://m.onkey.org/2008/7/20/rescue-from-dispatching[article] on the subject for more information.