Chapter 14

Debugging JavaScript Programs

• Common Errors in JavaScript Programming
  • Syntax Errors
  • Timing Problems
  • Variable Problems
  • Reserved Words
  • Platform-Specific Issues
• Techniques for Debugging
• Using Alerts to Display Values
• Debugging with a Temporary Window
• Tools for JavaScript Debugging
  • Using the JavaScript Command Line
• Testing JavaScript Commands Interactively
  • The JavaScript Trace Facility
• Installing the JavaScript Trace Facility
• Dealing with Bugs and Crashes
  • Netscape Navigator 2.0
  • Netscape Navigator 2.01
  • Netscape Navigator 2.02
  • Netscape Navigator 3.0 (Atlas)
  • Microsoft Internet Explorer
• Workshop Wrap-Up
  • Next Steps
  • Q&A
    

So far, you've learned the basics of JavaScript and several advanced techniques. You have explored several examples, all of which were tested and debugged for publication in this guide.

At this point, you're probably interested in creating your own unique JavaScript applications, and you may have run into some problems. In this chapter, you'll explore some common errors and misconceptions in JavaScript programming.

You'll also look at some tools and techniques you can use to debug your programs. Finally, you'll explore some problems that aren't your fault-bugs in various implementations of JavaScript. You'll also consider the impact of these bugs and explore ways of working around them.

Common Errors in JavaScript Programming

Although JavaScript is one of the simplest programming languages, there are still some statements, functions, and techniques that can be confusing. You will explore some of the most common errors you might make, and their symptoms, in the next sections.

Syntax Errors

Some of the most common errors you might make in a JavaScript program are syntax errors-errors in the punctuation, object names, and such that make up a program.

Some syntax errors are obvious. For example, you might miss a comma or period, or spell the name of an object wrong. Netscape recognizes most of these errors and will point them out to you.

Unfortunately, some of the easiest syntax errors to make can be the hardest to detect. Netscape won't detect them, and the program may even work-but produce the wrong result. You'll explore the most difficult syntax errors in the following sections.

Assignment and Equality

One of the most common errors people make in JavaScript is to confuse the assignment (=) operator with the equality (==) operator. This can often be one of the hardest errors to spot in your source code. If you've done any programming in C or Perl, you'll recognize this as one of the most common errors in those languages also.

Luckily, JavaScript is able to detect this error better than most languages. For example, the following line of JavaScript code mistakenly uses the assignment operator:

if (a = 5) window.status="a is 5";

When the JavaScript interpreter encounters this line, it recognizes that it was probably intended as an equality test and gives you an error message indicating this (see Figure 14.1). The interpretation of the program continues and treats the line as if it were an equality test. (Of course, you should still fix it.)

Figure 14.1 : Netscape recognizes when you have used an assignment operator by mistake.

If you make the opposite mistake-using == when you should have used =-the error message isn't quite as clear. In fact, you may not receive an error message. For example, this program will generate an error message:

a == 5; if (a == 5) window.status="a is 5";

The first statement is considered an error because you are trying to compare the variable a with a value, but a currently has no value. The error message produced by this example is shown in Figure 14.2.

Figure 14.2 : the error message produced when you used the equality error by mistake.

However, consider the following modified version of the example:

a = 7; a == 5; if (a == 5) window.status="a is 5";

In this example, the variable a has been defined and assigned a value, before the equality operator is used. This makes a == 5 an expression that simply evaluates to true, doing nothing. No error message is produced, but the correct action is not performed.

Naming Objects Correctly

Another common error in JavaScript is to leave out some details of an object's name-for example, in the following form definition:

<FORM name="form1"> <INPUT TYPE="text" NAME="text1"> </FORM>

If you want to access the value of the text1 text field, the correct syntax is this:

document.form1.text1.value

It's often tempting to refer to the object as simply text1, but it won't work without the document and form name. If the previous form was defined in a different frame, you would also need to refer to the proper frame:

parent.frames[1].document.form1.text1.value

Obviously, things can get complicated, especially when you're working with multiple documents, windows, and frames. If you have used the incorrect name, you will usually get the same error message: name has no properties. Figure 14.3 shows an example of the error message when the form name has been left out.

