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

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

True1

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

False2

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

1 Only at Acrobat start-up. Functions defined here are not privileged.
2 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.



Related topics:

JavaScript

Top Searches:


0 comments

Comments for this tutorial are now closed.

Comments for this tutorial are now closed.