Acrobat JavaScript Scripting Guide

bcAcrobat JavaScript Scripting Guide
Technical Note #5430 Version: 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.

Contents

Contents
Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Introduction. . . . . . . Audience . . . . . . Purpose and Scope Assumptions . . . . Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 .7 .7 .8 .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 . . . . . . . The App object. . . . . . . . . . . . . . . . The Doc Object . . . . . . . . . . . . . . . Other Common Acrobat JavaScript Objects . Database Objects . . . . . . . . . . . . . . JavaScript Language Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 15 16 17 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. . . . . . . . . . Opening the JavaScript Console Executing JavaScript. . . . . . . Formatting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 20 20 20

Using a JavaScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Specifying the Default JavaScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Acrobat JavaScript Scripting Guide

3

Contents

Using the Built-in Acrobat JavaScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . 24 Using an External Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Editor Capabilities . . . . . . . . . . . . . . . . . . . . . . . Specifying Additional Capabilities to Your Editor. . . . . . . . . . . . . . Testing Whether Your Editor Supports Opening at Syntax Error Locations Exercise: Working with the JavaScript Console . Enabling JavaScript . . . . . . . . . . . . . Enabling the Interactive JavaScript Console. Trying out the JavaScript Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 24 25 26 27 27 28 28

Chapter 3

Acrobat JavaScript Debugger . . . . . . . . . . . . . . . . 33
Chapter Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Introduction to the Acrobat JavaScript Debugger . . . . . . . . . . . . . . . . . . . . . . 33

Enabling the Acrobat JavaScript Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 34 Debugger Dialog Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Main Groups of Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Debugger View Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Debugger Buttons . . . Resume Execution. Interrupt . . . . . . Quit . . . . . . . . Step Over . . . . . Step Into . . . . . . Step Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 38 38 39 39 39 39 40 40 40 41 42 42 43 44 44

Debugger Scripts Window . . . . . . . . . . Accessing Scripts in the Scripts Window Scripts Inside PDF Files . . . . . . . . . Scripts Outside PDF Files . . . . . . . . Inspect Details Window . . . Details Window Controls . Inspecting Variables . . . Watches . . . . . . . . . Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Call Stack List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

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

Contents

Exercise: Calculator . . . . . . Calculator . . . . . . . . . Getting Started. . . . . . . Debugging a runtime error . Another runtime error . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

47 48 49 50 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 Button . . . . . . . . . . . . . . Check Box . . . . . . . . . . . . Combo Box . . . . . . . . . . . List Box . . . . . . . . . . . . . Radio Button . . . . . . . . . . . Signature. . . . . . . . . . . . . Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 64 66 67 70 71 72 73

Appendix A A Short Acrobat JavaScript FAQ . . . . . . . . . . . . . . 75
Where can JavaScripts be found and how are they used? Folder Level JavaScripts . . . . . . . . . . . . . . . . Document level . . . . . . . . . . . . . . . . . . . . Field level . . . . . . . . . . . . . . . . . . . . . . . How do I use date objects? . . . . . . Converting from a Date to a String Converting from a string to a date . Date arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 75 75 76 77 77 79 79

How should I name my form fields? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

How can I make my document secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Restricting Access to the Document. . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Acrobat JavaScript Scripting Guide

5