Figure 14.3 : The error message you usually get when using the incorrect name for an object.

Using Proper Punctuation and Capitalization

A few common errors involve punctuation. These usually result in an error message when the page is first loaded, and include the following:

• Be sure to use parentheses after a method name, even if you are not passing any parameters-for example, date1.getSeconds() accesses a method of the date object. Similarly, be sure not to use parentheses with a property name.
• If you want to use the value of a variable as the name of a property, be sure to use brackets ([]) rather than the period syntax. With a period, the variable name is used as the property name. For example, object[var] accesses a property with the value of var as its name; object.var looks for a var property.
• Be sure to use parentheses around the condition in the if statement and anywhere else you use a conditional expression.

You should also keep close watch on your capitalization, because JavaScript variable, method, function, object, and property names are case-sensitive. For example, this statement is invalid because the random() method should not be capitalized:

a = Math.Random();

HTML Issues

Because a JavaScript program is embedded within an HTML document, errors in the actual HTML can affect your program. HTML is a complicated language in itself, and this guide can't cover all of it here; however, here are some common HTML errors that can affect JavaScript programs:

• Be sure to use the NAME attribute for all forms, form elements, and frames. This makes it easy to access the objects from JavaScript.
• Be sure to enclose JavaScript code within <SCRIPT> tags, except when defining event handlers.
• Use quotation marks around an entire event handler, and be sure to use single quotation marks (apostrophes) instead within the event handler itself.
• Avoid using too many statements in an event handler; if you have a complex need, define a function and call the function in the event handler.
• If you are using HTML comments to hide JavaScript code from older browsers, you have to be careful; using the greater-than (>) or decrement (-) symbols anywhere in the script can cause the comment to end prematurely. For tips on working around this problem, see Chapter 1 "Creating Simple JavaScript Programs."

Using Correct Objects

Some of the objects and properties in JavaScript can be confusing. The best example of this is that the document and the window both have a location property. These are very different things:

• window.location is a location object that defines the location of the current window (or the specified window). You can change this location to cause a new document to be loaded by changing its properties, such as window.location.href.
• document.location is a simple text property that indicates the location of the document. This may be different from the value of window.location.href if the document was redirected from a different location.

A common error is to attempt to set document.location to send the user to a new URL. This doesn't generate an error message, but also doesn't accomplish anything. You should always use window.location.href to load a new URL.

Another area of confusion is the history object. Some references, such as Netscape's own documentation, refer to the history object as a property of document. However, it is actually a property of the window object. Each window has its own history.

For example, to go back to the previous document, you should use the window.history.back() method, or simply history.go(). To go back to the previous document in the frame1 frame, you would use parent.frame1.history.back(). Using document.back() results in an error.

Timing Problems

A number of potential JavaScript programming errors are caused by failure to understand various timing factors-the order in which a document loads and JavaScript code executes. Here are some examples of problems of this nature:

• You must always define a function before calling it. If you place your function definitions in the <HEAD> section of the HTML document, they will always be loaded first. Otherwise, the script section that defines the function must be located before the section that uses it.
• The window's onLoad event handler can be triggered before the entire document loads. This is particularly true of images. This means that you should be careful when working with the images array, because some images may not be loaded yet. You can use each image's onLoad event handler to verify this.
• Another situation when onLoad doesn't always work is in using frames. The best way to verify that an object you need to use is loaded is to check its value. If it isn't there, use setTimeout to pause before trying again.
• Multiple setTimeout calls do not override each other. If the timeouts use different variables, they will execute independently.

Variable Problems

Sometimes variables can create problems. One of the most confusing aspects of JavaScript is the scope of variables-in other words, where a variable can be used. As you have learned, there are basically two variable scopes in JavaScript:

• Global variables are those you define outside a function, or by using the var keyword. These can be used anywhere in the HTML file where they are defined.
• Local variables are those you define within a function, or without using the var keyword. They apply only to the function or set of <SCRIPT> tags where they are defined.

