Acrobat JavaScript Revealed

   There are plenty new changes to Acrobat JavaScript with the soon to be released Acrobat 9.  But, like the changes made in Acrobat 7 and Acrobat 8, it’s not just adding new functions and properties.  The scripting environment has also changed.

   The most obvious change is that the Acrobat JavaScript documentation is no longer a PDF file.  It’s been converted to HTML.  This has the advantage of being online and up to date, and it has good navigation.  But it has the big disadvantage of being difficult to print, or work with offline.  It does come with the Acrobat SDK documentation, so if you are inclined you can download and save the whole thing to a local folder.  

   The next big change is the addition of Cross Domain Policy files.  One constant complaint with Acrobat 7 and 8 is that they are constantly popping up warning messages to the user about linking to stuff at a different domain than the last thing was located at.  Mostly, this issue applies to video and sound files streamed from the internet into a player in Acrobat. But, it also affects form data submissions, email addresses, opening related PDF files, and just about anything where Acrobat touches an external resource, online or not.  Just to see how far Acrobat 8 took this issue, try this experiment.  Place a button on a PDF and add this code to it.

    this.URL;

No other code is needed.  This particular line doesn’t do anything.  It doesn’t access an external resource or do anything to the PDF or Acrobat.  Now click on the button.  Acrobat instantly displays a Cross Domain Warning Message.   What’s that about!! 

   Well, now there is a solution- the Cross Domain Policy file.  This is a technique previously used by Flash and Flex for securely accessing remote resources.  It’s basically an XML file that tells Acrobat it’s ok to get a resource from specific locations.  There are a few different ways to set one up, but for us scripters, we’re interested in the new “app.loadSecurityPolicy()” function.  This function silently loads the policy file from a remote location, which then allows the open document to smoothly display video files, or do whatever else it needs to do without pestering the user with cryptic warning messages. 

   Another update is the ability to apply redaction to a PDF with the new ”Redact” annotation type and the  ”doc.applyRedactions()” function.  First, Redact annotations are added to the PDF.  Then the function is used to apply redaction to everything that the annots cover.  It’s not real sophisticated, but it works.  This is a great new addition for automation scripting.  I just wish Adobe would put more top level Acrobat functionality into JavaScript so I could automate this stuff for my customers.  But at least we got redaction.

   There are a few more additons, like the new “util.crackURL()” function, and some new, long awaited parameters for the “printParams” object.  But I really want to talk about Flash.

  Far and away the biggest change in Acrobat 9 is that the Flash player is built into it.  That’s right, its a permanent part of Acrobat. This may not seem like much, but it opens up a whole new world, the world of ActionScript.  For us scripters this change is apparent in two new things, PDF Portfolios and Rich Media Annotations. 

   PDF Portfolios are an update of the old PDF Packages.  And it’s a big change.  In fact, if you’ve already been using Packages then you may not be very happy with Portfolios.  In a Portfolio, the cover page is replaced with a Flash display.  Theroretically, this opens up the display to all kinds of fancy animations for navigating to embedded files.  We’ll see how this goes.  Acrobat provides some basic templates to help out and hopefully there will be 3rd party Portfolio templates out there. 

   From the Acrobat JavaScript side, there is a new object called a “Collection,” which represents the top level of a Portfolio, and there are some new functions for creating and configuring Portfolios. 

• app.newCollection() - Creates a PDF Portfolio file
• doc.collection - Collection Object, if any, for the file
• Collection object - Properties and methods for managing the Portfolio configuration

  But much more interesting than Portfolios, is the new RichMedia Annotation.   This annotation is like the existing “Screen” annot, except it’s specifically for displaying interactive Flash files.  This is not a replacement for the Screen Annot.  The screen annot has a rich set of JavaScript objects, properties, and methods for controlling media playback, which the RichMedia annot does not.  In the screen annot, only a minimal amount of controlled data can be passed between the PDF and the media (movie or sound file).  The media, and the player, are essentially isolated from Acrobat so there is no security conflict.   The RichMedia annotation blows the doors open on data transfer in two ways. 

   First, markup annotations can be applied to individual frames and states of a flash, so it can easily be used for comment and review, which is not true for the old screen annot.  Second, and more important to us scripters, Acrobat JavaScript can talk to ActionScript inside the flash.  This really opens up the possibilities for interactivity on a PDF.  For example, a RichMedia annot could display a graph that’s updated as data is entered into a PDF form.  Or the RichMedia annot could display some kind of novel form field type, like a slider, a tree list, or a state tax field that automatically updated itself from a web service.  The user would never know that it was flash instead of a PDF form field. 

    Of course, there needs to be some kind of script on the PDF to support this interaction between JavaScript and ActionScript.  But this is taken care of as well.  The flash in the RichMedia annot can write scripts into the PDF.  So flash can set itself up. There really are endless possibilities.  But, I bet you’re wondering about security.  I did when I first heard about this.  I thought, this is great, but can’t Flash and Flex do things that are no-nos in the Acrobat security model?  Well yes it can, but the player is not the external Flash player your browser uses. Its a Flash player that’s built into Acrobat, and that player is specially built to play nice with Acrobat.  In fact, there are certain ActionScript classes that are completely missing from the Flash player in Acrobat, like anything that has to do with accessing the user’s hard drive.  So, not all flash files will work in Acrobat. 

  In my opinion, I think that the RichMedia Annotation is the biggest and most important update in Acrobat 9.  It really adds to the idea of Acrobat as an applicaton platform and it’s going to change how we think about interacting with PDF. 

This entry was posted on Tuesday, June 17th, 2008 at 9:34 pm and is filed under Uncategorized. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.