Macromedia Acrobat - 6.0 User Manual
Acrobat JavaScript
bbc
Scripting Guide
Te chnical Note #5430
Ve rs io n: Acrobat 6.0
ADOBE SYSTEMS INCORPORATED
Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704
(408) 536-6000
http://partners.adobe.com
May 2003
Copyright 2003 Adobe Systems Incorporated. All rights reserved.
NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or
electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or
otherwise, without the prior written consent of the Adobe Systems Incorporated.
PostScript is a registered trademark of Adobe Systems Incorporated. All instances of the name PostScript in the text are references to the
PostScript language as defined by Adobe Systems Incorporated unless otherwise stated. The name PostScript also is used as a product
trademark for Adobe Systems’ implementation of the PostScript language interpreter.
Except as otherwise stated, any reference to a “PostScript printing device,” “PostScript display device,” or similar item refers to a printing device,
display device or item (respectively) that contains PostScript technology created or licensed by Adobe Systems Incorporated and not to devices
or items that purport to be merely compatible with the PostScript language.
Adobe, the Adobe logo, Acrobat, the Acrobat logo, Acrobat Capture, Distiller, PostScript, the PostScript logo, and Reader are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Apple, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC
is a registered trademark of IBM Corporation in the United States. ActiveX, Microsoft, Windows, and Windows NT are either registered
trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark of The Open
Group. All other trademarks are the property of their respective owners.
This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a
commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies,
makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties
of merchantability, fitness for particular purposes, and noninfringement of third party rights.
3
Contents
Contents
Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Purpose and Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
How To Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Font Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
For More Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 1 Introduction to Acrobat JavaScript . . . . . . . . . . . . . 11
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
What Is Acrobat JavaScript?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
What Can You Do with Acrobat JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . 13
Acrobat JavaScript Object Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The App object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The Doc Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Other Common Acrobat JavaScript Objects. . . . . . . . . . . . . . . . . . . . . . . 16
Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
JavaScript Language Caveats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2 Acrobat JavaScript Editor and Debugger Console . . . . . 19
Introduction to the JavaScript Editor and Debugger Console . . . . . . . . . . . . . . . . 19
Chapter Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
JavaScript Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Opening the JavaScript Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Executing JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Formatting Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using a JavaScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Specifying the Default JavaScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Acrobat JavaScript Scripting Guide
Contents
Using the Built-in Acrobat JavaScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . 24
Using an External Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Additional Editor Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Specifying Additional Capabilities to Your Editor. . . . . . . . . . . . . . . . . . . . . 25
Testing Whether Your Editor Supports Opening at Syntax Error Locations . . . . . . . 26
Exercise: Working with the JavaScript Console . . . . . . . . . . . . . . . . . . . . . . . 27
Enabling JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Enabling the Interactive JavaScript Console. . . . . . . . . . . . . . . . . . . . . . . 28
Trying out the JavaScript Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 3 Acrobat JavaScript Debugger . . . . . . . . . . . . . . . .33
Introduction to the Acrobat JavaScript Debugger . . . . . . . . . . . . . . . . . . . . . . 33
Chapter Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Enabling the Acrobat JavaScript Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 34
Debugger Dialog Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Main Groups of Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Debugger View Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Debugger Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Resume Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Step Over . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Step Into . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Step Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Debugger Scripts Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Accessing Scripts in the Scripts Window . . . . . . . . . . . . . . . . . . . . . . . . 40
Scripts Inside PDF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Scripts Outside PDF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Call Stack List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Inspect Details Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Details Window Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Inspecting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Starting the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Debugging From the Start of Execution . . . . . . . . . . . . . . . . . . . . . . . . . 46
Debugging From an Arbitrary Point in the Script. . . . . . . . . . . . . . . . . . . . . 46
Stepping Through Your Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4
Acrobat JavaScript Scripting Guide
5
Contents
Exercise: Calculator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Calculator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Debugging a runtime error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Another runtime error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Chapter 4 Using Acrobat JavaScript in Forms . . . . . . . . . . . . .55
Creating simple JavaScripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Creating an automatic date field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Performing Arithmetic Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Assigning a ‘go to page’ action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Sending a document or form via e-mail . . . . . . . . . . . . . . . . . . . . . . . . . 58
Hiding a field until a condition is met. . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Working with JavaScript actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Working with document level JavaScript actions. . . . . . . . . . . . . . . . . . . . . . . 61
Creating form fields programmatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Check Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Combo Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
List Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Radio Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Appendix A A Short Acrobat JavaScript FAQ . . . . . . . . . . . . . . 75
Where can JavaScripts be found and how are they used? . . . . . . . . . . . . . . . . . 75
Folder Level JavaScripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Document level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Field level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
How should I name my form fields? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
How do I use date objects? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Converting from a Date to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Converting from a string to a date . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Date arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
How can I make my document secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Restricting Access to the Document. . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Acrobat JavaScript Scripting Guide
Contents
Restricting Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
How can I make restricted Acrobat JavaScript methods available to users? . . . . . . . . 82
How can I lock a document after a signature field has been signed? . . . . . . . . . . . . 82
How can I make my documents accessible?. . . . . . . . . . . . . . . . . . . . . . . . . 83
Document Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Short Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Setting Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Reading Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
How can I define globals in JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Making Globals Persistent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
How can I send form data to an e-mail address? . . . . . . . . . . . . . . . . . . . . . . 85
How can I hide a field based on the value of another?. . . . . . . . . . . . . . . . . . . . 85
How can I query a field value in another open form from the form I'm working on? . . . . . 85
How can I intercept keystrokes one by one as they occur? . . . . . . . . . . . . . . . . . 86
How can I build a nested popup menu? . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
How can I construct my own colors?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
How can I prompt the user for a response in a dialog? . . . . . . . . . . . . . . . . . . . 87
How can I fetch an URL from JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . 87
How can I change the hot-help text for a field dynamically? . . . . . . . . . . . . . . . . . 87
How can I change the zoom factor programmatically?. . . . . . . . . . . . . . . . . . . . 87
How can I determine if the mouse has entered/left a certain area? . . . . . . . . . . . . . 88
6
Acrobat JavaScript Scripting Guide
Introduction
Welcome to the Adobe Acrobat JavaScript Scripting Guide . This scripting guide is designed
to give you an overview of how you can use the Acobe Acrobat 6 Pro JavaScript
development environment to develop and enhance Acrobat applications.
The JavaScript language was developed by Netscape Communications so you could more
easily create interactive Web pages. Adobe has enhanced JavaScript so you can easily
integrate this level of interactivity into your PDF forms. The most common uses for JavaScript in Acrobat forms are formatting data, calculating data, validating data, and assigning
an action.
While there are plug-in, document, and field level JavaScripts, we are concerned only with
document level and field level scripts here.
Preface
●
For information on plug-in level scripts, see “Working with JavaScript actions” on
page 60.
●
Document level scripts are executed with the document open and apply only to this
document.
Field level scripts are associated with a specific form field or fields. This type of script is
●
executed when an event occurs, such as a Mouse Up action.
Audience
The intended audience of this guide includes you if you are an Acrobat solution provider or
power user of Acrobat. You are interested in developing solutions that leverage Adobe
products. You are resourceful and accustomed to learning new technologies quickly, and
with minimal hand holding, if you have access to the necessary knowledge resources. This
guide is one of those resources.
Purpose and Scope
The objectives of this guide include:
●
Introducing you to the Adobe Acrobat JavaScript functionality that supports developing
and deploying Acrobat solutions.
Providing you with easily understood, detailed information about Acrobat JavaScript
●
scripting features and use.
Providing you with references to other resources where you can learn more about
●
Acrobat JavaScript and related technologies.
Acrobat JavaScript Scripting Guide
7
Preface
How To Use This Guide
After reading this guide and completing the exercises, you should be equipped to start
using Acrobat JavaScript. During the development process, you’ll likely find yourself
reviewing the content of this guide, as well as exploring additional, more in-depth
information that updates to this guide offer in key technical areas.
Assumptions
This guide assumes that you are familiar with the non-scripting elements of the Acrobat 6
user interface that are described in Acrobat’s accompanying online help documentation.
This guide provides some review but focuses primarily on the user interface elements for
writing JavaScript code. You should, in addition, be familiar with the basics of the standard
JavaScript scripting language. To work through the exercises in this guide, you must have
access to Acrobat 6 Pro.
Organization
This guide is divided into the following chapters and appendix:
3.
2.
1.
●
Chapter 1, “Introduction to Acrobat JavaScript”
Chapter 2, “Acrobat JavaScript Editor and Debugger Console”
●
●
Chapter 3, “Acrobat JavaScript Debugger”
Chapter 4, “Using Acrobat JavaScript in Forms
●
Appendix A, “A Short Acrobat JavaScript FAQ”
●
How To Use This Guide
Chapters 2 and 3 in this guide include one or more exercises that give you an opportunity
to work directly with Acrobat JavaScript. If you plan to do any of the exercises, do the
following:
Be sure that you have Acrobat Pro installed on your Windows or Macintosh workstation.
The exercises are designed to work on Windows and Macintosh versions of Acrobat,
unless otherwise noted.
Create a JavaScript exercises directory on your local hard drive. You will use this
directory to store the PDF documents and other files used in the exercises.
At the beginning of the Debugger chapter, a .zip file is identified that contains the
files you need to work through the exercises in that chapter. You should extract the
contents of these files to your local directory.
OTE
N
:
Note: Macintosh users need to have the StuffIt Expander application to extract the
.zip file contents.
8
Acrobat JavaScript Scripting Guide
9
Font Conventions Used in This Book
The Acrobat documentation uses text styles according to the following conventions.
Font Used for Examples
Font Conventions Used in This Book
Preface
monospaced Paths and filenames
Code examples set off
from plain text
monospaced bold Code items within plain
text
Parameter names and
literal values in
reference documents
monospaced italic Pseudocode
Placeholders in code
examples
blue Live links to Web pages The Acrobat Solutions Network URL is:
Live links to sections
within this document
Live links to other
Acrobat SDK documents
C:\templates\mytmpl.fm
These are variable declarations:
AVMenu commandMenu,helpMenu;
The GetExtensionID method ...
The enumeration terminates if proc returns
false .
ACCB1 void ACCB2 ExeProc(void)
{ do something }
AFSimple_Calculate( cFunction ,
cFields )
h
ttp://partners/adobe.com/asn/
See Using the SDK.
See the Acrobat Core API Overview .
bold PostScript language and
italic Document titles that are
Acrobat JavaScript Scripting Guide
Live links to code items
within this and other
Acrobat SDK documents
PDF operators,
keywords, dictionary
key names
User interface names The File menu
not live links
New terms
PostScript variables
Test whether an ASAtom exists.
The setpagedevice operator
Acrobat Core API Overview
User space specifies coordinates for...
filename deletefile
Preface
For More Information
For More Information
This guide refers to the following sources for additional information about Acrobat
JavaScript and related technologies:
●
Acrobat® JavaScript Scripting Reference
This document is the companion reference to this scripting guide. It provides detailed
descriptions of all the Acrobat JavaScript objects.
Adobe® Acrobat® Help
●
This online document is included with the Acrobat 6 application.
JavaScript reference material available on the Netscape D
●
(h
ttp://devedge.netscape.com/)
eveloper Web site
This documentation consists of:
– Core JavaScript Guide
– Core JavaScript Reference
Acrobat eForms Solution Training
●
(h
ttp://partners.adobe.com)
●
Acrobat Review and Markup Training
(h
ttp://partners.adobe.com)
Portable Document Format (PDF) Reference, Version 1.4
●
In this document, references to Acrobat SDK documents that appear online (in blue, italics)
are live links. However, to activate these links, you must install the documents on your local
file system in the same directory structure in which they appear in the SDK. This happens
automatically when you install the SDK. If, for some reason, you did not install the entire
SDK and you do not have all the documents, please visit Adobe Solutions Network Web site
to find the documents you need. Then install them in the appropriate directories. You can
use the Acrobat SDK Documentation Roadmap located at the beginning of this document
as a guide.
10
Acrobat JavaScript Scripting Guide
1
Introduction
This chapter introduces Adobe Acrobat JavaScript. The JavaScript development
environment for Acrobat 6, which includes new debugging capabilities, is only supported
on the Acrobat Pro “flavor” of Acrobat 6.
This guide shows a variety of ways that you can use Acrobat JavaScript to implement
solutions to your customer or company’s needs. For further information and examples, see
the Web sites and other resources listed in For More Information on page 10.
Chapter Goals
Introduction to Acrobat JavaScript
At the end of this chapter, you will be able to:
● Describe the difference between Acrobat JavaScript and standard, or HTML JavaScript.
● List what you can do with Acrobat JavaScript.
● Describe the Doc Object containment hierarchy and briefly state for what purpose the
Contents
Overview
App, Doc, Console, Global, Util, Connection, and Statement objects are used.
Topics
Overview
What Is Acrobat JavaScript?
What Can You Do with Acrobat JavaScript?
Acrobat JavaScript Object Overview
Most people know Adobe Acrobat as a medium for exchanging and viewing electronic
documents easily and reliably, independent of the environment in which they were
created. However, Acrobat provides far more capabilities than a simple document viewer.
You can enhance an Adobe Portable Document Format (PDF) document so that it contains
fields to capture user-entered data as well as buttons to initiate user actions. This type of
Acrobat JavaScript Scripting Guide
11
Introduction to Acrobat JavaScript
1
What Is Acrobat JavaScript?
PDF document is referred to as an eForm. eForms are integral to an automated paper
document processing solution for a company. In this scenario, eForms can replace existing
paper forms, allowing employees within a company to fill out forms and submit them via
PDF files.
Acrobat also contains functionality to support online team review. Documents that are
ready for review are converted to Adobe PDF. When a reviewer views an Adobe PDF
document in Acrobat and adds comments to it, those comments (or annotations)
constitute an additional layer of information on top of the base document. Acrobat
supports a wide variety of standard comment types, such as a note, graphic, sound, or
movie. To share comments on a document with others, such as the author and other
reviewers, a reviewer can export just the comment "layer" to a separate comment
repository.
In either of these scenarios, as well as others that are not mentioned here, you can
customize the behavior of a particular PDF document, implement additional functionality
beyond what Acrobat provides, and alter the appearance of a PDF document by using
Acrobat JavaScript. You can tie Acrobat JavaScript code to a specific PDF document, a
particular page within a PDF document, or a field or button on a PDF file. When an end user
interacts with Acrobat or a PDF file displayed in Acrobat that contains JavaScript, Acrobat
monitors the interaction and executes the appropriate JavaScript code.
Not only can you customize the behavior of PDF documents in Acrobat, but you can
customize the Acrobat application. In earlier versions of Acrobat (prior to Acrobat 5), this
type of customization could only be done by writing Acrobat plug-ins in a high-level
languge like C or C++ language. Now, much of that same functionality is available through
Acrobat JavaScript extensions. You will find that writing a JavaScript script to perform a task
such as adding a menu to Acrobat’s user interface much easier to do than writing a plug-in.
What Is Acrobat JavaScript?
Acrobat JavaScript is based on the core of JavaScript version 1.5 of ISO-16262, formerly
known as ECMAScript. JavaScript is an object-oriented scripting language developed by
Netscape Communications. It was created to offload Web page processing from a server
onto a client in Web-based applications. Acrobat JavaScript implements extensions, in the
form of new objects and their accompanying methods and properties, to the JavaScript
programming language. These Acrobat-specific objects enable a developer to manipulate
a PDF file, allowing the PDF file to communicate with a database, modify its appearance,
and so on. Because the Acrobat-specific objects are added on top of core JavaScript, you
still have access to standard classes like Math, String, Date, Array, and RegExp.
PDF documents have great versatility since they can be displayed in a Web browser via an
Acrobat plug-in. In this situation, you need to be aware that there are differences between
Acrobat JavaScript and JavaScript used in a Web browser, also known as HTML JavaScript.
● Acrobat JavaScript does not have access to objects within an HTML page. Similarly,
HTML JavaScript cannot access objects within a PDF file.
12 Acrobat JavaScript Scripting Guide
● HTML JavaScript is able to manipulate objects such as Window. Acrobat JavaScript
cannot access this particular object but it can manipulate PDF-specific objects such as
Doc and annot.
What Can You Do with Acrobat JavaScript?
Acrobat JavaScript enables you to do a wide variety of things within a PDF document. The
Adobe Solutions Network (ASN) has an Adobe Acrobat JavaScript Training course that
covers a wide variety of the possibilities available within Acrobat JavaScript. This course
material is in a PDF file available at:
http://partners.adobe.com/asn/developer/training/acrobat/javascript/main.html
The ASN course includes:
● Performing calculations
You can create fields on a PDF document that collect numeric data. Like a spreadsheet,
you can specify calculations that can be performed on several field values to yield a
desired result. See the ASN JavaScript training module on “JavaScript Basics” for more
information.
Introduction to Acrobat JavaScript
What Can You Do with Acrobat JavaScript?
1
● Responding to user actions
When a user interacts with a PDF document, mouse clicks, text entry, entering or exiting
fields are all possible actions that can occur. You can tie JavaScript code, or scripts, to a
particular action or event. Acrobat detects when the action occurs and calls the
associated script. See the ASN JavaScript training module on “JavaScript Basics” and the
ASN JavaScript training module on “Location Matters” for more information.
● Validating user data
You can check whether or not the data entered by the user on an eForm is valid. You can
check whether a given date is legitimate for the application, whether a particular value
makes sense given other information the user has provided on the form, and so on. See
“Performing Validations and Calculations” in the ASN JavaScript training module on
“J avaScript Basics” for more information.
● Modifying the Acrobat application
Acrobat gives you the ability to alter its menus and tool bars. Use JavaScript to add
custom menu items, hide or display tool bars and menus. See the ASN JavaScript
training module on “Location Matters” for details.
● Controlling the behavior of the document
You can control what happens when a document first opens by using document-level
scripts. Document-level scripts can cause changes that are visible to the user, such as
setting up viewing parameters for a PDF. They are also used to initialize functions and
variables used by page-level and field-level scripts. You can also associate scripts with
actions such as a page opening or closing. See the ASN JavaScript training module on
“Location Matters” for details.
Acrobat JavaScript Scripting Guide 13
Introduction to Acrobat JavaScript
1
What Can You Do with Acrobat JavaScript?
● Dynamically modifying a document’s appearance and function
One major advantage of electronic form documents is the ability to dynamically alter
their appearance in response to a user’s data entry. For example, you could alter allowed
per diem amounts on an expense report if an employee’s business trip is chargeable to a
client versus an internal project. Examples of such changes include:
–Modifying field properties, such as hidden, read-only, required, and don’t print
–Populating list boxes and combo boxes with different choices
– Altering actions associated with fields and buttons, such as adding new JavaScripts
–Dynamically creating fields
–Generating annotations
See the ASN JavaScript training module on “Creating Fields with JavaScript,” for
additional information.
● Processing multiple PDF files using batch sequences
Using a batch sequence, you can execute JavaScript on a set of PDF files. You can use
batch sequences to do a variety of different tasks such as extract comments, identify
spelling errors, automatically print PDF files, and so on. You can specify the set of files on
which to operate either when you define the batch sequence or just prior to running the
sequence. See the ASN JavaScript training module on “Batch Processing with
Sequences,” for details.
● Dynamically creating a new page based on an Acrobat page template
Based on user input or action, you can use JavaScript to create or spawn a new page
based on a template. A template is a blueprint for a page that can be added dynamically
to an existing PDF document. See the ASN JavaScript training module on “Templates
and JavaScript,” for details.
● Overlaying templates on top of a page to change its appearance
If a form has many fields and buttons that need to be displayed or hidden, you can
better control these page elements by placing them into a separate template. A
template is a blueprint for variable information, such as text, fields, buttons, and so on,
that can be dynamically overlaid on a PDF document. To change a PDF document’s
appearance, use JavaScript to overlay the page elements contained in the template on
top of the specified page. See the ASN JavaScript training module on “Templates and
JavaScript,” for details.
● Interfacing to a database
Acrobat JavaScript provides objects to specifically interact with a database via ADBC,
Acrobat’s specific implementation of ODBC. Using JavaScript, you can read values from a
database, update or insert new data, and delete information. See the ASN JavaScript
training module on “Integrating with a Database,” for details.
● Setting the comment repository preference
If you plan on using Adobe Acrobat’s collaborative review capabilities, you need to
specify the type of comment repository to use, as well as its location. These are referred
to as comment repository preferences. You can use JavaScript calls to set the comment
repository for a particular document or for all documents you review in Acrobat. See the
14 Acrobat JavaScript Scripting Guide
ASN JavaScript training module on “Setting up a Comment Repository,” for more
information.
Acrobat JavaScript Object Overview
Acrobat JavaScript defines several objects that allow your code to interact with the Acrobat
application, a PDF document, or fields and buttons on a PDF document. This section
introduces you to some of the more commonly used objects.
The App object
The App object is a static object that represents the Acrobat application itself. It defines a
number of Acrobat specific functions plus a variety of utility routines and convenience
functions. By interacting with the App object, you can get to all of the currently open PDF
documents and customize Acrobat by adding menus and menu items. You can also query
App to determine which type of Adobe product (for example, Reader, Approval, or full
Acrobat) and which version the end user is using.
Introduction to Acrobat JavaScript
Acrobat JavaScript Object Overview
1
The Doc Object
Since the primary focus of an Acrobat application is the PDF document, you can use the
Doc Object to manipulate an actual PDF document. The Doc Object provides the interfaces
between a PDF document open in the viewer and the JavaScript interpreter. By interacting
with the Doc Object, you can get general information about the document, move around
within the document, and access other objects within a document. Many of the objects
represent items found within a PDF document, such as bookmarks, fields, templates,
annotations, and sounds.
NOTE: Those of you who are familiar with the HTML JavaScript object hierarchy will
remember that it is a containment hierarchy, not an inheritance hierarchy. Acrobat
JavaScript is no different. No object inherits properties or methods of an object
higher up the chain. Likewise, there is no automatic message passing from object to
object in any direction.
Acrobat JavaScript Scripting Guide 15
Introduction to Acrobat JavaScript
1
Acrobat JavaScript Object Overview
FIGURE 1.1 Doc Object Containment Hierarchy
doc
annot
bookmark
field sound
template
Figure 1.1 represents the containment hierarchy of objects related to the Doc Object.
Accessing the Doc Object from JavaScript can be done in a variety of ways. The most
common method is using the this object, which usually points to the Doc Object of the
current underlying document.
Other Common Acrobat JavaScript Objects
Several objects exist independently of the PDF document. In addition to App, some objects,
such as Console, Global and Util, provide assistance to the programmer.
Console
The Console object is a static object to access the JavaScript console for displaying debug
messages and executing JavaScript. It does not function in the Adobe Reader or Acrobat
Standard. Use the Console object as a debugging aid and as a means of interactively
testing code.
data
Dbg
You can use the Dbg object, available only in Acrobat Pro, to optionally control the
JavaScript debugger from a command line console. The Dbg object methods produce the
same basic functionality as the buttons in the JavaScript debugger dialog toolbar. In
addition, you can use the Dbg object to set, delete, and inspect breakpoints.
Global
Use the Global object to store data that is persistent, or permanent, across invocations of
Acrobat. Global is also used to store information that pertains to a group of documents, a
situation that occurs when a batch sequence runs. For example, batch sequence code often
stores the total number of documents to process as a property of Global. If information
about the documents needs to be stored in a Report object, that object is assigned is
assigned to a property of Global so it is accessible. For more on using the Global object,
16 Acrobat JavaScript Scripting Guide
see the ASN JavaScript training module on “Location Matters” and the ASN JavaScript
training module on “Batch Processing with Sequences.”
Util
The Util object is a static JavaScript object that defines a number of utility methods and
convenience functions for string and date formatting and parsing.
Database Objects
You can interface to a database by using the ADBC, Connection, and Statement objects.
These Acrobat-specific JavaScript objects constitute Acrobat Database Connectivity (ADBC)
and utilize ODBC calls to establish a connection to a database and access its data. As a
developer, you can use SQL statements to insert, update, retrieve, and delete data. You
simply pass the SQL statement to the Statement object’s execute() method. These
objects are discussed in detail in the ASN JavaScript training module on “Integrating with a
Database.”
Introduction to Acrobat JavaScript
Acrobat JavaScript Object Overview
1
JavaScript Language Caveats
One issue that comes up often with beginning JavaScript programmers deserves to be
mentioned explicitly. It comes from the combination of two features of the JavaScript
language. First, JavaScript is a case-sensitive language, which means that “fillColor” and
“fillcolor” are two separate properties. Second, JavaScript creates local properties of
objects you are working with “on demand”, simply by your assigning a value to the new
property name. The combination of these features can create programming bugs that are
difficult to discover. If you assign a value to a property, but do not have the case correct in
the property name, you will simply create a new property without affecting the value you
thought you were changing.
Acrobat JavaScript Scripting Guide 17
Introduction to Acrobat JavaScript
1
Acrobat JavaScript Object Overview
18 Acrobat JavaScript Scripting Guide
Acrobat JavaScript Editor and
2
Debugger Console
Introduction to the JavaScript Editor and Debugger Console
Acrobat provides a development environment in which you can implement and test
Acrobat JavaScript functionality. On both Windows and Macintosh systems, you have a
choice of using Acrobat’s built-in editor or a third-party editor to develop your code. To
introduce you to a simple method of evaluating short scripts, this chapter details how you
can use Acrobat’s JavaScript debugger console with the built-in JavaScript editor to
evaluate scripts.
Chapter 3, “Acrobat JavaScript Debugger,” will introduce the full feature set of Acrobat’s
debugger, which enables you to perform more sophisticated debugging tasks such as
setting breakpoints, inspecting variables, and stepping through code—to name a few.
Chapter Goals
At the end of this chapter, you will be able to:
Contents
● Specify the type of editor you use to write your code.
● Identify the extra capabilities that Acrobat supports on some external editors.
● Invoke the JavaScript console and use it to interactively execute code and display print
statements.
Topics Exercises
JavaScript Console Exercise: Working with the JavaScript
Console
Using a JavaScript Editor
Specifying the Default JavaScript Editor
Using the Built-in Acrobat JavaScript
Editor
Using an External Editor
Acrobat JavaScript Scripting Guide 19
Acrobat JavaScript Editor and Debugger Console
2
JavaScript Console
JavaScript Console
The Acrobat JavaScript console provides an interface for testing and debugging your
JavaScript code. It is editable and interactive. The console is also handy for experimenting
with object properties and methods before you use them in your code. You can use the
console as an editor and interactively execute lines or blocks of code within the console.
You can use the Console object to manipulate the JavaScript console from within your
code. Console is a static object. Consequently, you do not need to instantiate it to use it.
Use Console’s println() method in your scripts to print debugging information. Other
methods are available to show, hide, and clear the console.
Opening the JavaScript Console
To open the Acrobat JavaScript console from within the Acrobat application:
1. Open the debugger window using one of these methods:
–Select the Advanced > JavaScript > Debugger menu command (Windows and
Macintosh) or
–Typing Ctrl-j (Windows) or
–Typing Control-j (Macintosh)
2. Select Console or Script and Console from the debugger View window.
To open the console programmatically, use console.show().
Executing JavaScript
One way of testing your JavaScript code as you develop it is to evaluate it in the JavaScript
console. There are two basic ways of evaluating JavaScript code in the console:
● To evaluate a line of code, position the cursor on the line you want evaluated and press
the Enter key on the numeric keypad (or type Ctrl+Return on the regular keyboard) to
obtain the results.
● To evaluate a block of code, type in the code, highlight it, and press Enter on the
numeric keypad (or type Ctrl+Return on the regular keyboard).
Any immediate results of evaluating the code are printed to the console. Be aware that
when evaluating a block of code, Acrobat only automatically prints to the console the result
from the last JavaScript expression in the block.
Formatting Code
You can format code in the JavaScript console using the Tab key.
● To insert fours spaces at the insertion point, press the Tab key.
20 Acrobat JavaScript Scripting Guide
● To move the cursor four spaces to the left, press Shift+Tab. (This moves the cursor to the
beginning of the line if it is fewer than four spaces from the left.)
● To move a whole line or block of code to the right four spaces, highlight the code, or a
portion of a line, then press Tab.
● To move a whole line or block of code to the left four spaces (or as far left as possible
when that is less than four spaces), highlight the code, or a portion of a line, then press
Shift+Tab.
Using a JavaScript Editor
To define or edit JavaScript associated with a specific event for an object, you typically use a
context-specific JavaScript editor, rather than the JavaScript console. The general
procedure for accessing the editor is as follows:
1. Select the object (such as a field, link, bookmark, or page) with which you want to
associate an action defined in JavaScript code.
Acrobat JavaScript Editor and Debugger Console
Using a JavaScript Editor
2
2. Open the properties dialog box for that object. An example is shown in Figure 2.1.
FIGURE 2.1 Page Properties
3. Select a particular trigger (for example, Mouse Up or Page Open) that will execute the
JavaScript action.
4. Select Run a JavaScript from the Select Action drop-down list.
Acrobat JavaScript Scripting Guide 21
Acrobat JavaScript Editor and Debugger Console
2
Using a JavaScript Editor
5. Click Add to open the JavaScript editor.
6. In the editor window, write the JavaScript script that you want to run when the user
opens the page.
7. When you are done, click Close to close the editor.
If there are errors in your code, the JavaScript editor will highlight the code line in
question and display an error message, as shown in Figure 2.2.
FIGURE 2.2 Error detected by the JavaScript editor
In Figure 2.2, the quotation mark to the right of the string is missing.
Key Notes
You can open the JavaScript editor to associate a JavaScript action with an object at
various locations (or “levels”) in a PDF document. For example, you can associate a script
at the location of a particular field in a form or at the document level, in which case the
script is available from all other scriptable locations within the document. Access to the
editor depends on where you want the script to take effect.
For details on accessing and using the JavaScript editor at different locations within a PDF
document and at the application level, see the ASN JavaScript training module on
“Location Matters.”
22 Acrobat JavaScript Scripting Guide
Acrobat JavaScript Editor and Debugger Console
Specifying the Default JavaScript Editor
You can choose to either use the built-in JavaScript editor that comes with Acrobat, or an
external JavaScript editor of your choice. To set the default JavaScript editor that you want
to use:
1. Choose Edit > Preferences to open the Preferences dialog box.
2. Select JavaScript from the list of options on the left side of the dialog box.
This brings up the Preferences dialog shown in Figure 2.3.
3. In the JavaScript Editor section, select the editor you want to use.
FIGURE 2.3 Selecting the Editor in Preferences
Specifying the Default JavaScript Editor
2
The Acrobat JavaScript Editor option sets the built-in Acrobat JavaScript editor as the
default.
The External JavaScript Editor option sets an external editor as the default. If you wish
to use and external editor,type or paste the path to the editor in the text box, or click
Browse... to navigate to your prefered JavaScript editor application.
NOTE: When you specify some external editors by browsing, Acrobat adds command
options to the editor command. For details, see “Additional Editor Capabilities” on
page 24.
Acrobat JavaScript Scripting Guide 23
Acrobat JavaScript Editor and Debugger Console
2
Using the Built-in Acrobat JavaScript Editor
4. Click OK to close the Preferences dialog box.
Using the Built-in Acrobat JavaScript Editor
You can use the built-in Acrobat JavaScript editor to evaluate JavaScript code, just as you
use the Acrobat JavaScript console. Simply select a line or block of code to evaluate, and
press the Enter key on the numeric keypad or Ctrl+Return on the regular keyboard.
The editor behaves the same way as the debugger console except that the results of
evaluating code in the console are output to the console window, rather than to the editor.
This is so that code that you enter in the editor does not become mixed up with printed
evaluation results.
You format code in the built-in JavaScript editor in the same way that you do in the console
window. For details, see “Formatting Code” on page 20.
Using an External Editor
When you specify an external editor program as the default for editing JavaScripts in
Acrobat, that program is used any time a JavaScript has to be edited from inside Acrobat.
Acrobat generates a temporary file and opens it in the external editor program. When you
are editing a file in an external editor, you must save the file for Acrobat to see your
changes. In addition, Acrobat is inaccessible to you while you are editing the file in the
external editor program. You cannot evaluate Acrobat JavaScript code from inside an
external editor. Close the external JavaScript editor to regain access to Acrobat.
Additional Editor Capabilities
Acrobat is able to support additional editor capabilities of Windows-based editors if those
capabilities can be specified on the command line. Two parameters are available to support
command line syntax: the file name (%f ) and the target line number (%n). Parameters for
Macintosh-based editors are not supported.
One important editor capability is the launching of a new instance of the editor each time
you start a new editing session. By default, many editors load new files into the same editor
instance if one is already running. In such a case, opening a new session closes the existing
one. Since Acrobat does not have access to your changes in the file until you have saved it
in the temporary locaton, the result is that unsaved changes in your session are lost. To
prevent this from occurring, you must either remember to close the editor application
before starting a new editing session or you must instruct the editor to always launch a new
editor instance.
If you can set an internal preference in your editor to always launch a new instance of the
editor, do so. If you editor requires a command line parameter to instruct it to invoke a new
editor instance, you may add that parameter to the editor command line specified in the
24 Acrobat JavaScript Scripting Guide
Acrobat JavaScript Editor and Debugger Console
Edit > Preferences > JavaScript dialog. This ensures that your editing work is not
discarded.
If your editor accepts a starting line number on the command line, Acrobat also supports
the option of starting the editor on a line that contains a syntax error by making the line
number available as a parameter (%n) to insert in the command line.
Acrobat has pre-defined, command-line templates for many current external editors. The
external editor settings are defined in Edit > Preferences > JavaScript. If you use the
Browse button to specify an external editor and it has a pre-defined command line
template, that template will be sustituted in the command line field. You may edit the
command line options at this point if you wish. If your editor does not have a pre-defined
template, you may need to specify the appropriate command-line parameters in the
command-line field.
Specifying Additional Capabilities to Your Editor
Acrobat provides internal support for both of the commands described above on a few
editors such as CodeWrite, Emacs, and SlickEdit.
Using an External Editor
2
If your editor is not one that Acrobat currently supports, go to the Web site for your editor
and look up the editor documentation, or use the documentation provided with your
editor. To determine your editor’s capability, you need answers to the following questions:
● What are the command switches to tell the editor to always open a new instance?
Switches vary depending on the editor and include /NI and +new followed by the file
name, which is represented as %f and which should be enclosed in double quotes to
ensure that spaces in file and folder names are properly handled.
● Is there a way to instruct the editor to open a file and jump to a line number?
Some example line number command switches include -#, -L, +, and -l each followed
by the line number, which is represented as %n.
Because the value of %n may be null if there is no line number to jump to, Acrobat
supports having that portion of the command be optional, only inserted if there is a line
number to jump to. Any command switches or parameters enclosed in square brackets
([...]) will only be inserted if the line number parameter is to be used. Thus, unless your
editor supports a null line number in a useful way, you should enclose the line number
switch and the %n parameter in square brackets.
If you need to insert %, [, or ] literally in your command line, you can use %%, %[, or %]
respectively.
For instance, Acrobat recognizes the Visual SlickEdit editor as vs.exe and will substitute
the command line:
"C:\ProgramFiles\vslick\win\vs.exe""%f"+new[-#%n]
This is what you will see in the Edit > Preferences > JavaScript dialog after you click Open
in the Browse dialog. The program must be installed and must be found using the Browse
dialog for Acrobat to properly recognize it and substitute the template.
Acrobat JavaScript Scripting Guide 25
Acrobat JavaScript Editor and Debugger Console
2
Using an External Editor
When Acrobat needs to open the JavaScript editor, it makes the appropriate substitutions
in the command line and executes it with the operating sytem shell. In the above case, if
the syntax error were on line 43, the command line generated would be something like:
"C:\Program Files\vslick\win\vs.exe" "C:\Temp\jsedit.js" +new -#43
TABLE 2.1 Editors supported as External JavaScript editor with command line templates.
Editor Web site
Te mplate Command Line
Arguments
Boxer http://www.boxersoftware.com
ConTEXT http://fixedsys.com/context
CodeWright http://www.codewright.com
Emacs http://www.gnusoftware.com/Emacs
Epsilon http://www.lugaru.com
Multi-Edit http://www.multiedit.com
TextPadhttp://www.textpad.com
UltraEdit http://www.ultraedit.com
VEDIT http://www.vedit.com
Visual
http://www.slickedit.com
-G -2 "%f" [-L%n]
"%f" [/g1:%n]
-M -N -NOSPLASH "%f" [-G%n]
[+%n] "%f"
[+%n] "%f"
/NI /NS /NV [/L%n] "%f"
-m -q "%f"
"%f" [-l%n]
-s2 "%f" [-l %n]
+new "%f" [-#%n]
SlickEdit
Testing Whether Your Editor Supports Opening at Syntax Error Locations
On a few editors such as TextPad, Acrobat does not support opening the editor on a line
number. To determine if this capability is supported,
1. Open a syntax error-free script in your editor.
2. Add a syntax error.
3. Move the cursor to a line other than the one containing the syntax error.
4. Close and save the file.
Does a dialog display prompting you to fix the syntax error?
If so, does it correctly specify the line containing the syntax error?
26 Acrobat JavaScript Scripting Guide
Acrobat JavaScript Editor and Debugger Console
Exercise: Working with the JavaScript Console
Saving and Closing a File with a Syntax Error
If you save and close a file you have been editing and it contains a syntax error (on line 123,
for example), Acrobat displays a dialog box with the following message prompting whether
you want to fix the error:
There is a JavaScript error at line 123.
Do you want to fix the error?
NOTE: If you click No, Acrobat discards your file.
Always click Yes . Acrobat will expand the path to the editor to include the line number in
the specified syntax. The editor will open and the cursor will be placed on line 123.
Exercise: Working with the JavaScript Console
To do this exercise, you must have Acrobat 6 Pro installed on your machine.
2
In this exercise you will verify that JavaScript is enabled for Acrobat and then begin working
with the Acrobat JavaScript console to edit and evaluate code.
At the end of the exercise you will be able to:
● Enable or disable Acrobat JavaScript.
● Enable or disable the JavaScript debugger.
● Open the console in the debugger.
● Evaluate code in the console window.
Enabling JavaScript
To create and use JavaScript actions in Acrobat, you must have JavaScript enabled. To verify
that JavaScript is enabled for your installation of Acrobat:
1. Launch the Acrobat application.
2. Select Edit > Preferences to open the Preferences dialog box.
3. Select JavaScript from the list of options on the left side of the dialog box.
4. Select Enable Acrobat JavaScript if it is not already selected.
5. Keep the Preferences dialog box open to enable the JavaScript debugger and the
debugger console.
Acrobat JavaScript Scripting Guide 27
Loading...