Problems can occur when you cut and paste JavaScript routines between two pages. You might be using a global variable for one routine with the same name as a local variable used in another routine. Any time a variable's value changes unexpectedly, suspect this type of problem.

Reserved Words

JavaScript has a list of reserved words-words that you can't use as variable names because they serve an important purpose within JavaScript. Because this list includes all the object properties in the object hierarchy, it can be quite long.

This can create problems if you choose a name that matches a reserved word. For example, suppose you created an order form that includes a name, address, and phone number. You might choose the obvious names name, address, and phone for those text fields. However, because form.name is a predefined property that holds the name of the form, this can create conflicts.

In some cases, the property might not work the way you expect it to, or change value unexpectedly, because the internal JavaScript property has priority. In other cases, your new property might override the built-in property, causing a different set of problems.

Platform-Specific Issues

JavaScript is designed as a platform-independent language. In other words, the Windows, Macintosh, and UNIX versions of Netscape should run a script in exactly the same way.

For the majority of JavaScript features, this is true; however, there are still a few differences in the way JavaScript works on the different platforms. Here are a few common platform-specific problems:

• For some Macintosh versions of Netscape, dates in Date objects are one day in the future compared to other versions.
• For some UNIX and Macintosh versions, the document.lastModified property returns an incorrect value-or causes a crash.
• The parseInt() and parseFloat() functions return 0 to indicate that the result is not a number in Windows platforms; on other platforms, they return "NaN" (not a number).

There are many other minor differences between platforms. Worse, when the current version of Netscape is a beta version, there may be different bugs for different platforms, or the version may not be available for a particular platform yet.

How do you keep up? The differences are usually minor, so you can usually avoid these issues. Because most of us don't have several computers handy to test a program on every platform, the best you can do is put it on the Web-you'll get feedback from users if there's a problem.

Techniques for Debugging

Let's look at two techniques you can use in the process of debugging your JavaScript programs. Either of these methods can be used to test the value of a variable at intermittent points and follow the data through the program.

Using Alerts to Display Values

The simplest way of adding debugging information to a JavaScript program is to use the window.alert() method to display a value. For example, the following section of code includes an alert to test the value of the text variable:

text = document.form1.text1.value; window.alert("Value:" + text);

Remember that because JavaScript is a loosely typed language, you can include numeric variables, string variables, and floating-point variables in the alert text. Here's an example:

a = 5.66; b = 2; window.alert("a is " + a + " and b is " + b);

In the process of debugging a JavaScript program, you might add statements like this several times to find the cause of a problem. After determining the problem, you can remove the alert statement.

Debugging with a Temporary Window

For larger-scale debugging needs, you can open a new window and use it to display debugging information. The following is an example of a statement to create a new window called bug to display debug information in:

bug = window.open("","bug","status=0 toolbar=0");

After opening the debug window, you can use a simple function to write data to it:

function debug(text) { bug.document.writeln(text); }

You can now use the debug() function to display debug messages in the new window. Listing 14.1 shows a detailed example of this technique, and Figure 14.4 shows the output in the debug window.

Figure 14.4 : Using a temporary window to display debugging information.

Listing 14.1. (TEMPWIN.asp) A simple program that displays debug information in a temporary window.

<HTML> <HEAD><TITLE>Test of Debugging Window</TITLE> <SCRIPT> //open the debug window bug = window.open("","bug","status=0 toolbar=0 height=100 width=400"); bug.document.write("<HTML><HEAD><TITLE>debug</TITLE></HEAD>"); bug.document.write("<BODY><h1>debug output</h1><hr><PRE>"); //function to write to debug window function debug(text) { bug.document.writeln(text); } a = 17.5; b = 29; c = "This is text"; debug("Value of a is: " + a); debug("Value of b is: " + b); debug("Value of c is: " + c); </SCRIPT> </HEAD> <BODY> <h1>Test of Debugging Window</h1> <hr> this is a test. </BODY> </HTML>

Tools for JavaScript Debugging

If you've programmed with C, Perl, or another full-scale programming language, you might be used to the benefits of a complete debugger, which enables you to step through programs, test variables, and perform other helpful tasks automatically.

