Trap JavaScript runtime errors in Domino Web apps

Domino developers know that errors can and do occur during application development and testing as well as during production. This JavaScript traps errors in Domino applications -- providing two advantages over the browser's built-in error-handling method.

This Content Component encountered an error

JavaScript has become the de facto front-end scripting language for Web browser applications; it's also heavily used in many Domino Internet and Intranet applications. Previously, JavaScript was used for what might be considered simple tasks -- validating fields and displaying messages to users. However, JavaScript usage has evolved with the complexity of Web applications.

Websites and Web applications now use JavaScript to produce complex user interfaces by manipulating user interfaces in conjunction with DHTML and real-time data lookups using AJAX technologies. JavaScript toolkits such as Jquery, DoJo and YUI (Yahoo! User Interface Library) are also now commonly used on many sites including Domino applications. This adds up to a lot of JavaScript on a Web page.

Domino developers know that errors can and do occur during application development and testing as well as when a system is live in production. Here's a method for trapping errors in Domino applications that can provide two main advantages that the browsers' built-in method doesn't have for handling errors:

  • Eloquently deals with errors
  • Provides information about on the error to aid debugging and production support

Generating an error in JavaScript is simple. Insert the following code into the body of a Domino form:

<script>
 alert(ABC); 
// will generate an error as ABC is not a defined variable.
</script>

Mark the text as pass-thru HTML and preview the form in a Web browser. This code will generate a JavaScript error because it tries to use the variable ABC, which has not been defined.

What happens once you open this code will depend on which browser you're using, its version and your configured browser settings.

To view the error in Firefox, you may need to open the Error Console (Ctrl+Shift+J). To view the error in Internet Explorer, you may need to enable Script Debugging. To do so, uncheck the Disable Script Debugging check box in the Advanced tab of Internet Options.

You'll get an error similar to that shown in Figure 1.

webpage error, abc is undefined
(Click on image for enlarged view .)
Figure 1. Webpage error: 'abc is undefined.

JavaScript errors can be caught and trapped using a Try Catch block, which should be familiar to C++ and Java developers. The following code is the same, but this time it's trapped in a Try Catch block.

<script>

try {
 alert(ABC);  
// will generate an error as ABC is not a defined variable.
 }
catch(e) {
 alert(e.name + ' : ' + e.message);
}
</script>

When the error occurs between try{ and the closing }, the catch(e) block is executed and the code displays a message. In Firefox, the dialog box will appear as shown in Figure 2.

abc is not defined
(Click on image for enlarged view .)
Figure 2. Reference error: abc is not defined.

The Try Catch block is a great way to trap errors in blocks of code. However, it's not always practical or possible to wrap all your code in this block. For example, it may not be a good idea to use the Try Catch block when using a third-party JavaScript library where you either can't or don't want to change the code.

There is a way to implement a global JavaScript error handler on a Web page using the window.OnError property. But first, consider a slightly more complex piece of JavaScript code that is more representative of the type of code that you might find in contemporary Web pages.

The following code block still generates the original error, but this time the error-producing code is nested within four levels of function calls.

<script>

function a(){
 b() 
// call function b()
}

function b(){
 c() 
// call function c()
}

function c(){
 d() 
// call function d()
}

function d(){
alert(abc);  
// will generate an error as ABC is not a defined variable.
}

// Code execution starts here.

a();  
// call function a()

</script>

In this code, function a() calls function b(); function b() calls function c(); and so on, until function d() gets called and generates the same error as before. Both Firefox and IE show the same error message as before since there is no error handling in place. In other words: "'ABC' is still not defined."

Debugging this kind of error requires more effort, since we can't be sure where the error occurred. We might be able to see where the error is in this example, but consider the complexity of a Web page with multiple script libraries that contain various JavaScript functions.

Let's add a global error handler to our code using the window.onerror property:

<script>
function a(){
 b() 
// call function b()
}
function b(){
 c() 
// call function c()
}
function c(){
 d() 
// call function d()
}
function d(){
\alert(abc);  // will generate an 
error as ABC is not a defined variable.
}

