So where does JavaScript go in Acrobat?

Learn the physical locations where JavaScript can be entered into the Acrobat JavaScript environment.

By Thom Parker – November 7, 2008

 

Scope: Acrobat Professional 6.0 and greater 
Skill Level: Beginner to Advanced, there is something here for everyone
Prerequisites: Familiarity with Acrobat Professional

If you're reading this article, then you've probably already been trying to figure out how to do something in Acrobat and been told "You need JavaScript for that." Acrobat JavaScript is the programming language used to script activities in Acrobat. It is massively useful. It is used to automate and control numerous tasks in Acrobat and PDF documents. One of the side effects of this diverse functionality is a long, sometimes confusing list of physical locations where JavaScript can be entered into the Acrobat JavaScript environment. 

Each location where JavaScript is entered is associated with a specific event. When the event is triggered the script at that location is run. For example, at least two events are triggered when a user clicks the mouse over a form field: Mouse Down and Mouse Up. These are part of a larger class of events (called Widget Events). Since the events are associated with a form field, they are entered in the form field properties dialog.  

So, what are all the other events and how do you enter a script into one? The first thing you need is Acrobat Professional. It comes fully loaded out-of-the-box with all the necessary tools for entering, editing, testing, and debugging Acrobat JavaScript. Table 1 below provides the second thing you need. It is a comprehensive summary of script locations in Acrobat, with a description of how each is accessed from Acrobat Professional. Note that Acrobat Standard X also contains all the tools needed to enter scripts.

The table breaks the script locations into three categories: 

• Application scripts
• PDF scripts
• External scripts

Application scripts are associated with the Acrobat application. They either exist in files on the user's system, or are created dynamically by a script file on the user's system. Acrobat loads and processes these script files when it starts up. Because it knows about them at startup time, many of these scripts enjoy a high level of trust (also called privilege). A privileged-script location can run code that is generally considered a security risk, such as functions that access the local file system.   

PDF scripts include page scripts, bookmark scripts, form field scripts and any other script that are stored inside a PDF. All of the PDF scripts are entered into their proper locations using the properties dialog for the PDF element that is triggering the script event. For example, a bookmark action is set from the action tab on the bookmark properties dialog.

PDF documents can (and usually do) come from outside the user's system, so they are generally not trusted. However, there are special circumstances where code in a PDF is given an increased, but limited level of trust. For example, both Reader extensions and certification with a digital signature convey some amount of trust onto a PDF script.

External scripts are injected into the Acrobat JavaScript engine from locations outside the Acrobat JavaScript environment. For this reason, external tools must be used to access them, and they are not trusted.

Table 1- Summary of script locations in Acrobat

¹ Only at Acrobat start-up. Functions defined here are not privileged.
² In Acrobat 6.0 and earlier, menu-item scripts are privileged. In Acrobat 7, a preference is provided that allows menu-items to be privileged for backward compatibility.