Acrobat User Community

So where does JavaScript go in Acrobat?

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

Script Location	Privileged	Access (Acrobat Professional)
Application Scripts – Scripts associated with the Acrobat Application
Console Window	True	An immediate mode command window located on the JavaScript Debugger dialog.
Folder Level	True¹	Disk file with ".js" extension. Created with external text/code editing tool. Located in the JavaScript folders. Find with: Local: app.getPath("user","javascript"); Global: app.getPath("app","javascript");
Action (Batch Sequence)	True	Acrobat X – Tools Panel, Action Pane Acrobat 9 and earlier – On Batch Command list, from the Menu-item: Advanced>Batch Processing…
Menu Item	False²	Created in JavaScript with: app.addMenuItem();
Toolbar Button	False	Created in JavaScript with: app.addToolbarButton()
Timer	False	Created in JavaScript with: app.setInterval(); app.setTimeOut();
Stamp	True	Field calculation script on the PDF for a Dynamic Stamp. Find the stamp folder with: app.getPath("user","stamps");
PDF Scripts– Scripts inside a PDF document
Document –Level Scripts	False	Acrobat X – On Tools Panel, JavaScript Pane. Acrobat 9 and earlier – On Menu item: Advanced>JavaScript>Document JavaScripts…
Document Actions	False	Acrobat X – On Tools Panel, JavaScript Pane. Acrobat 9 and earlier – On Menu item: Advanced>JavaScript>Set Document Actions…
Page Actions	False	Actions tab on the Page Properties dialog. Can only be accessed from the menu on the Pages navigation tab.
Bookmark Actions	False	Actions tab on the Bookmark Properties dialog. Can only be accessed from the menu on the Bookmarks navigation tab.
Field Scripts/ Widget Actions	False	Actions, Format, Validate, and Calculate tabs on the Field Properties dialog. Accessed from the Select Object Tool right-click Popup Menu
Link Actions	False	Actions tab on the Field Properties Dialog. Accessed from the Select Object Tool right-click popup menu
XFA Scripts	False	Adobe LiveCycle Designer
3D Annotations	False	External script editing tool only, Acrobat 7 and later. Then it's imported from the Annot3D properties dialog.
Rich Media	False	Located inside SWF ActionScript, so it's entered with a Flash development tool. Acrobat 9 and later.
External Scripts – JavaScript code applied to Acrobat from an external source
FDF Files	False	External text-editing tool, or FDF-creation tool
The JSO ActiveX module	False	Injected through the Acrobat ActiveX interface from a Visual Basic Application, Windows only.
Acrobat plug-ins	False	C/C++ development tools

¹ 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.