JavaScript is a simple language and is not equipped with a debugger. However, you're not entirely alone in your task of debugging a JavaScript program. You will learn about two tools in the next sections that can help:

• The JavaScript command line, built into Netscape, can be useful for testing JavaScript commands.
• The JavaScript Trace Facility is a third-party tool that can be helpful in developing complex JavaScript applications.

Using the JavaScript Command Line

Although you won't find any mention of it in Netscape's documentation, there is a debugging tool of sorts built into Netscape Navigator (all versions that support JavaScript). It has no official name, but it's called the JavaScript command line here.

To access this tool, simply type javascript: in Netscape's Location field and press Enter. If you're a slow typist or enjoy coffee-related terms, you can type mocha: to access the same screen. The resulting screen is divided into two frames horizontally; the top one is blank, and the bottom frame includes a text field. The initial JavaScript command line screen is shown in Figure 14.5.

Figure 14.5 : The JavaScript command line: a simple debugging tool.

Testing JavaScript Commands Interactively

As you might guess, the JavaScript command line enables you to type a command into the blank. When you press Enter, the command is executed. The top frame is used to display the status of each of the commands in a scrolling list.

Although this won't help you debug an existing program, it can be very useful in the process of learning JavaScript or planning a project. You can test commands in this command line to find out easily how they work and what they return.

As an example, Figure 14.6 demonstrates the use of the command line to test the window.confirm() method. I have already tried it several times, and you can see the result (true or false) for each trial. The confirmation dialog is currently displayed along with the command that produced it.

Figure 14.6 : The result of several trials of the window.confirm() method using the JavaScript command line.

You don't have to use an actual statement in the command line. You can use any valid JavaScript expression. The result of evaluating the expression is shown in the upper frame. For example, Figure 14.7 shows the result of several trials of the Math.random() method.

Figure 14.7 : The result of several trials of the Math.random() method using the command line.

When you're working at the command line, you can use variables and even create functions. The only restriction is that anything you do has to fit in the text field. For example, you could define a simple function to add 5 to a number by typing this command:

function add5(num) {return num+5}

Once you've done that, you can type this expression:

add5(39)

and the result (44) will be displayed.

Using Commands in the URL

You can also skip a step and enter a JavaScript command directly into Netscape's Location field. Use javascript: (or mocha:) as the method before the command. For example, you can type the following into the Location field to display an alert message:

javascript:window.alert("This is an alert.");

This makes it easy to test a statement or expression quickly. Using this method, however, you cannot define functions or perform other complex operations.

The JavaScript Trace Facility

Obviously, the JavaScript command line leaves something to be desired as a debugger. It enables you to test statements, but it doesn't do much good in testing complete applications. The JavaScript Trace Facility is a third-party utility that allows a wide variety of options for testing a program.

The JavaScript Trace Facility was created by Fred Highland (wwmfarm@fred.net). It is ed, but it can be copied for use in your own JavaScript programs.

Installing the JavaScript Trace Facility

To use the Trace Facility, you need to copy its functions into the HTML file with your script. You can also use the <SCRIPT SRC=> tag in later versions of Netscape to include it in your file.

To copy the Trace Facility functions, load the page at this URL:

http://www.fred.net/wwmfarm/javastra.asp

Once you've done this, you can use the functions for interactive debugging and tracing.

Using the Debug Form

The Trace Facility includes several functions that you can use for debugging and tracing. The first, trace_form(), creates a form to hold the results of the trace. In the call to this function, specify the width and length of the form. This example:

trace_form(60,5)

defines a form with 5 lines, 60 characters across.

The JavaScript Trace Facility debug form is shown in Figure 14.8. It includes the following components:

Figure 14.8 : The JavaScript Trace Facility debug form enables you to test values and trace the execution of your program.

• The Expression or Object text field enables you to enter an expression, command, or object name to be evaluated.
• The Evaluate button evaluates the expression, similar to Mocha's command line.
• The Properties button lists the properties of the object you have named on the command line.
• The Clear button clears all the fields.
• The Result text field displays the result of the expression, the return code for a statement, or the properties of the object.
• The Trace Output window displays tracing messages. You can create these by using the trace functions, described in the next section.
• The Statistics button displays statistics for a function. This is used with the statistical functions described in the next section.

