Working with Events in Acrobat JavaScript

Editor’s Note: This article is part of the Introduction to Acrobat JavaScript Learning Center

There are various events made available to people writing Acrobat JavaScript to associate their code with. Without actually associating the JavaScript code you write with one of these available events in Acrobat, then it’s not going to execute. So, what are these events, and where can I find them?

What is an event?

An event is a result of a user action. For example, a user could start the Acrobat viewer (App/Init), click on a button (Mouse Up), save a PDF file (Doc/DidSave), or close a PDF file (Doc/WillClose). The list goes on. The complete list of events that you can associate Acrobat JavaScript with can be found in the Acrobat JavaScript Scripting Reference document at the Adobe website, here:

      http://partners.adobe.com/asn/acrobat/docs.jsp#javascript

A selection of the more interesting events has been listed below, along with an example situation where it would come in use.

App/Init

This is when the Acrobat/Reader viewer starts. Any files with a .js extension (this is just a text based file containing JavaScript code) located in the Acrobat JavaScripts folder (usually in ‘C:Program FilesAdobeAdobe Acrobat 6.0AcrobatJavaScripts’) will be processed, and any code contained in these files will be executed.

Example usage: Have a .js file sitting in the JavaScripts folder (as noted above) that customizes the Acrobat/Reader viewer interface. This is achieved be using the JavaScript methods hideMenuItem(), hideToolbarButton(), addMenuItem() and addToolbarButton().

Batch/Exec

This is when a batch sequence is executed in Acrobat. JavaScript can be included as one or more of any number of commands in a batch sequence.

Example usage: Create a new batch sequence that will execute the doc.addWebLinks() method across a folder of PDF documents. By using the ‘Run a JavaScript’ command in your batch sequence, and using the addWebLinks() method in your JavaScript, you can add interactive web links across a batch of PDF documents.

Doc/Open

This event is fired whenever a document is opened. You can add JavaScript to be executed on this event in Acrobat under ‘Advanced > JavaScript > Document JavaScript’.

Example usage: Add a new document level JavaScript that adds the current date to a form field when the PDF is first opened.

Doc/WillPrint

This event is fired just before the document is printed. You can associate JavaScript with this (and a number of other useful events) in Acrobat under ‘Advanced > JavaScript > Set Document Actions’.

Example usage: Your organization may have a document policy that requires a disclaimer to be displayed on printed versions of particular documents along with the date/time it was printed. You can achieve this by associating a JavaScript with the Doc/WillPrint event that fills a form field with the required values.

Restrictions on Particular Events

It’s important to know that particular Acrobat JavaScript methods and properties are restricted to being able to be associated with/executed on specific events (for security reasons).

src=’http://www.planetpdf.com/images/1-CD-LS_JS_-_Events.gif’ width=’505′ height=’146′
alt=’Security note’>

Figure 1. Security note

If such a restriction is placed on a method or property, then there will be a security note (see figure 1.0) just following the method/property description in the Acrobat JavaScript Scripting Reference document. In the above example (Figure 1), this means that the insertPages() method can only be associated to the Batch/Exec, Console/Exec or Menu/Exec events. If you attempt to run it on any other event, the operation will fail and an error message written to the console stating — ‘NotAllowedError: Security settings prevent access to this property or method.’

Examples

If you’d like to see these events in action, you can download the example PDF [PDF: 86KB] that illustrates just a few of the events available.

More Info

You May Also Like

About the Author: Chris Dahl

Leave a Reply