This tutorial shows you how to work with the JavaScript features in Acrobat 9. See what the all-new Acrobat DC can do for you.

Download a free trial of the new Acrobat.

Scripting for Reader 9

Learn about the various restrictions of Reader 9 scripting and methods for testing and debugging code.

By Thom Parker – December 1, 2009

Just about all PDF documents are intended to be viewed at some point in Reader. If a document includes scripts, and this is especially true for forms, then it must be tested in Reader. Not all operations in Acrobat JavaScript will work in the Reader scripting environment, and some operations require Reader Rights Enabling in order to work. In this article, we’ll explore the various restrictions of Reader scripting and methods for testing and debugging code directly in the Reader environment.

By the way, when you see the capitalized word "Reader" in this article it means Adobe Reader.

Reader script restrictions

Reader is a much smaller and more restrictive tool than Acrobat Pro. Reader is free and intended for viewing PDF files, not creating and modifying PDF files like Acrobat. So in general, any operation that’s related to PDF creation and modification is not allowed. To be more specific, Reader coding restrictions can be placed in 4 categories:

Operations that are completely forbidden.
Operations that are only possible if the PDF is Rights Enabled for that operation.
Operations that are version dependent.
Operations that require Privilege.

The Acrobat JavaScript Reference uses a Rights (or Quick) Bar (Figure 1) to indicate which restrictions apply to which functions and properties in the AcroForm model. The Rights Bar is a group of at least four boxes. Each box displays a specific restriction on the usage of a scripting operation. The Rights Bar is a mandatory reference when deciding whether or not an operation can be used in a particular scripting environment.

Figure 1 – Each box in the Rights Bar indicates a specific usage restriction

The Acroform Model is the oldest Document Object Model in Acrobat and the one used for scripting Acrobat forms and automation scripts. Unfortunately, the documentation for the LiveCycle Scripting Model is not so clear when it comes to providing the same information. However, as a rule of thumb, only the functions and properties in the LiveCycle Host and SourceSet models have restrictions on them; everything else is open for use in Reader. A little known secret is that the Host Model functions actually call the equivalent AcroForm functions. You can get an idea of how these functions are restricted by looking in the Acrobat JavaScript Reference.

Let’s take a closer look at how these restrictions work by examining the Rights Bars for some common scripting functions. The Rights Bar shown in Figure 2 is for the most common function used in any PDF script. The Doc.getField() function is used the acquire a Field Object.

Figure 2 – No usage restrictions

This function is an absolute necessity for any kind of form-field handling, so it’s important for it to work in Adobe Reader without any restrictions, which is exactly what the Rights Bar shows. The first box indicates that getField() was first added to Acrobat/Reader in version 3.01. This is also the first version of Acrobat that contained JavaScript, so this function was one of the originals. The following boxes are all empty, meaning there are no restrictions. This function will, for all practical purposes, work in all versions and variations of Acrobat, including Adobe Reader.

Now let’s look at a heavily restricted operation, the Doc.insertPages() function (Figure 3).

Figure 3 – Can only be used under special circumstances

This function was added to Acrobat in version 5. Knowing the version an operation was added in is very important. It is generally a bad idea to use operations added in the most recent versions of Acrobat, because many Reader users will still be at least one or two versions behind. It is also common for Adobe to add new features (function inputs) to an existing operation. This information won’t be listed in the Rights Bar, so be sure to read all the documentation for the features you’ll be using.

The version number listed here is old, so if it wasn’t for the other restrictions, we’d be OK using this function. However, the fourth and last column has an X in it. This is the Reader column and the X tells us this operation does not exist in Reader. Further, column three has a red S, indicating that the function also requires privilege, meaning for the most part that it cannot be used in a PDF script at all. This function can only be used in an Acrobat automation script. It’s not even close to suitable for a script in a document viewed in Reader.

