John Brinkman on form design

Handling JavaScript Exceptions

I have previously apologized for not being the most sophisticated JavaScript programmer on the block. But one of the advantages of learning while I blog is that occasionally I discover things that a smart JavaScript programmer would already know, but is interesting to people who are climbing the same learning curve as me.

Today I learned more about JavaScript exceptions. Or more specifically, the JavaScript exceptions thrown by script errors in XFA.

As it turns out, this is not a very satisfying way to report exceptions. The error object that gets thrown by the script engine does not provide helpful information from the toString() method. Typically it returns something like: "GeneralError: Operation failed.". Thanks a lot.

Then it dawned on me that just maybe there was useful information locked up inside the exception object that the toString() method does not report. I wrote some code (ok, I shamelessly copied some code from O’Reilly’s: JavaScript the Definitive Guide) to examine the contents of the object in my catch block.

Turns out there’s lots of great information available. The exception we catch comes populated with properties: name, message, filename, lineNumber, extMessage, number and stack. The toString() method on this object ignores the most useful information and simply concatenates the name and message properties. The extMessage property is what normally gets dumped to the JavaScript console.

With this knowledge, I can write an exception object formatter that turns the exception message into something both useful and human readable:

Server Side

You might not be aware that our JavaScript processor on the server is different from the one embedded in Acrobat/Reader. Fortunately, in spite of being different processors, the compatibility between the two is very good. However the exception object that gets thrown on the server has a different set of properties from the exception object thrown on the client. The function I wrote to format an exception has conditional code that produces a different result for the server, based on the properties available there:

Why Bother?

If you’ve been debugging JavaScript for some time, then you might wonder why I went to all this trouble, since most of the useful information from a JavaScript error is dumped to the console anyway. Three reasons:

Some form authors make a practise of wrapping all their JavaScript code in try/catch blocks.

The stack trace information is not part of the information dumped in the JavaScript console

I found a bug where under certain conditions, JavaScript exceptions are *not* reported in the console.

The bug happens when an initialization script creates an instance of a subform. If that new subform also has an initialization script, its errors go unreported in the console. This condition (a nested initialization) is probably a bit unlikely for most forms, but has happened to me at least a couple of times. My workaround is to wrap the initialization script in a try block and dump exception information to the console in the catch block. And now that I have better tools for dumping exceptions I’m a happier form developer.

The Deep End

Server Side Debugging

When writing code for forms destined for the server, it is important to be able to dump information from your scripts so you can debug them. In Reader/Acrobat using console.println() is invaluable. But the console object is specific to Acrobat. We need something for the server as well. I use xfa.log.message().

You might have noticed up above that the dump of the exception for the server had a line of code that did not appear in the form:

this.ForceError = ForceError; this.nestedFunction = nestedFunction;

This line gets added to the script by the XFA processor so that for a named script object we can support the syntax: foo.ForceError() and foo.nestedFunction().

Other Kinds of Exceptions

If you write JavaScript code that throws an exception, then the exception object will be whatever you throw. For example you could do this:

throw "Bad date format";

In this case, the object caught in a catch block will be a string — not the exception object that XFA scripts throw.

March 19 Update

After using the sample code for a few days, I added a couple of improvements to the sample:

It turns out that the contents of the exception in Reader varies depending on the nature of the exception. The code I wrote handled exceptions thrown by the XFA engine. Regular JavaScript language exceptions did not populate an "extMessage" member of the exception class. I updated the pretty printing of the exception accordingly, and added an example of this kind of exception to the form.

Since most of the time we want to display exceptions in the console or server log file, I added a handleError() method that does just that. In addition, to logging to the console, it calls console.show() in order to make sure the form author sees the exception when they’re debugging.

August 14 Update

Improved the handling of message emitted in Designer. Added support for thrown string objects. These changes are explained here. Download this fragment for the latest version of this script.

8 Responses to Handling JavaScript Exceptions

Exceptions are cool but in Javascript they are also pretty useless (as in ActionScript). The problem is that a lot of things in JavaScript (as in ActionScript) are asynchronous. If you define an event handler within a ‘try’ and the event is triggered after the ‘try’ was constructed, the ‘throw’ looses it’s context, i.e. it doesn’t know the context of the ‘try’ it was created in.PS: Can you make this input text field a bit larger? I’m not a masochist you know…

pan69:I haven’t run into this limitation — primarily because using asynchronous events isn’t normally required for developing PDF forms.As for the width of the commenting input box… I agree it’s too small. I’ll see what I can do.John

This is not true. Exceptions in JavaScript are great. You just have to wrap the event handler in a try-catch block. While it is a bit cumbersome to use them for error solution, this works fine for reporting errors to the server.

Looks great – and could be really useful during development.. But what’s with the attached sample in PDF format? It seems I need to download a 46 MB viewer application just to open the sample function.. Which could just have as easily been inserted into the article, or attached as a JS file – or even a text file.