Using the Trace Functions

Along with the debug form, the JavaScript Trace Facility includes a variety of functions that you can use to track events in your program. The output of each of these commands appears in the Trace Output window of the debug form:

• trace_entry(name,arguments): Use this function to trace the entry into a function. Specify the function's name and the arguments being passed to it in the parentheses. Place this function call at the beginning of your function definition to trace calls to the function.
• trace_exit(name,value): Use this function to trace the exit from a function. Place this function call immediately before the return statement in the function. Specify the function's name and the value that you will return.
• trace_msg(text): Use this function to display the text string you specify in the trace output field. You can use this to display any message you like.
• trace_entry_stats(name): This function enables you to trace the entry to a function and collect statistics on the number of calls to the function and the time spent within it. The name you specify is used to identify the function. You must also use trace_exit_stats.
• trace_exit_stats(name): This function ends the statistical trace of a function. Place this command at the end of the function and specify the same name as you did previously. After the function has been called at least once, you can press the Statistics button in the debug form to display the statistics.

Dealing with Bugs and Crashes

JavaScript is continually being developed and improved; because of this, you should always use the latest version of Netscape to test and debug your JavaScript applications. However, you're probably making your applications available to users all over the world via the Web, and there's no way to ensure that they have all upgraded.

In the next sections, you'll look at each of the versions of Netscape and Microsoft Internet Explorer that support JavaScript, their limitations and bugs. If users report a problem with your script, you should refer to this list to determine whether the problem is caused by their browsers.

Netscape Navigator 2.0

JavaScript was introduced in version 2.0 of Netscape Navigator. There were several beta versions of version 2.0 before the final version, and JavaScript progressed in these versions. You'll look at some of the problems in the beta versions, then in the released version.

You will also look at some memory problems in JavaScript in this section. These are not described by Netscape in the release notes, but have been discovered by users (usually causing a crash). You'll also look at some ways of avoiding the problem.

Beta Versions of Netscape 2.0

JavaScript was introduced in the first beta release of Netscape Navigator 2.0. It was originally called LiveScript, and the <SCRIPT> tag used "livescript" as its language value. It was also available only for the Windows platforms.

In version 2.0 beta 2, support was added for Macintosh and UNIX platforms. Improvements continued until version 2.0b6, the last beta release.

Several bugs are present in the beta versions. Here are some of the most important ones:

• The select() and focus() methods for input fields don't work properly.
• The selectedIndex property of a selection list doesn't receive the correct value.
• The window.close() method does not work in these versions.
• Attempting to use a window the user has closed can cause Netscape to crash.

Problems in the Release of Netscape 2.0

Although the final release of Netscape 2.0 is a much more stable product than any of the previous versions, it still has several JavaScript-related bugs and limitations:

• You must use the HEIGHT and WIDTH attributes for all images in a document that uses JavaScript. If they are not used, event handlers will not work correctly.
• The onLoad event may occur before the document and its images are completely loaded.
• The lastIndexOf string method does not work properly; it starts one character earlier than it should.
• You are not allowed to set the form.method property.
• Multiple form elements with the same name should be stored in an array. In some cases, this array will be indexed backward.
• The document.close() method can cause a crash if it is used with the default window.
• The eval() function causes crashes, particularly in the 16-bit Windows version of Netscape.
• Floating-point arithmetic has some inaccuracies.
• The <SCRIPT SRC> method of including JavaScript in an HTML file does not work.

Memory Problems

Along with these problems, Netscape 2.0 suffers from some memory leaks when JavaScript is used. This means that certain JavaScript code can use up memory, often resulting in an out-of-memory error or crash.

The most common cause of this problem is when you repeatedly assign a value to a string. JavaScript cannot modify the value of a string without re-creating the entire string. If you change a string's value repeatedly in a loop, memory will quickly disappear.

Netscape Navigator 2.01

