"Theory is when you know something, but it doesn't work.
Practice is when something works, but you don't know why.
Programmers combine theory and practice: Nothing works and they don't know why"

What this article is about:
The following beginners' introduction into form script debugging tries to get you get started.

This article just focuses on debugging the ECMAScript that's used in your form and executed in the browser.

What this article is not about:
We are not talking about generic workflow debugging or driver debugging. That part of the logic is executed on the server.

The "poor man's debugger"

You may add script commands to your code that display variable contents or warnings.

Typical script commands are:
alert()
form.showDebugMsg()
form.showMsg()
form.showWarning()
form.showError()
form.showFatal()

Using these commands is legitimate, but should primarily be used to present information to the end user of the final form version.

For development/testing purposes the debugging approach outlined below is more appropriate and even easier to use.

Catch Me If You Can

You know: Anything that can go wrong, is will most likely do so at some point in the future.

If some of your code logic can potentially fail - be it due to unexpected conditions, rights issues, or plain code logic faults - embed your code into a "try .. catch" clause,

try {
    [ your code here ]
}
catch ( ex ) {
    alert( "Something went wrong: "   ex );
}

If some exception is thrown, it will be displayed as alert message.

If, in the case of an exception you need to perform some sort of "clean up" after your code inside the try statement.

try
{
    [ your code here ]
}
catch ( ex )
{
    [ this code will be executed on error ]
    alert( "Something went wrong: "   ex );
}
finally {
    [ this code will always be executed ]
}

The code in the "finally" clause will be executed regardless of whether an error occurs in the preceeding try clause.

Do you need some special debugger?

This depends:

• In current Internet Explorer versions (IE8 or later) there is an integrated debugger.
  Older IE versions utilized a separate tool "Microsoft Script Debugger" which could be downloaded from the Microsoft web site.
  You may have to enable script debugging: "Tools"/"Internet Options"/"Advanced" - clear the "Disable script debugging" check box.
  

• In Firefox, get the "Firebug" plugin (FF Menu: "Tools"/"Add-ons").
  To get help on using your debugger, check the Firebug site (https://addons.mozilla.org/en-US/firefox/addon/firebug/).
  

• Safari and Chrome have integrated debuggers. However, these browsers are not discussed in this article.
  

Starting your debugger

• Internet Explorer:
  select "Tools"/"Developer Tools", or press F12
  

• Firefox:
  select "Tools"/"Web Developer"/"Firebug", or press F12
  

The debugger is started in a separate window or in a separate portion of your current browser window.

To toggle debugging on/off, press F12 again.

Our Test Case

For demonstration purposes, let us take a look at a very simple example:

Assume you have a User Application form with a user DNLookup control.





When a user is selected, the form script needs to check if the selected user is in a specific group, then present an alert.

To achieve this, you add an "onchange" event to the DNLookup field and add this code to the event:

var dn = field.getValue();
if ( dn != "" )
{
	var groups	= IDVault.get( null, dn, "user", "group" );
	for ( var i=0; i < groups.length; i   )
	{
		var groupDn = groups[i];
		if ( groupDn == "cn=admin,ou=groups,o=data" )
		{
			alert( "The selected user is in the admin group" );
			break;
		}
	}
}

Code view

Now, let us take a look at your code in the debugger.
To get you started, I'm guiding you through the steps for Internet Explorer and Firefox/Firebug separately.

Code view: a) Internet Explorer

You have loaded the request form and started the debugger, e.g., by pressing F12.

The debugger window should pop up and look similar to this:





Press the "Script" tab and click on "Start debugging" - if the debugger forces your User App to be reloaded; re-open the form that you want to debug.





To see a list of all debuggable pages and scripts that are currently in browser memory, click on the list field





One of these listed items contains the script that you're after. Now what? See the next step: "Finding your code"

Code view: b) Firefox/Firebug

You have loaded the request form and started the debugger, e.g., by pressing F12.

The debugger window should pop up and look similar to this:





Press the "Script" tab and reload the page; re-open the form that you want to debug.

To see a list of all debuggable pages and scripts that are currently in browser memory, click on the list field





One of these listed items contains the script that you're after. Now what? See the next step: "Finding your code"

Finding your code

One of the pages and scripts that's on the list contains the inline script that you want to debug.

Finding your code is pretty easy, if you were including external form scripts.

In this case you'll find the script file listed in clear text and can quickly select the file.

However, if you're using inline scripts, one way to locate the correct item is to open one item after the other, then check the contents. Enjoy!

A better way to directly open an inline script is to add a breakpoint with a "debugger" statement.

Breakpoints

Static Breakpoint: The "debugger" statement
The 'official' ECMAScript definition does not have a debug statement, however all implementations (like JScript or Javascript) do implement a "debugger" statement.

If no debugger is loaded, the statement is ignored. However, if debugging is active, the execution is stopped and the debugger window pops up.

Now, it would be easiest to insert "debugger" statements at the critical places in your code. You could consider changing the sample above to:

var dn = field.getValue();
debugger;
if ( dn != "" )
[ ... ]

However, IDM Designer checks if the script conforms to the ECMAScript rules, and since "debugger" is not an official statement, IDM Designer prevents you from saving the script.

The solution is to wrap it up and let the browser script engine decide if it can handle it:

var dn = field.getValue();
eval( "debugger;" );
if ( dn != "" )
[ ... ]

The "eval()" statement asks the browser to evaluate whatever is passed as parameter.

Note: there are other breakpoints, like dynamic and conditional or data sensitive breakpoints.

We'll have a short look at these later.

Watch your Step

Once you've hit a breakpoint, program execution is halted, and you can continue executing your script with one of several methods:

Continue
Press "F5" (IE) or "F8" (FF) to let your script execution continue until the next breakpoint or the execution ends

Step over
"F10" (IE & FF) Executes next code line as a whole, but doesn't jump into it, instead moves to the next line of the same scope

Step into
"F11" (IE & FF) If the next line is a function, it goes into the body that function, so you can debug it

Step out
"Shift F11" (IE & FF) Executes the rest of the current function and jumps back to it's calling code line

Looking into our sample script with the 'eval( "debugger;" )' statement, the debugger pops up when selecting an object with the DNLookup control





The current code execution position is indicated by a yellow arrow.

Instead of using the function keys for stepping through the code, you may use the respective speed buttons.

In our test, we're moving on by pressing "F10" (stev over) or "Shift F11" (step out)

In Firefox/Firebug, things look pretty similar:





If you have static breakpoints, Firebug allows you to temporarily disable them.





Proceed and step up to the calling function.

Now the script panel shows our inline script. If we move the mouse pointer over a variable, the variable contents are displayed.





In the "Watch" panel, we can manually enter variable names that we would like to keep an eye on.

The "Locals" panel shows all variables in the current scope, which is especially useful while your current execution point is within a function.

Same, same, but different ... in Firebug





Dynamic Breakpoints

If your in a debugger code window, you may click on the code line number to toggle dynamic breakpoints. Unlike the hard coded debugger statements, these dynamic breakpoints will only affect your current debugging session.


Data sensitive Breakpoints


You may right-click on dynamic breakpoints to add conditions, e.g., to make them data-sensitive. You may for example add conditions like 'i > 100' or 'dn.indexOf( "test" ) > 0'

Console

In the debugger console windows, you can enter any script commands. This can come in handy when you want to quickly check or modify some variables.

Wrap it up

Especially when you've ended up adding more than trivial script code to your forms, you won't be able to avoid starting your debugger - and once you've made your first steps, you'll quickly ask yourself how you could get along without it.