function globalErrorHandler
(description,pagename,lineno)
{
 alert(
  'An Error occurred!  \n'
  +' \n Description:  \t'+description
  +' \n Page Name:       \t'+pagename
  +' \n At Line :        \t'+lineno
 )
 return true
}

// Code execution starts here.
window.onerror=globalErrorHandler;

a();   
// call function a()
</script>

I've added two additional parts to this code. The first is a function called globalErrorHandler(), which prints information about an error. The second is the line: window.onerror=globalErrorHandler.

The window.onerror property tells the browser to call the assigned function when a JavaScript error occurs. The function is called and is automatically passed three parameters by the browser, which then displays in a dialog box to the user. We tell the code to call the globalErrorHandler() function, which displays the dialog box show in Figure 3.

An error occurred
(Click on image for enlarged view .)
Figure 3. An error has occurred.

The dialog box now displays some useful information that we can use to debug our code or solve a production support issue. We now know what the error is, which URL contained the JavaScript code and in which line the error occurred.

You can make this dialog box even more useful by adding a custom stack trace function. The stack trace function displays the calling hierarchy of the JavaScript functions involved in generating the error.

Note: This function came from www.gettingclever.com. There are many similar functions available on the Internet, but they only seem to work in Internet Explorer.

The code for the stack trace function is:

function stackTrace()  
{  
 re = /function \W+([ \w-]+)/i;  
  
 var f = arguments.callee;  
 var s = "";  
 while (f)  
 {  
  s += (re.exec(f))[1] + '(';   
  
  for (i = 0; i < f.arguments.length - 1; i++)  
  {  
   s += "'" + f.arguments[i] + "', ";  
  }  
  
  if (arguments.length > 0)  
  {  
   s += "'" + f.arguments[i] + "'";  
  }  
  
  s += ") \n";  
  
  f = f.arguments.callee.caller;  
 }
s += " \n"
  
return s;  
}  

With the function in place, modify the globalErrorHandler() function to call the stack trace. Here is the code for this function:

function globalErrorHandler(description,pagename,lineno)
{

var st = stackTrace();

var thisError =   'Error details: \n'
  +' \n Description: \t'+description
  +' \n Page Name: \t'+pagename
  +' \n At Line :  \t'+lineno;

var sMessage = thisError + " \n \n" 
+ "Function call hierachy (listed from bottom to top)" + " \n" + st;

 alert(sMessage);

 return true
}

When the form loads, the globalErrorHandler function is called and it displays the information in a dialog box.

In Internet Explorer, the full calling path is displayed as enabled and you can use it to easily locate the source of the problem (Figure 4).

Error message from webpage
(Click on image for enlarged view .)
Figure 4. You can now locate the source of the problem.

Figure 5 shows that the calling information is not readily available in Mozilla Firefox.

error message from FireFox
(Click on image for enlarged view .)
Figure 5. The calling information is not readily available in Firefox.

However, if you are developing with JavaScript in Firefox, you should take a look at the Firebox development add-on, which has fantastic JavaScript debugging capabilities.

I also suggest putting the globalErrorHandler and stack trace functions in a JavaScript library (Figure 6). You may want to call the library errorHandling.js.

JS library
(Click on image for enlarged view .)
Figure 6. The JavaScript library.

To include the JavaScript library in your form, insert it into the JS Header section. Make sure that the window.onError is the first JavaScript command that is executed (Figure 7).

JavaScript command gets executed
(Click on image for enlarged view .)
Figure 7. Insert errorHandling.js first.

Do you have comments on this tip? Let us know.

ABOUT THE AUTHOR:   
Ethann Castell
Ethann Castell is a senior consultant with Caliton Innovations. He has extensive experience across all aspects of Lotus Notes and Domino dating back to 1995. Caliton Innovations develops leading-edge Lotus Notes tools, and provide boutique consulting services. You can contact Caliton Innovations through their Web site at www.Caliton.com.

This was first published in August 2009

Dig deeper on JavaScript for Lotus Notes Domino

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

-ADS BY GOOGLE

SearchWinIT

Search400

  • iSeries tutorials

    Search400.com's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...

SearchEnterpriseLinux

SearchVirtualDataCentre.co.UK

Close