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.

Win an Annual Membership to Learnable,

SitePoint's Learning Platform

  • kangax

    “apply” is a property of Function.prototype, not Function object. There’s a small but subtle difference, since being a property of Function.prototype is what makes apply available on all functions (created with that particular constructor)

  • Rick E

    Could you post a sample PDF with some of these features? That is, an end result to work towards.
    Cool subject though.

  • CoastalData

    The universal problem with Acrobat is the very low adoption rate of any new Adobe technologies… So what if the new version supports JS 1.7, the most used version of Acrobat is 5, and so anything that you do with this new version won’t work correctly with the zillions of users out there who have absolutely no desire to upgrade.

    Acrobat has become of those inescapebly undesirable “non-technologies” that ingrained into the Internet as a necessary evil that most users would gladly do without, if only HTML had the capacity to handle layout better.

    So, my point? Don’t get too jiggy with the javascript if you intend to widely distribute your PDFs unless you don’t mind being doomed to failure!

  • Isn’tAnyoneEditing?

    it’s = it is

  • Anonymous

    My comments mirror CoastalPoint’s, but the article would have been even better than it already was — and it was good — if the article readers were advised what’s the first Acrobat Reader version that understands the JavaScript…the article seems to imply Acrobat 9, but never comes out directly and says it.

    May we suggest re-releasing / re-emailing the article over again, with the new added information?

  • josephrot

    My comments mirror CoastalPoint’s, but the article would have been even better than it already was — and it was good — if the article readers were advised what’s the first Acrobat Reader version that understands the JavaScript…the article seems to imply Acrobat 9, but never comes out directly and says it.

    May we suggest re-releasing / re-emailing the article over again, with the new added information?

    [ Sorry, the previous initial log-in failed to log right...repeating with my member name info. ]

  • Seth

    I don’t know a lot about existing capabilities of PDF, but it has always seemed to me that it is a technology frequently used because it is non-volatile and secure (insomuch as it produces documents in a “fixed” state.) That makes it a pretty good choice for legal documentation, etc. Why add a very volatile and exploitable technology? It seems to me that this makes PDF less desirable for its niche purpose. I’ll have concerns in the future when asked to have my digital signature applied to something that I now know may have JavaScript embedded in it.

  • http://tetlaw.id.au Andrew Tetlaw

    Hi folks,
    according to the API docs:

    v3.01, v4.0 = JavaScript 1.2
    v5.0, 6.0, 7.0 = JavaScript 1.5
    v8.0 = JavaScript 1.6
    v9.0 = JavaScript 1.7

  • Dimitri

    Thanks for introducing a new crowd to JS in PDFs. The use of Acrobat to create e-forms is exploding and it is not easy to create efficient, usable forms without some scripts in there ( lists, submission buttons, calulations, validation of data, etc).

    Many examples of how scripts are used in PDF forms and documents can be found at Acrobatusers.com- especially in the JavaScript Corner section (http://www.acrobatusers.com/tech_corners/javascript_corner/index.php), and for those who want to learn Acrobat JS, an on-line training course and lots of scripts and examples can be found at a new subscription site http://www.pdfscripting.com

    Dimitri Munkirs
    WindJack Solutions, Inc
    http://www.windjack.com
    http://www.pdfscripting.com

  • Dimitri

    The link in my previous post is now incorrect for JavaScript Corner at acrobatusers.com. “Tech Corners” were changed to the “Learning Center” during a site redesign. All Acrobat and PDF JavaScript tutorials can now be found at-
    http://www.acrobatusers.com/learning_center/tutorials
    (use the search term “JavaScript” to filter for that topic)

    Happy scripting!

    Dimitri
    WindJack Solutions
    http://www.pdfscripting.com
    http://www.windjack.com

  • John

    Is it possible to set the focus from one application to another, similar to AppActivate in VBS? If so, does anyone have an example?

    Thanks,

    John

  • Randy

    I can see there is a lot to learn about Acrobat Javascripting… is there a good book to read that takes into account ones beginning in this field?