Learning Centers

Debugging Acrobat JavaScript

October 28, 2004


Editor's Note: This article is part of the Introduction to Acrobat JavaScript Learning Center

You'd be hard pressed to find someone who has developed with Acrobat JavaScript and hasn't had a problem that has stumped them (of which can sometimes end up with the developer kicking themselves when they discover it's such a simple problem). When this happens, it usually results in the person writing the JavaScript to play around with their code, or ask a fellow JavaScript developer on one of the PDF related user forums.

If you're the type of person who likes to try and solve such problems first before asking for help, then there are a number of different ways you can debug your code in an attempt to get to the bottom of your problem. In this article we'll briefly look at the app.alert and console.println methods for checking variable values, and then introduce you to the Acrobat JavaScript Debugger, which allows you to step through your code line by line for a better look at your code.

The app.alert Method

The app.alert method is used to display a message to the user (and can also receive a response from the user, but we wont go into that here). It's also a useful tool for checking values of variables you use in your JavaScript code.

// get user's name
var fieldValue = app.response("Please enter your name");

// set form field value with user's name
var objField = this.getField("txtName");
objField.value = fieldValue;

In the above example code, we ask the user to enter their name into a textbox and then set the form field 'txtName' with the name they entered. If everything went perfectly, then after the user entered their name, this would appear in the PDF form field ('txtName'). However, imagine that for some reason it wasn't working, and you wanted to find out where the problem is. So we'll add some app.alert calls so we can see what is happening when the code is executed.

// get user's name
var fieldValue = app.response("Please enter your name");

// set form field value with user's name
var objField = this.getField("txtName");

// check to ensure we retrieved this form field
if(objField != null)
  // form field retrieved
  app.alert("Form field found");
  // set value
  app.alert("Inserting value: " + fieldValue);
  objField.value = fieldValue;
  // form field not found
  app.alert("Form field NOT found");

As can be seen in the bolded lines in the above code, we've used the app.alert method to (a) inform the user whether the form field was retrieved successfully or not, and (b) if it was retrieved then to inform the user of the value being inserted into the form field.

Once you've got all your code working as expected, then there is no longer any need to include these app.alert debug statements so they can be removed.

The console.println Method

The console.println method works in a similar way to the app.alert method, in that it allows you send output to the user. However, rather than displaying an alert box to the user, the console.println writes the output to the Acrobat console.

Note: You can access the Acrobat console under the Advanced menu, by clicking 'JavaScript > Debugger' or the Ctrl+J shortcut. If the debugger menu item is disabled you need to enable the interactive console in Acrobat's preferences (Edit > Preferences > General > Enable interactive console).

This method comes in use when you want to review the output after your code has executed. For example, if you wanted to inspect the contents of each form field in your document and you had a large number of fields, you don't really want to have to click 'OK' to close each alert that appears when using the app.alert method. Thus, if you use the console.println method instead of app.alert you can simply show the Acrobat console once your code has executed to view the output.

// loop through each form field in PDF
for(var i=0; i<this.numFields; i++)
  // write the name/value of this form field to console
  var fName = this.getNthFieldName(i);
  var f = this.getField(fName);
  console.println(Name: " + f.name + ", Value: " + f.value);	

Output in the Acrobat Console

Figure 1. Output in the Acrobat Console

Acrobat JavaScript Debugger

The Acrobat JavaScript Debugger was introduced with version 6.0 of Adobe Acrobat (only the Professional version includes the Debugger), and can be turned on in the Preferences section (Edit > Preferences > JavaScript) by checking the 'Enable JavaScript debugger after Acrobat is restarted' option. The debugger allows you to step through your code line by line, set breakpoints and inspect variables via the debugger dialog.

Note: A "breakpoint" is a placemarker that tells the application to pause at that point to allow the user to inspect variables.

Once the debugger is enabled (if it wasn't, you will need to restart Acrobat after selecting the checkbox), we need to tell Acrobat that we wish to run any JavaScript code that executes in 'Debug Mode'. This is achieved in Acrobat under the Advanced menu, by clicking on 'JavaScript > Debug from Start'. Once you've finished debugging your code, you can turn the debugger off by clicking on the same menu item (JavaScript > Debug from Start).

Whilst it's possible to use app.alert and console.println calls to try and locate problems with your code, using the JavaScript Debugger allows you to inspect any of the variables that are being used and also gives you a good feel for the flow of your code.

Running JavaScript in debug mode

Figure 2. Running JavaScript in debug mode

In the above screenshot you can see Acrobat executing JavaScript in debug mode. In this JavaScript there is a function (called 'calculateMe') that receives an array of numbers as a parameter, adds all the numbers up, and then returns the total. By running the code in debug mode, we can step through each operation line-by-line to understand exactly what is happening. The code that's being executed is in the main panel (and the current line is represented by the yellow arrow), whilst the variables being used can be inspected in the top right panel (you can see each of the values contained in the array 'myArray').


Each of the three techniques we've discussed for debugging your Acrobat JavaScript are relevant to anyone looking at enhancing their Acrobat and PDF experience using JavaScript.

Which technique you select to use depends on the problem you have at hand, whereby for debugging a simple problem you might try using straightforward app.alert or console.println methods, but if you need to inspect a large number of variables and/or get a greater understanding of how your JavaScript code is being executed, then the Debugger can provide this higher level of intelligence to the JavaScript developer.

For anyone looking for more information any of these three techniques, you should consult the related JavaScript documents in the Adobe Acrobat SDK, which can be found at the Adobe site.

More Info

PDF In-Depth Free Product Trials Ubiquitous PDF

Debenu Quick PDF Library

Get products to market faster with this amazing PDF developer SDK. Over 900 functions and an equally...

Download free demo

Five visions of a PDF Day

In the world of PDFs or as we like to say Planet (of) PDF, a year isn't a real PDF year without an intense few days of industry knowledge sharing.

May 15, 2018
Platinum Sponsor

Search Planet PDF
more searching options...
Planet PDF Newsletter
Most Popular Articles
Featured Product

Debenu PDF Aerialist

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link control. Take Acrobat to the next level.


Adding a PDF Stamp Comment

OK, so you want to stamp your document. Maybe you need to give reviewers some advice about the document's status or sensitivity. This tip from author Ted Padova demonstrates how to add stamps with the Stamp Tool along with related comments.