Availability

Navigator 3.0

Synopsis

You register an onerror() event handler like this:

window.onerror=handler-func 

Navigator invokes the handler like this:

window.onerror(message, url, line)

Description

The onerror() event handler of the Window object is invoked when a JavaScript error occurs in code executing in that window. The default error handler installed by JavaScript displays an error dialog box. You can customize error handling by providing your own onerror() event handler.

You define an onerror() event handler for a window by setting the onerror property of a Window object to an appropriate function. Note that unlike other event handlers in JavaScript, the onerror() handler cannot be defined in an HTML tag.

When the onerror() handler is invoked, it is passed three arguments. The first is a string specifying the error message. The second is a string specifying the URL of the document in which the error occurred. And the third is a number that specifies the line number at which the error occurred. An error handling function may do anything it wants with these arguments: it may display its own error dialog, or may log the error in some way, for example. When the error handling function is done, it should return true if it has completely handled the error and wants JavaScript to take no further action. Or, it should return false if it has merely noted or logged the error in some fashion and still wants JavaScript to display the error message in its default dialog box.

Note that while this event handler returns true to tell the browser to take no further action, most Form and form element event handlers return false to prevent the browser from performing some action, such as submitting a form. This inconsistency can be confusing.

You can turn off error handling entirely for a window by setting the onerror property of the window to null. If you will later want to turn error handling back on, you should first save the default error handler in a temporary variable, so you can restore the onerror property to its default value.

Example

The following code shows how you might write and register an error handler for a window. Instead of reporting the error in a dialog box, this handler reports the details in a form that it creates directly in the document itself. The form contains a button that will send the details of the error off to the author of the web page.

<script>
function p(s) { document.writeln(s) }  // shorthand
// define the error handler. It generates an HTML form so
// the user can report the error to the author.
function report_error(msg, url, line)
{
   // Output a form that reports the error
   p('<P><HR SIZE=5><DIV align=center>');
   p('<H1>SORRY!  A JavaScript Error Has Occurred</H1>');
   p('<FORM ACTION="mailto:bugs at wahoo.com" METHOD=post
   p('      ENCTYPE="text/plain">');
   p('You can help the author debug this program by clicking here: ');
   p('<INPUT TYPE="submit" VALUE="Report Error">');
   p('</DIV><DIV align=right>');
   p('<BR>Your name (optional): <INPUT SIZE=60 NAME="name" VALUE="index.html">');
   p('<BR>Message: <INPUT SIZE=60 NAME="message" VALUE="'
               + msg + '">');
   p('<BR>URL: <INPUT SIZE=60 NAME="url" VALUE="' + url + '">');
   p('<BR>Line Number: <INPUT SIZE=60 NAME="line" VALUE="'
               + line + '">');
   p('<BR>Browser Version: <INPUT SIZE=60 NAME="version"'
               + 'VALUE="' + navigator.userAgent + '">');
   p('</DIV>');
   p('</FORM>');
   p('<HR SIZE=5><P>');
   return true;    // tell the browser not to report the error itself
}
// now register the error handler
window.onerror =index.html report_error;
</script>

See Also

"Window"