An Introduction to JavaScript for Acrobat

Being a JavaScript fan I’m always interested to see how JavaScript works on non-browser platforms. You may not be aware of this but Adobe Acrobat has a complete JavaScript API with which you can add interactivity to PDF files. So I thought I’d investigate the JavaScript support available in Acrobat from a web developer’s point of view.

JavaScript in PDF files is used to interact with bookmarks, annotations, links, buttons, custom dialogs, embedded media, forms, searching and quite a lot more. It can be used at the application level and in batch operations, but also saved with PDF files. When it is saved within the PDF file, compatible viewer applications are able to run the JavaScript.

Is it Really JavaScript?

In web development our use of JavaScript is intertwined with the browser’s DOM API, and we don’t often separate the two. Acrobat 9, a component of most versions of the recently released Adobe Creative Suite 4, supports JavaScript 1.7, complete with all the top level objects you’re used to like Date and RegExp. You can use closures and functions can be passed around as objects. Object properties can be accessed via their names or dot notation; app.language and app["language"] both refer to the same property.

Acrobat has it’s own document API and a variety of supporting objects. The first oddity I found though, was that the this keyword always refers to a Doc object that is the reference to the current PDF document; similar to the window object in browsers. Even in the context of the MouseUp event of a button object, this is still a reference to the current document. Although, the apply method of the Function object can still be used to change what the this keyword refers to.

The Acrobat JavaScript API

The API uses the named parameter style of passing arguments to functions that has become popular in JavaScript libraries. Each API function can take an array of key/value pairs as a single argument. For example we call the app.alert function — much the same as the browser alert function — like this:

var result = app.alert({
  cMsg: "Are you going to click it again?",
  cTitle: "You've clicked the Big Red Button!",
  nIcon: 2,
  nType: 2
});

The values cMsg and cTitle set the alert dialog message and title respectively. The icon and buttons displayed are specified by the last two values. The buttons that are specified also determine the possible return values. we’ve specified nType of 2, so the dialog will display a Yes and a No button, returning 3 if No is clicked and 4 if Yes is clicked.

Event handling is implemented using actions. For example if we wrapped the above call to app.alert in a function called getChoice, we can then set it to be called when a button is clicked:

button.setAction("MouseUp", "getChoice()");

Programmer Features

Acrobat has a JavaScript debugger with an interactive console, but the JavaScript editor has a lot to be desired. You get a plain text box in which to type; no syntax highlighting, no code hinting, no code completion — it’s like editing using Windows Notepad, made slightly worse because there’s no undo either. Mercifully you can use an external editor. It does have one redeeming feature though, a syntax checker. You won’t be able to save your JavaScript if it has syntax errors; a feature I wish more text editors had.

Advanced JavaScript

JavaScript in Acrobat has a number of features you won’t find in browsers. Direct database access is provided by the ADBC object, the SOAP objects enables access to web services using the SOAP protocol. JavaScript for Acrobat has the ability to read and write files and data streams, and E4X, the JavaScript XML processing extension. However, most of these features are intended for enterprise use rather than general web use, because some require Acrobat Professional and some require security level elevation in Adobe Reader.

Compatibility

Compatible viewing applications include Adobe Acrobat and Adobe Reader. Some more advanced parts of the API are only available to Acrobat Professional. Compatible authoring applications include Adobe Acrobat Professional and the open source desktop publishing application Scribus. JavaScript support can be found in other PDF developer libraries, such as PDFDoc Scout for .NET, and JPedal and iText for Java

Getting Help

You won’t get anywhere without these essential documents: The JavaScript for Acrobat API Reference and Developing Acrobat Applications Using JavaScript. Both of these documents and other resources can be found on the JavaScript for Acrobat web page. Unfortunately you may find the information there a little out of date. You can also find the same information in the Acrobat 9 SDK online help site.

Frequently Asked Questions about JavaScript for Acrobat