What’s new with Acrobat 8 JavaScript

Learn about the Acrobat JavaScript features in Acrobat 8.

By Thom Parker – February 12, 2009

Level: Intermediate
Acrobat 8
Prerequisites: Familiarity with Acrobat and Acrobat JavaScript

With each previous version of Acrobat, the JavaScript DOM (Document Object Model) has improved by leaps and bounds. The DOM is the set of objects that expose Acrobat functionality to Acrobat JavaScript. JavaScript was introduced in Acrobat 3.02 with a paltry seven objects. Acrobat 4.0 cleaned up and filled out the basic functionality. Acrobat 5.0 super-charged the DOM with the addition of Application Level services like ODBC access, text to speech, security and digital signatures, as well as increasing the functionality of existing objects. Acrobat 6 introduced advanced services like SOAP, multimedia, OCG, toolbar buttons and full custom dialogs. Acrobat 7 added XML processing and two new JavaScript DOMs — XFA (LiveCycle) and 3D.

So what has Acrobat 8 got for us? Well, Acrobat 8 is a mixed bag. It’s the first version of Acrobat that actually cuts out functionality and the number of updates is much lower than in previous releases. The choices for the updated functionality are also a bit curious. However, there are some very powerful additions, as well as useful updates. We’ll cover just the new features in this article.

Just the good stuff, please

One of the most exciting new features in Acrobat 8.0 is the ability to apply Reader Rights Enabling to PDF files for Fill and Save, Commenting and Digital Signatures. This powerful new feature makes JavaScript functionality available that was once literally out of reach for most developers because it was only available through a very expensive server. It’s as if the Acrobat DOM instantly gained a heap of new functionality that was once forbidden. The sinister bit about this functionality was that it would work in Professional (while the developer was working on it) and then fail when the PDF was loaded into Reader. But no longer. These rights open up a host of operations on manipulating fields and handling data. Below is an example of a PDF that Acrobat 8 Rights Enabling made possible; however it will only work properly on Reader 8.

Example file available
Download [PDF, 354KB]

To be clear, for some operations such as fill and save, Acrobat 8 Rights Enabling is backward compatible with Reader 7. But this example file uses Form Field creation, which is only works on Reader 8.

The usual suspects

There are currently two major trends in Acrobat JavaScript. First, there is a push toward greater security. This is, of course, due to the increase in spoofing, spam and generally intrusive software. Security is sort of the theme behind many of the changes in Acrobat JavaScript. Second, there is a push toward greater use of LiveCycle (XFA) forms. I won’t be discussing LiveCycle JavaScript in this article, but the fact is that no updates were made to AcroForm JavaScript, the traditional PDF-based Acrobat forms technology. Together, these two trends mean that document scripts are becoming more restricted in what they can do, and new additions to Acrobat JavaScript tend to lean more toward Automation/Workflow functionality, rather than document-form scripting. Let’s look at some specifics.

A standard in every new version of Acrobat JavaScript is the expansion of existing functionality and Acrobat 8.0 is no exception. But as explained above, much of this expansion has to do with security features. Several security-related objects have been beefed up with additional properties; Certificate, SignatureSeedValue, SignagureInfo, RDN (relative distinguished name), and the doc.getLegalWarnings() function have also been improved. These feature updates are aimed at improving the granularity with which JavaScript handles security.

There are also some miscellaneous upgrades to other, non-security-related functionality. The doc.openDoc() function has a new parameter for opening a PDF to a Named Destination. This feature is a great advancement for Documents on CD or any other multi-document application where tight navigation between documents is necessary. The Doc Object has a new XFAForeground property to support the new LiveCycle feature for using an existing PDF as background. The Doc Object also has a couple new functions, doc.exportAsFDFStr() and doc.exportAsXFDFStr(). These functions expand the range of data-handling capabilities for JavaScript. They put the export data into a form that can be manipulated with ordinary JavaScript string operations and exported through non-traditional means — for example, stuffed into an embedded file, or uploaded to a server script with the new Net Object.

Power to Acrobat (the big features)

Acrobat 8.0 has three new power features, page content color conversion, booklet printing and the Net Object. A power feature is one that does a lot with very little code and the first one on the list is a good example. The Doc Object has a new function called colorConvertPage(). This amazing function converts the colorspaces for every element drawn on a PDF page; images, text and paths. For example, say you need to convert to CMYK before sending your document out for printing. With this function you can convert not just to CMYK, but to any of several color profiles available on your system. Acrobat ships with several well-known, industry-wide color profiles. Of course, colorspace conversion can be done with the Preflight Tool and the Touchup Object Tool, but this capability allows color-space conversion to be part of an automation or workflow script.

Booklet printing is a subset of imposition, which is the art of arranging page tiles on a larger sheet (both front and back sides) so the sheet can be folded into sections (or booklets). These booklets can then be placed together to make an entire book. Acrobat only arranges four pages per sheet, two front and two back. Booklet printing is set up through the PrintParams Object with a group of settings. There are a bunch of these settings and they can look confusing, but only one of them needs to be set to use this feature. Like colorspace conversion, this feature is also available in the user interface (new in 8).

The first internet communication method available to Acrobat JavaScript was HTTP Request/Response through the doc.submitForm() function in Acrobat 3. This was useful, but very limiting. In Acrobat 6, things got a lot better with the SOAP Object, which provides access to Web Services. Still, many of the protocol details were hidden from the JavaScript programmer. Now in Acrobat 8.0, the SOAP object has been moved to the more general Net Object. The Net Object blows the doors open by providing the ability to communicate directly with HTTP. This object gives the user fine control over the details of the HTTP Request, including the HTTP Verb and all settable header fields. The response is handled asynchronously by a function passed into the Net.HTTP.request() function. Control over the HTTP Verb is very important. It allows a script to communicate with more than just the standard HTTP calls, such as PUT, GET and POST. It can, for example, also control a WebDAV server.

But it does contain some very powerful additions. I’m hopeful there are plenty of things already on the table to be released in one of the minor updates. There are probably several already in the current version waiting to be released (i.e. documented). At least I hope so.

See it for yourself in the official Acrobat JavaScript Reference:
www.adobe.com/devnet/acrobat/
Click on the “Documentation” tab and scroll down to “JavaScript.”