An Introduction to JavaScript for Acrobat

    Andrew Tetlaw
    Andrew Tetlaw
    Share

    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

    How can I debug JavaScript in Acrobat?

    Debugging JavaScript in Acrobat can be done using the built-in JavaScript Debugger. To access it, go to the ‘Edit’ menu, select ‘Preferences’, then ‘JavaScript’, and finally ‘Enable Acrobat JavaScript Debugger’. This will allow you to set breakpoints, step through code, and inspect variables during the execution of your scripts. Remember to disable the debugger when you’re done to avoid performance issues.

    What is the purpose of JavaScript in Acrobat?

    JavaScript in Acrobat is used to automate routine tasks, validate form fields, calculate form field values, create complex document navigation, create complex forms or interactive documents. It can also be used to integrate PDF documents with databases or other external data sources.

    How can I apply JavaScript to my PDFs in Acrobat?

    To apply JavaScript to your PDFs in Acrobat, you need to open the ‘Tools’ pane, select ‘JavaScript’, and then ‘Document JavaScripts’. Here, you can add, edit, or delete JavaScripts. You can also set document-level scripts that apply to the entire document, or field-level scripts that apply only to specific form fields.

    Can I use JavaScript to secure my PDFs in Acrobat?

    Yes, you can use JavaScript in Acrobat to enhance the security of your PDFs. For example, you can use it to password-protect your documents, restrict printing or editing, and control access to certain features or content. However, keep in mind that JavaScript is not a substitute for proper document security measures.

    How can I learn more about JavaScript for Acrobat?

    Adobe provides extensive documentation on JavaScript for Acrobat, including a JavaScript API reference and a JavaScript developer guide. You can also find many tutorials and examples online. Remember, learning JavaScript for Acrobat requires a basic understanding of JavaScript itself, so it might be helpful to learn or brush up on JavaScript basics first.

    Is JavaScript in Acrobat the same as JavaScript in web development?

    While JavaScript in Acrobat is based on the core JavaScript language, it also includes Adobe-specific extensions and APIs that are not available in web development. Therefore, while the basic syntax and concepts are the same, there are differences in how JavaScript is used and what it can do in Acrobat compared to web development.

    Can I use JavaScript to create interactive PDFs in Acrobat?

    Yes, JavaScript is a powerful tool for creating interactive PDFs in Acrobat. You can use it to create custom form fields, validate user input, calculate values, control navigation, and much more. With JavaScript, you can turn a static PDF into a dynamic, interactive document.

    How can I test my JavaScript code in Acrobat?

    You can test your JavaScript code in Acrobat using the JavaScript Console, which is part of the JavaScript Debugger. The console allows you to run JavaScript code snippets and see the results immediately. This is a great way to test small pieces of code and troubleshoot problems.

    Can I use external JavaScript libraries in Acrobat?

    While it’s technically possible to use external JavaScript libraries in Acrobat, it’s generally not recommended. Acrobat’s JavaScript environment is different from a web browser’s, and many libraries rely on browser-specific features that are not available in Acrobat. It’s usually best to stick with the built-in Acrobat JavaScript API.

    What are some common uses of JavaScript in Acrobat?

    Some common uses of JavaScript in Acrobat include automating tasks (like batch processing multiple documents), validating form fields, calculating form field values, creating custom navigation, integrating with databases, enhancing document security, and creating interactive documents. With JavaScript, you can greatly enhance the functionality and usability of your PDFs.