The Field.setItems() function (Figure 4) is used to set the items in a list. This seems like a very standard form operation. Acrobat considers anything that changes a field property to be a document modification, which requires a special right to be performed in Reader. The D in column two indicates this function modifies the document. Nearly all operations with a D in this box will also require a Reader Right. In this case, since the function affects a form field, it requires Form Rights. Other operations that require this same Right include modifying the fill color, border style, field font, and similar operations.

Figure 4 – Any operation that modifies the document usually requires Form Rights

Unfortunately, the Rights Bar for this particular operation is a bit of a deception. It, and all the other list item operations, does not require Form Rights to work in Reader. In fact, many of the entries in the Acrobat JavaScript Reference are mis-marked. Another example is the Soap connect function. The reference indicates that the connect() function requires Form Rights when, in fact, it requires a different Right. Make sure you thoroughly test the operations you want to use in the targeted Reader versions. Do not rely entirely on the JavaScript Reference.

Two features that forms designers like to put on their documents are custom print and save buttons. The Acrobat JavaScript model provides functions for both these features. However, a quick look at the Rights Bars for these functions shows that there are issues with both. For the Print function, Doc.print() (Figure 5), the only restriction on is that something about it requires privilege, as shown by the red S in column three.

Figure 5 – One feature of the print requires Privilege

This does not mean the print() function cannot be used in a document script. It does mean that some care is needed when using this function, and a little further reading in the documentation reveals this note (Figure 6).

Figure 6– Typical security note for any operation with a red S in column three

Notes like this are standard for any operation with a red S in the Rights Bar. In this case, the note indicates that only non-interactive printing is Privileged, meaning that Acrobat does not allow a document script to print silently. In the Acrobat security model, the user must approve all operations that touch resources outside of Acrobat/Reader. This type of restriction on the print() function and any other similar operation is expected.

The save function, doc.saveAS() (Figure 7), has two restrictions as shown by the entries in the last two boxes of the Rights Bar. The S in the last box, the Reader box, indicates this function can be used in Adobe Reader, but only if the PDF is enabled with Form Save Rights. The security note for the red S in column three indicates the entire function is privileged. The result of these restrictions is that the save function is not suitable for generally distributed documents; but it is useful for certain types of forms that will be viewed in Reader. To understand this, both of these restrictions require more explanation.

Figure 7 – Requires both Reader Rights and Privilege

Reader rights

There are a number of operations available in Adobe Reader that are blocked unless the document has been enabled with a Right specific for that operation. When Adobe first added these enabling rights, the only way they could be applied to a PDF was with a special Adobe Rights Server. Few customers could afford this server, so the general attitude was if an operation required Rights Enabling, then it might as well not exist because you couldn’t use it.

In Acrobat 7, commenting rights (the ability to apply markup comments to a PDF) were added to Acrobat Professional. Then in version 8, Form Save (the ability to save a filled in form), Form Rights (performing advanced field manipulation), and Digital Signing Rights were added to Acrobat Professional. These Reader Enabling Rights opened up a whole new world of scripting functionality that could be applied to a PDF viewed in Reader. However, there are still several Rights that can only be applied by what is now called the LiveCycle ES Rights Server. These include File Embedding, Spawning Page Templates, SOAP operations, as well as a few others.

Reader Enabling Rights are like a digital signature. They mark the whole document and any changes made to the PDF after the Rights are applied will invalidate them. So this is the very last thing that should be done to a PDF using these features.

Privilege

Some operations in the JavaScript model are considered dangerous because they could potentially be used to create malicious scripts, for example any operation such as the doc.saveAs() function that writes to the users hard drive. But they are, of course also very useful operations. To use one of these, it must be granted Privilege. Privilege is just a way for the user to say that they trust a script. There are two main ways to give a script Privilege. The most robust method is to create a Trusted Function. This is a script file that is installed on the user’s system.

