Documentation

Learn, DAMN IT! This documentation will cover the following:

• Setup
• Using
• Advanced Usage
• Security concerns

Setup

For a head start, download the code from the demo.

There are two ways to set up DamnIT:

• Using the error plugin of JavaScriptMVC
• As a standalone script

Setting up DamnIT with JavaScriptMVC

DamnIT is available as JavaScriptMVC's error plugin. Using JavaScriptMVC's error plugin lets you easily compress your application with the DamnIT library. To load DamnIT with JavaScriptMVC, all you have to do is include the error plugin.

Setup steps:

1. Obtain an application key
2. Include the error plugin

Obtaining an application key:

1. Sign up at damnit.jupiterit.com.
2. Click the link in the confirmation email.
3. Get your Application Key on the setup instructions page.

Including the error plugin:

Assuming you've correctly set up your JavaScriptMVC application, the following code includes the error plugin and defines your application key. Make sure you replace _APPLICATION_KEY_ with your application key.

APPLICATION_KEY='_APPLICATION_KEY_';
include.plugins('error');

The error plugin only reports errors in JavaScriptMVC's production mode.

Setting up DamnIT as a standalone script

Setup steps:

1. Obtain an application key
2. Load the DamnIT script

Obtaining an application key:

1. Sign up at damnit.jupiterit.com.
2. Click the link in the confirmation email.
3. Get your Application Key on the setup instructions page.

Loading the DamnIT script:

Insert the following code into your html pages right before the ending body tag (</body>). Replace _APPLICATION_KEY_ with your application key.

<script type='text/javascript' 
   src='https://damnit.jupiterit.com/damnit.js?_APPLICATION_KEY_'>
</script>

Using

We'll walk through:

• how to catch errors in all the browsers
• browser support for error reporting functionality
• how to configure DamnIT for your application's needs

Catching Errors

IE and Mozilla support the onerror event, while Opera and Safari do not. Thus, DamnIT error notification works automatically in IE and Mozilla, while you have to wrap your code in try...catch blocks in other browsers to add DamnIT's error notification functionality. If you're using JavaScriptMVC's Controller plugin, your code is covered across all browsers.

IE and Mozilla: Automatic Support

These browsers require no additional code in your application to catch all errors and notify you. For many apps, IE and Mozilla support is sufficient, since they make up 91% of the browser market.

Safari and Opera: Wrap your Code with try...catch

Opera and Safari don't support the onerror event, so add DamnIT functionality like this:

try { // 1
   this.will.cause.an.error();
} catch(e) {
   ApplicationError.notify(e); // 2
}

1. Place try...catch blocks around your application code.
2. ApplicationError.notify accepts an error object and performs the same functionality as the onerror event handler for IE and Mozilla: prompting the user and sending error information to the DamnIT server.

DamnIT with Controller: Cross Browser Support

The easiest way to maximize DamnIT's code coverage for all browsers is to use Controller to define your event handlers. Errors within event handlers defined using Controller are automatically caught and reported across all browsers.

Browser Support

Configuring DamnIT

DamnIT provides the ability to customize the contents of its user prompt or to turn off the user prompt entirely.

Turning off user prompt

During beta testing, its useful to ask testers to describe their actions the preceded the error. As you move into production, you may wish to turn this functionality off. You can do so with the prompt_user option of ApplicationError's config method:

ApplicationError.config({prompt_user: false});

Configuring user prompt

You can configure the user prompt to say what you like and stay open for as long as you'd like:

ApplicationError.config({
   prompt_text: 'DAMN IT YOU BROKE IT!', 
   textarea_title: 'Please explain.', 
   close_time: 4
});

The above configuration creates the following user prompt:

Modified user prompt

Advanced Usage

After you mastered the basics, you can start adding your own functionality to your DamnIT notifications. You can:

• Add information to your notifications
• Use DamnIT notifications for other purposes
• Send custom notifications

Adding Information to your Notifications

You can add information to your error emails if there is something else you want to know about an error. You can do this by creating your own attributes and adding them to the error object passed into ApplicationError.notify.

For example, you might want to know the username of the person who broke your application:

try {
   this.will.cause.an.error();
} catch(e) {
   e.username = 'Brian';
   ApplicationError.notify(e);
}

Or maybe you noticed a lot of problems in IE, but since IE doesn't provide file name information in the error, you manually add it:

try {
   this.will.cause.an.error();
} catch(e) {
   e.fileName = 'myscript.js';
   ApplicationError.notify(e);
}

You'll see this information added to your email notifications.

Using DamnIT for Other Purposes

DamnIT is a JavaScript reporting service. It allows you to always be aware when something of consequence happens in your applications.

Beyond error notification, you can use DamnIT to notify you when a user:

• clicks your new drag and drop widget
• types something in an important input box
• clicks an area of the page

These examples are trivial, but the point is you can use DamnIT to notify you of anything that occurs in your JavaScript application. Error notification is simply the best application we've come up with so far.

Sending a Custom Notification

If you wish to use DamnIT for a purpose other than error reporting, you can easily create your own notification functionality using ApplicationError's send method:

var notification = new ApplicationError({
   subject: "test",
   content: "someone clicked the new widget"
}); // 1
notification.save(); // 2

1. Creates a new ApplicationError instance. Set the subject and content attributes to define what the email will contain.
2. Sends a request to DamnIT's server to email you the subject and message content.

Custom notification email

Security Concerns

Data Privacy

We store all your error information on the DamnIT servers. This includes snapshots of your page's HTML, which could contain things we shouldn't see, like bank account numbers. For apps with sensitive information, this could rightly be a cause of concern.

DamnIT will shortly include an option to not save the HTML content on the DamnIT server. Until then, we promise we aren't evil and will never read your HTML.

JavaScript concerns

Error information is sent from your site's domain to damnit.jupiterit.com. The technique used to allow this cross domain communication involves loading a script tag and tacking the data on to the end of the url like this:

<script type="text/javascript" 
   src="https://damnit.jupiterit.com/errors.json?error%5Bsubj..."></script>

The server saves the objects and sends back JavaScript like this:

ApplicationError.createCallback({error: "https://damnit.jupiterit.com/errors/1833", 
   id: 1833, status: 201})

The obvious problem is we could technically send back any JavaScript here. To paint it in the most diabolical way possible, if your user's bank account number is on the page, the script could find it and send it to our servers.

In the short term future there are plans to replace the current method with Subspace, a method for secure cross-domain communication. Without this method, DamnIT, Google Analytics, and any other remotely loaded JavaScript should never be used unless you trust the vendor completely. We promise we're not evil.