diff options
Diffstat (limited to 'vendor/plugins/exception_notification/README')
| -rw-r--r-- | vendor/plugins/exception_notification/README | 111 |
1 files changed, 0 insertions, 111 deletions
diff --git a/vendor/plugins/exception_notification/README b/vendor/plugins/exception_notification/README deleted file mode 100644 index 9a47c41..0000000 --- a/vendor/plugins/exception_notification/README +++ /dev/null | |||
| @@ -1,111 +0,0 @@ | |||
| 1 | = Exception Notifier Plugin for Rails | ||
| 2 | |||
| 3 | The Exception Notifier plugin provides a mailer object and a default set of | ||
| 4 | templates for sending email notifications when errors occur in a Rails | ||
| 5 | application. The plugin is configurable, allowing programmers to specify: | ||
| 6 | |||
| 7 | * the sender address of the email | ||
| 8 | * the recipient addresses | ||
| 9 | * the text used to prefix the subject line | ||
| 10 | |||
| 11 | The email includes information about the current request, session, and | ||
| 12 | environment, and also gives a backtrace of the exception. | ||
| 13 | |||
| 14 | == Usage | ||
| 15 | |||
| 16 | First, include the ExceptionNotifiable mixin in whichever controller you want | ||
| 17 | to generate error emails (typically ApplicationController): | ||
| 18 | |||
| 19 | class ApplicationController < ActionController::Base | ||
| 20 | include ExceptionNotifiable | ||
| 21 | ... | ||
| 22 | end | ||
| 23 | |||
| 24 | Then, specify the email recipients in your environment: | ||
| 25 | |||
| 26 | ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bill@schmoe.com) | ||
| 27 | |||
| 28 | And that's it! The defaults take care of the rest. | ||
| 29 | |||
| 30 | == Configuration | ||
| 31 | |||
| 32 | You can tweak other values to your liking, as well. In your environment file, | ||
| 33 | just set any or all of the following values: | ||
| 34 | |||
| 35 | # defaults to exception.notifier@default.com | ||
| 36 | ExceptionNotifier.sender_address = | ||
| 37 | %("Application Error" <app.error@myapp.com>) | ||
| 38 | |||
| 39 | # defaults to "[ERROR] " | ||
| 40 | ExceptionNotifier.email_prefix = "[APP] " | ||
| 41 | |||
| 42 | Email notifications will only occur when the IP address is determined not to | ||
| 43 | be local. You can specify certain addresses to always be local so that you'll | ||
| 44 | get a detailed error instead of the generic error page. You do this in your | ||
| 45 | controller (or even per-controller): | ||
| 46 | |||
| 47 | consider_local "64.72.18.143", "14.17.21.25" | ||
| 48 | |||
| 49 | You can specify subnet masks as well, so that all matching addresses are | ||
| 50 | considered local: | ||
| 51 | |||
| 52 | consider_local "64.72.18.143/24" | ||
| 53 | |||
| 54 | The address "127.0.0.1" is always considered local. If you want to completely | ||
| 55 | reset the list of all addresses (for instance, if you wanted "127.0.0.1" to | ||
| 56 | NOT be considered local), you can simply do, somewhere in your controller: | ||
| 57 | |||
| 58 | local_addresses.clear | ||
| 59 | |||
| 60 | == Customization | ||
| 61 | |||
| 62 | By default, the notification email includes four parts: request, session, | ||
| 63 | environment, and backtrace (in that order). You can customize how each of those | ||
| 64 | sections are rendered by placing a partial named for that part in your | ||
| 65 | app/views/exception_notifier directory (e.g., _session.rhtml). Each partial has | ||
| 66 | access to the following variables: | ||
| 67 | |||
| 68 | * @controller: the controller that caused the error | ||
| 69 | * @request: the current request object | ||
| 70 | * @exception: the exception that was raised | ||
| 71 | * @host: the name of the host that made the request | ||
| 72 | * @backtrace: a sanitized version of the exception's backtrace | ||
| 73 | * @rails_root: a sanitized version of RAILS_ROOT | ||
| 74 | * @data: a hash of optional data values that were passed to the notifier | ||
| 75 | * @sections: the array of sections to include in the email | ||
| 76 | |||
| 77 | You can reorder the sections, or exclude sections completely, by altering the | ||
| 78 | ExceptionNotifier.sections variable. You can even add new sections that | ||
| 79 | describe application-specific data--just add the section's name to the list | ||
| 80 | (whereever you'd like), and define the corresponding partial. Then, if your | ||
| 81 | new section requires information that isn't available by default, make sure | ||
| 82 | it is made available to the email using the exception_data macro: | ||
| 83 | |||
| 84 | class ApplicationController < ActionController::Base | ||
| 85 | ... | ||
| 86 | protected | ||
| 87 | exception_data :additional_data | ||
| 88 | |||
| 89 | def additional_data | ||
| 90 | { :document => @document, | ||
| 91 | :person => @person } | ||
| 92 | end | ||
| 93 | ... | ||
| 94 | end | ||
| 95 | |||
| 96 | In the above case, @document and @person would be made available to the email | ||
| 97 | renderer, allowing your new section(s) to access and display them. See the | ||
| 98 | existing sections defined by the plugin for examples of how to write your own. | ||
| 99 | |||
| 100 | == Advanced Customization | ||
| 101 | |||
| 102 | By default, the email notifier will only notify on critical errors. For | ||
| 103 | ActiveRecord::RecordNotFound and ActionController::UnknownAction, it will | ||
| 104 | simply render the contents of your public/404.html file. Other exceptions | ||
| 105 | will render public/500.html and will send the email notification. If you want | ||
| 106 | to use different rules for the notification, you will need to implement your | ||
| 107 | own rescue_action_in_public method. You can look at the default implementation | ||
| 108 | in ExceptionNotifiable for an example of how to go about that. | ||
| 109 | |||
| 110 | |||
| 111 | Copyright (c) 2005 Jamis Buck, released under the MIT license \ No newline at end of file | ||
