The Acrobat JavaScript Console (Your best friend for developing Acrobat JavaScript)

The Acrobat JavaScript Console window (a.k.a. the Console window) is one of the tools included in the Acrobat JavaScript Debugger. The Console window is by far the most useful tool in Adobe Acrobat for testing and debugging JavaScript code, but it is more than just a utility for testing code. It can also execute code snippets for automating tasks in Acrobat and analyzing documents. In this article, we’ll cover setting up and using this essential tool.

Getting started

If this is your first time using the Console window, you will need to enable it from Acrobat’s Preferences settings. Depending on your platform, use one of the following methods to open the Preferences dialog:

In Preferences, select the JavaScript pane. Make sure both Enable Acrobat JavaScript and Enable interactive console are checked. It’s a good idea to also check Enable JavaScript debugger after Acrobat is restarted so you can use some of the other debugging features, if necessary. 

Another nice feature is the external JavaScript editor, as the default Acrobat editor is very basic. A good JavaScript-specific editor will have advanced features that make code manipulation and navigation easier. 

After these preferences have been set (Figure 1), you’re ready to start using the Console window.

Figure 1 – Acrobat Preferences for enabling the JavaScript Console

See larger image [1]

Activating the Console window

To display the JavaScript Debugger, which is where the Console window resides, use one of the following methods:

Note: On earlier versions of Acrobat, these options are found on the Tools menu.

The activated Debugger is shown in Figure 2.

Figure 2 – Acrobat JavaScript Debugger, Console window selected

See larger image [2]

The Console window part of the Debugger is in the bottom portion of the dialog labeled View (Figure 2). The View pull-down selection list is set to Console, meaning the Console window is being shown. This area is also used to show the Script window (for displaying runtime code). When Acrobat is launched and the JavaScript Debugger opens, a number of status messages are automatically displayed in the Console window. Each line represents a JavaScript module loaded by Acrobat. If there were any problems with these modules, or any others that Acrobat loads, error messages would also be displayed here.

Normally we’re not interested in these initial messages. Clear the window by pressing the button that looks like a garbage can in the lower right corner of the window. Now we have a clean work area and are set up and ready to start using the Console window.

Using the Console to run code

JavaScript code can be executed directly from the Console window. This ability is a huge time saver since it provides a fast and easy way to test out code before it’s placed into a scripting location where it will be more difficult to debug.

Let’s try out some simple examples. Enter the following line of code into the Console window.

3 + 4

To run the code, make sure the cursor is on this line. You can place it anywhere on the line as long as nothing is selected. Either of two following actions will cause Acrobat to run the code.

• Press Ctrl+Enter on Windows, or Command+Enter on Macintosh.
• If your keyboard has a number pad, you can use the Enter key on the number pad without pressing the Control (Command on Mac) key. 

Acrobat displays the result of the execution on the next available line, Figure 3.  

Figure 3 – Simple Calculation in the Console window

Sometimes the result of an operation is not so clean, or obvious.  Let’s try something that doesn’t have such a well-defined result. Enter the following line in the Console window and run it: 

3/0

This calculation has an obvious mathematical error, but Acrobat JavaScript doesn’t display an error message. Instead, as shown in Figure 4, it displays the word “Infinity.” So, a mathematical calculation can create a result that is not a number. Values like this can cause a script to have a problem. It is much easier to find this kind of a problem by executing individual lines in the console window where you can see the results immediately, than it is by debugging it from a field-calculation script. 

Figure 4 –Result of a calculation with a math error in the Console window 

The next line of example code is something that might be used in a real script. It assigns a simple addition to a variable named ‘sum’.

var sum = 5 + 9;

As shown in Figure 5, the return value from this line of code is “undefined.” This is not the return value from the calculation. The calculation is executed and applied to the declared variable, sum. However, the first and primary operation on the line is the variable declaration, so this is the operation that returns a value to the Console window. Unfortunately, variable declarations do not return a value. To overcome this small issue, the Console widow displays “undefined.” This is the same value displayed for any operation that doesn’t return a value, or for variables that have never been declared. 

To display the value of the sum variable, use the cursor to select just the word sum, as shown in Figure 5, then press Ctrl+Enter (Command+Enter on Mac). This action executes just the selected text. 

Figure 5 – Variable assignment in the Console window 

This technique of selecting parts of the code for execution is also useful for executing multiple lines of code.

So far we’ve talked about executing code in the Console window for testing and debugging, but there is no reason to restrict our usage to this limited theme. The Console window is really an “Immediate Mode Command” window — anything entered into this window is executed directly by the JavaScript engine. We can use it anytime we want to execute code for any purpose. 

Two uses for the Console window (besides code testing) that immediately come to mind are automation and analysis. There are several functions in Acrobat for manipulating and for acquiring information from PDFs and Acrobat. Most of these JavaScript functions have Acrobat menu-item equivalents, but a few don’t, so for these operations the Console window is the only immediate access. The main advantage of using JavaScript is greater flexibility in how you can deal with a particular operation. For example, suppose you wanted to know the exact border color of a text field so you could use the same color in another location. Assuming the current document has a field with the correct name on it, you could use the following code in the Console window:

this.getField("MyButton").strokeColor;

The result of this operation is a color array. Arrays are converted to text by converting each individual array element into a text string, so the result would look something like the following line when it is displayed in the Console window.

"RGB",255,0,0

This is an example of document analysis with JavaScript. We’ve just found out something that would have taken us just a little more effort to find out using the Acrobat property dialogs, and the information is in a very usable format. We can easily copy and paste this information to accomplish some other purpose, for example applying the color to another field with this line of code:

this.getField("MyButton2").strokeColor = ["RGB",255,0,0];

The real advantage is that by using JavaScript, we can automate this analysis for the entire PDF. Suppose a document needs to be checked for branding purposes, i.e., all the border colors of all fields in the document should match a special color. The following code uses a simple loop to display this color info in the Console window for manual inspection:

for(var i=0;i<this.numFields;i++)
{
  var fNm = this.getNthFieldName(i);
  console.println(i+":"+this.getField(fNm).strokeColor);
}

Because of the loop, this code cannot be executed one line at a time. It has to be done all a once. To execute multiple lines of code, the lines must all be selected before pushing Ctrl+Enter (Command+Enter on Macintosh) to start running it.

Notice that in the loop there is a function called console.println(). It’s in the fourth line. This function writes text to the Console window and it will be discussed in the next section.

Here’s an example of a function that does not have an equivalent on the regular Acrobat menus and toolbars. Enter the following line into the Console window and run it:

app.newDoc();

Acrobat will create a new, blank PDF document. This is perfect for trying out new ideas before applying them to a working document.

The results of this operation are shown in Figure 6 below. Note that yet again, the result is something different.

Figure 6 – Result of running the app.newDoc() function 

The Console window has to convert the result of code execution to text before it can be displayed. Not everything has an obviously meaningful text representation. In this case, the output of the function is a Document Object. Objects are converted to text by simply converting their type information to a string. The result shown in Figure 6 tells us the type of object app.newDoc()created. This result is only useful in letting us know the function worked. If app.newDoc() had failed, it would have either caused an error (discussed later in this article) or returned null. Both of these situations would have been displayed on the Console window.

Enter and run the following line of code:

this.path

The path property is exactly what you might think it should be. It’s the folder path of the current document. Since the current document was just created with app.newDoc() and has not been saved,  this path is for the temporary PDF. The result will look something like this:

/C/DOCUME~1/MyName/LOCALS~1/Temp/Acr1FE.tmp

Of course, this information is easily available in the Document Properties dialog. The advantage to using the Console window is now we can copy this information to the system clipboard for use with another script in Acrobat or for something else.

Using the Console to display status and error messages

Besides testing code, the Console window has one other important role in debugging JavaScript. It is the standard location for displaying status and error messages. The Acrobat JavaScript environment has a built-in error-handling system. When something goes wrong, this error-handling system usually displays some helpful message (sometimes) in the Console window, so this is the first place to look when things aren’t working. In addition, you can create your own status and error messages to display here.

As an example, let’s execute some code we know will cause an error. Enter and run the following line of code in the Console window:

app.openDoc("xx.pdf");

This line of code instructs Acrobat to open a file (xx.pdf) that does not exist, an obvious error (if by some chance you actually have a file with this name, please change the code to use something that’s not on your system). Acrobat responds by generating an error, which is displayed by the Console window, shown in Figure 7.

Figure 7 – Error message generated by a bad file path parameter

The error message shows that the problem is in the cPath parameter of the app.openDoc() function. This message would be critical to finding the problem if the function call was buried in several lines of code inside a PDF. Always check the Console window first when something goes wrong.

We can also create our own messages for display in the Console window. The Console window is defined as an object in the Acrobat JavaScript DOM (Document Object Model). This object provides a few functions for manipulating and accessing the Console window, but for purposes here, only one is of interest, the console.println() function. This function displays a single line of text on the next available line in the Console window. The following line of code displays the words “Hello Acrobat.”

console.println("Hello Acrobat");

The console.println() function is particularly useful for monitoring how code is working. Just place a few console.println() statements at critical locations in your script and you can literally watch the progression of code execution in real time. It is up to the developer to decide which information to display. This information should be relevant to the state of the script.

For example, the following line helps us understand how JavaScript events work in Acrobat. The code can be placed in any script location in a PDF file. Try it out by putting several in different locations in a PDF, a Document script, a Page Action, different JavaScript Field Actions, and so on. It is a good practice to use this code (or something like it) whenever you start a new document scripting project to get a feel for how the different scripts will interact.

console.println("Event Name: " + event.name + " Type: " + event.type);

Watch the Console window to monitor the sequence of scripts that are executed as you open and close the document, navigate between pages, move the mouse around the document or perform other actions.

Summary

All in all, the Acrobat JavaScript Console is the greatest thing since, well, Acrobat JavaScript. Use it early and often to test and debug scripts, and to automate processes in Acrobat.