# Whoopsie

**Version: 0.0.2**

A wrapper for ExceptionNotifier and TraceKit, especially suited for Rails apps.

This ***Rails engine*** was originally written by [Wojtek Kruszewski](https://github.com/OXOS/whoopsie).

RSpec tests, minimal documentation (below), and some cleanup by [Midwire](https://github.com/midwire)

Whoopsie wraps [ExceptionNotification](https://github.com/midwire/exception_notification) to handle notifications for JavaScript errors as well as back-end errors.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'whoopsie'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install whoopsie

## Usage

### Rails Usage

#### Configuration

Enable it in `config/application.rb`: 

    config.whoopsie.enable        = true
    config.whoopsie.email_prefix  = '[ERROR] ' # optional
    config.whoopsie.recipients    = ['me@example.com', 'you@example.com']
    config.whoopsie.sender        = 'notifications@example.com'
    config.ignored_exceptions += %w{ActionView::TemplateError CustomError} # optional

...or in any initializer (example: `config/initializers/whoopsie.rb`):

    Rails.application.config.whoopsie.enable        = true
    Rails.application.config.whoopsie.email_prefix  = '[ERROR] ' # optional
    Rails.application.config.whoopsie.recipients    = ['me@example.com', 'you@example.com']
    Rails.application.config.whoopsie.sender        = 'notifications@example.com'
    Rails.application.config.ignored_exceptions += %w{ActionView::TemplateError CustomError} # optional

You can ignore certain exceptions if you don't want to be notified for them.

    config.ignored_exceptions += %w{ActionView::TemplateError CustomError}

ActiveRecord::RecordNotFound, AbstractController::ActionNotFound and ActionController::RoutingError are ignored by default.

Add a condition to determine when an exception must be ignored or not. The `ignore_if` method can be invoked multiple times to add extra conditions.

    config.ignore_if do |exception, options|
      ! Rails.application.config.whoopsie.enable
    end

##### Additional Notifiers

The Email notifier is configured automatically when you configure Whoopsie as above.

Add additional notifiers just like you normally would for [ExceptionNotification](https://github.com/midwire/exception_notification). For example, to add a Slack channel notification:

    Rails.application.config.middleware.use(
      ExceptionNotification::Rack,
      :slack => {
        :webhook_url => 'YOUR_SLACK_WEBHOOK_URL_GOES_HERE',
        :channel => '#my_app_channel',
        :additional_parameters => {
          :icon_url => 'https://myapp.com/assets/logo-square.png',
          :mrkdwn => true
        }
      }
    )

#### Usage

Exceptions will be automatically caught and notifications sent using the configured notifiers. You can also handle exceptions explicitly:

    def my_method
      raise 'oh noes!'
    rescue SomeError => err
      Whoopsie.handle_exception(
        err,
        data: {
          id: 'whatever',
          another_thing: 'something else',
          errors: %w(array of things)
        }
      )
    end

Wrap code for protection:

    Whoopsie.report_and_swallow do
      # Do something risky...
    end

### Javascript Usage

Require it in your JS

    # assets/javascripts/application.js
    //= require whoopsie

Add the config helper to your layout:

    <%= whoopsie_config %>

or for HAML

    = whoopsie_config

Wrap any JS that you want to be protected with TraceKit:

    Whoopsie.wrap(function($){
      $(document).on('click', 'button[data-dismiss-hint]', function(event){
        alert("All is well.")
      });      
    });

or wrap long methods by name:

    $(document).ready(Whoopsie.wrap(myFunction));

### Coffeescript Usage

TODO

## Bugs

Please report any bugs or issues using [GitHub Issue Tracker](https://github.com/midwire/whoopsie/issues).

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/midwire/whoopsie.

Please use feature branches and follow the Git Flow paradigm.