Netscape Navigator 2.01 did not add any new features (or bugs) to JavaScript. It did remove several features for security reasons, however. These include the following:

• You cannot use the submit() method with the mailto: action. This would enable scripts to send mail from you without your knowledge.
• You cannot access lists of files and directories (such as opening a local directory) within JavaScript.
• You cannot access the individual history items within the history object.
• If a document is loaded in another window from a different server, you can obtain only certain information about the window.

Netscape Navigator 2.02

This is an incremental release that fixed a number of bugs in version 2.01. The main bug was a problem with Daylight Savings Time, which caused pages to remain in the cache even when they had been changed. There were also some minor fixes to JavaScript:

• The document.close() method works properly.
• A fix prevents scripts from starting a file upload to the server without your permission.

Netscape Navigator 3.0 (Atlas)

At this writing, Netscape Navigator 3.0 is under development and several beta versions have been released. Some of these versions were released under the code name "Atlas." Many new features have been added in these versions.

New Features

Netscape 3.0 added many new features to JavaScript. In fact, many of the features you already learned about were added in this version. JavaScript didn't really "grow up" until version 3.0 was released. Here is a summary of the new features:

• JavaScript can now access a list of plug-ins, to determine which ones are available. You will use this feature in Chapter 13, "Working with Multimedia and Plug-Ins."
• JavaScript can now communicate with and access Java applets, and Java applets can access JavaScript. You'll explore these features in Chapter 16, "Integrating JavaScript with Java."
• The Array and Object keywords, which you looked at in Chapter 4 "Using Built-In Objects and Custom Objects," were added.
• The images array, which you looked at in Chapter 12, was added.
• Data tainting, explained in Chapter 10, "Working with Multiple Pages and Data," was added.
• The focus() method can now be used on external windows.
• The <SCRIPT SRC> tag can now be used to include JavaScript from a URL.
• The <NOSCRIPT> tag makes it easy to detect non-JavaScript browsers.
• You can modify the items in a selection list on the fly.

Remaining and New Bugs

Unfortunately, several bugs still plague the beta versions of Netscape 3.0. These should be fixed in a later release. These include the following:

• The document.lastModified property does not work on all platforms, and it sometimes causes a crash.
• The click() method of buttons, radio buttons, and checkboxes does not work properly.
• Forms or JavaScript code inside a nested table are not recognized properly.
• There are still several situations that can cause memory leaks.

Microsoft Internet Explorer

At this writing, Microsoft has begun to support JavaScript with an early alpha version of its Web browser, Microsoft Internet Explorer (MSIE) 3.0. At present, this support is very minimal.

Currently, few of the examples in this guide will work in MSIE 3.0 at all, and many will cause a crash. My recommendation is not to attempt to support this browser until it is more finished; Microsoft has promised full JavaScript support in the final version of MSIE 3.0.

Workshop Wrap-Up

In this chapter, you explored some of the many ways JavaScript programs can fail, and what to do about them:

• You've looked at some of the most common errors JavaScript programmers make and how to avoid them.
• You have also looked at two techniques for displaying debug information: alerts and external windows. Each of these has its advantages.
• Next, you looked at two tools that may help the debugging process: Netscape's JavaScript command line, and the JavaScript Trace Facility by Fred Highland.
• Finally, you took a tour of the various versions of Netscape (and Microsoft Internet Explorer) that support JavaScript and some of the problems and bugs in each version.

Next Steps

You should now have a good understanding of the techniques you can use to debug even the most stubborn JavaScript program. Now move on with one of the following:

• To build a full-scale JavaScript application, see Chapter 15, "Real-Life Examples III."
• To learn issues involved when working with JavaScript and Java, see Chapter 16, "Integrating JavaScript with Java."
• To learn tips for debugging CGI programs used with JavaScript and forms, see Chapter 17, "Combining JavaScript, CGI, and SSI."
• To learn more about Microsoft Internet Explorer and its scripting capabilities, see Chapter 18, "Using ActiveX and Microsoft Internet Explorer 3.0."
• To learn about proposed and rumored features for future versions of Netscape, see Chapter 20, "The Future of JavaScript."

Q&A