The second method is to digitally certify the PDF, then install the digital signature on the user’s system so the signed file can be verified by Reader. When the certification is verified, all scripts in the PDF become privileged. The downside to this methodology is that it’s possible for older versions of Reader and for Acrobat users to make changes to the PDF that invalidates the certification, thus destroying the privileged operation. If both Reader Rights and Digital Certification are applied to a PDF, the certification must be done last.

Both of these methodologies require changes to be made to the user’s system. This means that privileged operations are not suitable for generally distributed documents. They can only be used within a more intimate environment. For example, the trusted function methodology is perfect for use within a single office or company. The digital certification methodology is often used with customer/vendor forms since trading digital signatures is more controllable and practical than installing and maintaining scripts at remote locations.

Testing and debugging in Reader

Adobe does not recommend this, but it’s very useful to have Adobe Reader on the same system as Acrobat so you can develop and test on the same system. In fact, both Reader and Acrobat can be open at the same time, so you can modify a PDF in Acrobat and then immediately test it in Reader. To do this, you’ll need to add a shortcut (or link) to Reader on your desktop. The shortcut should use a line like this one to reference the Reader program:

"C:\Program Files\Adobe\Reader 8.0\Reader\AcroRd32.exe" /n

The "/n" option specifies a new window. Normally, if Acrobat or Reader is already open, then any reference to either executable will defer to the already open program. The "/n" option overrides this behavior.

Installing the console window

The most useful test and debug tool in Acrobat is the Console Window. The console is not a native feature in Reader, but Adobe added it as an optional feature to Reader 7 and later. Three things need to be done to install and activate the console window in Reader.

A file named "debugger.js" must be copied from the Acrobat JavaScript folder into the Adobe Reader JavaScript folder. It’s best to copy this file between equivalent versions of Acrobat and Reader.
The settings for Reader have to be modified to enable and allow access to the console window. (The links below provide detailed information on the specific settings)

On Windows these settings are in the Registry key:
HKEY_CURRENT_USER\Software\Adobe\Acrobat Reader\8.0\JSPrefs\
On the Mac these entries are in the Property List File found at:
:Library:Preferences:com.adobe.Reader8.0.plist

Some way to display the console needs to be set up. The code:
console.show();
is all that is needed. This code can be run from a toolbar button or menu item. The toolbar button is the most convenient.

A kit for setting up the console can be found here: http://www.pdfscripting.com/public/65.cfm. It includes a toolbar button script, a Registry file for windows installation, the debugger.js file for Acrobat 8, and instructions. More information can also be found in the Acrobat JavaScript Guide, also labeled as "Developing Acrobat Applications using JavaScript."

Debugging

It’s best to start out by opening your non-Reader Enabled PDF in Reader to see how things work. This will help reduce development time and save testing the operations that require Reader Enabling until everything else is tested. You can also save time by using the console window to test out code before entering it into scripts in the PDF.
If the console reports an error, it’s more than likely it will report a security error, regardless of the actual error (Figure 8). In this example, the Doc.addField() function requires Form Rights and the error will stop being reported when the PDF is Rights Enabled.

Figure 8 – Most of the time Reader will report a security violation regardless of the actual error

It is also important to be version aware. Documents that are Reader enabled will work best when viewed in the same version of Reader in which they were enabled with Acrobat because Reader Rights tends to be a shifting landscape. For example, a document that was Reader Enabled in Acrobat 8 has a script that changes the fill color of a form field under some special circumstance. When viewed in Reader 8, the form can be filled out, saved, then reopened and modified without a problem. When the same PDF is viewed in Reader 9, it can be filled and saved without a problem until the code that changes the field fill color is activated. If this happens, the Rights Enabling will be invalidated the next time the PDF is opened.

This situation is a quirk of the particular versions involved and the issue has changed with minor version updates from Adobe. Reader Rights, as well as security issues, are shifting sands. So always test the PDF on the target platforms, and try not to use too many operations that require Reader Rights.

Happy Reader Scripting!!