This is the first in a series of tips on accessing the locations where JavaScript is used in Acrobat and PDF. JavaScript is the scripting language behind many of the interactive features in PDF as well as the primary tool for automating Acrobat. It is important to note that the JavaScript model for Acrobat is significantly different than the more well known JavaScript model for HTML pages and web browsers. These script locations in Acrobat represent one of the biggest differences between the models and knowing about them is essential for anyone starting to develop Acrobat JavaScript.
Script locations
JavaScript is a massively useful tool. It can be 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 of these locations is associated with an 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). There is a script location inside the PDF file associated with each.
So what are all these 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.
The table breaks the script locations into three categories:
- Application scripts
- PDF scripts
- External scripts
Application-scripts are associated with the Acrobat application. They exist in files on the user’s system, are created by tools in Acrobat, or are created dynamically by another Application-script. Application-scripts that exist in external files are loaded and processed when Acrobat starts up. Because Acrobat knows about them at startup time, these scripts enjoy a high level of trust (also called privilege). A privileged-script location can run code that in other locations (a script that is inside a document for example) would be considered a security risk.
PDF scripts include page scripts, bookmark scripts, form field scripts, and any other script that physically exists inside a PDF. This is not official Acrobat terminology and is only used as a convenience here for grouping these scripts into a single category. All of the PDF scripts are entered into their proper locations using the scripting tools built into Acrobat Professional. 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 entered into Acrobat from locations outside the Acrobat JavaScript environment. For this reason, external tools have to 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 |
On JavaScript Debugger dialog |
|
Folder Level |
True1 |
External editor, files are located in the JavaScript folders Local: app.getPath("user","javascript"); Global: app.getPath("app","javascript"); |
|
Batch Sequence |
True |
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 |
All field calculation scripts on the PDF for a Dynamic Stamp. Find the stamp folder with: |
|
PDF Scripts– Scripts inside a PDF document |
||
|
Document –Level Scripts |
False |
Menu item: Advanced>JavaScript> Document JavaScripts… |
|
Document Actions |
False |
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/ |
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 Tabs on the Field Properties Dialog. Accessed from the Select Object Tool Right-Click popup menu |
|
XFA Scripts |
False |
Adobe LiveCycle Designer 7 |
|
3D Annotations |
False |
External script editing tool only, Acrobat 7 and greater |
|
External Scripts – JavaScript code applied to Acrobat from an external source |
||
|
FDF Files |
False |
External text-editing tool, or FDF creation tool |
|
The JSO |
False |
Visual Basic development tools |
|
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.
In the coming weeks, we’ll publish tips with instructions on accessing the most important of these script locations.
