Developing Acrobat Applications Using JavaScript

220 Pages·2006·2.71 MB·English

by  Adobe Developer Support

bbc
Developing Acrobat Applications
®
Using JavaScript™
Adobe Acrobat SDK
® ®
November 2006 Version 8.0
© 2006 Adobe Systems Incorporated. All rights reserved.
Adobe® Acrobat® SDK 8.0 Developing Acrobat Applications Using JavaScript for Microsoft® Windows® and Mac OS®.
Edition 1.0, November 2006
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished
under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part
of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording,
or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected
under copyright law even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, 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 that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The
unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to
obtain any permission required from the copyright owner.
Any references to company names and company logos in sample material are for demonstration purposes only and are not intended to refer
to any actual organization.
Adobe, the Adobe logo, Acrobat, After Effects, FrameMaker, Illustrator, LiveCycle, Photoshop, PostScript and Reader are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Apple and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries.
JavaScript is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
All other trademarks are the property of their respective owners.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101,
consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R.
§12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable,
the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users
(a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein.
Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA
95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if
appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of
1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60,
60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Contents
Contents.......................................................................................................................................3
List of Examples.........................................................................................................................10
Preface........................................................................................................................................12
What’s in this guide?...................................................................................................................................................................12
Who should read this guide?...................................................................................................................................................12
About the sample scripts...........................................................................................................................................................12
Related documentation.............................................................................................................................................................13
1 Introduction...............................................................................................................................14
Overview..........................................................................................................................................................................................14
Reading the JavaScript for Acrobat API Reference..........................................................................................................15
Object summary...........................................................................................................................................................................16
app...............................................................................................................................................................................................16
Doc..............................................................................................................................................................................................16
dbg..............................................................................................................................................................................................17
console.......................................................................................................................................................................................17
global..........................................................................................................................................................................................17
util................................................................................................................................................................................................18
dialog..........................................................................................................................................................................................18
security.......................................................................................................................................................................................18
SOAP...........................................................................................................................................................................................18
search.........................................................................................................................................................................................18
ADBC...........................................................................................................................................................................................19
event...........................................................................................................................................................................................19
JavaScript applications...............................................................................................................................................................19
2 Tools ...........................................................................................................................................21
Using the JavaScript Debugger console..............................................................................................................................21
Opening the console............................................................................................................................................................22
Executing JavaScript.............................................................................................................................................................22
Formatting code.....................................................................................................................................................................22
Enabling JavaScript...............................................................................................................................................................22
Debugging with the JavaScript Console.......................................................................................................................24
Using a JavaScript editor...........................................................................................................................................................24
Specifying the default JavaScript editor..............................................................................................................................25
Using an external editor.............................................................................................................................................................26
Additional editor capabilities............................................................................................................................................26
Specifying additional capabilities to your editor.......................................................................................................26
Saving and closing a file with a syntax error................................................................................................................28
Using the Debugger with Adobe Reader............................................................................................................................28
Enabling the JavaScript Debugger........................................................................................................................................29
3
Adobe Acrobat SDK Contents
Developing Acrobat Applications Using JavaScript 4
2 Tools (Continued)
JavaScript Debugger...................................................................................................................................................................30
Main groups of controls.......................................................................................................................................................30
Debugger View windows....................................................................................................................................................31
Debugger buttons.................................................................................................................................................................32
Debugger Scripts window..................................................................................................................................................33
Call Stack list............................................................................................................................................................................35
Inspect details window........................................................................................................................................................35
Coding styles and breakpoints...................................................................................................................................37
Listing breakpoints.........................................................................................................................................................38
Using conditional breakpoints...................................................................................................................................38
Starting the Debugger.........................................................................................................................................................38
Final notes................................................................................................................................................................................39
3 JavaScript Contexts in Acrobat ................................................................................................40
The concept of a JavaScript event.........................................................................................................................................40
About contexts..............................................................................................................................................................................41
Folder level...............................................................................................................................................................................42
Document level......................................................................................................................................................................43
Page level..................................................................................................................................................................................43
Field level..................................................................................................................................................................................44
Batch level................................................................................................................................................................................44
Privileged versus non-privileged context...........................................................................................................................45
Executing privileged methods in a non-privileged context...................................................................................45
Executing privileged methods through the menu....................................................................................................47
Executing privileged methods in a certified document..........................................................................................48
4 Creating and Modifying PDF Documents................................................................................49
Creating and modifying PDF files...........................................................................................................................................49
Combining PDF documents...............................................................................................................................................51
Combining and extracting files.........................................................................................................................................51
Creating file attachments....................................................................................................................................................52
Cropping and rotating pages............................................................................................................................................55
Cropping pages................................................................................................................................................................55
Rotating pages..................................................................................................................................................................56
Extracting, moving, deleting, replacing, and copying pages................................................................................56
Adding watermarks and backgrounds...........................................................................................................................58
Converting PDF documents to XML format.......................................................................................................................59
5 Print Production ........................................................................................................................60
Setting print options...................................................................................................................................................................60
Printing PDF documents............................................................................................................................................................62
Silent printing..........................................................................................................................................................................63
Printing comments and forms..........................................................................................................................................64
Booklet printing......................................................................................................................................................................64
Setting advanced print options........................................................................................................................................65
Specifying output settings...........................................................................................................................................65
Specifying marks and bleeds.......................................................................................................................................65
Setting PostScript options............................................................................................................................................65
Setting font options........................................................................................................................................................65
Adobe Acrobat SDK Contents
Developing Acrobat Applications Using JavaScript 5
6 Using JavaScript in Forms.........................................................................................................67
Forms essentials............................................................................................................................................................................67
About PDF forms....................................................................................................................................................................67
Elements of Acrobat forms...........................................................................................................................................68
Guidelines for creating a new form...........................................................................................................................68
Creating Acrobat form fields..............................................................................................................................................69
Setting Acrobat form field properties............................................................................................................................70
Field properties................................................................................................................................................................71
Button fields......................................................................................................................................................................72
Check box fields...............................................................................................................................................................74
Combo box fields.............................................................................................................................................................75
List box fields.....................................................................................................................................................................79
Radio button fields..........................................................................................................................................................81
Signature fields.................................................................................................................................................................82
Text fields............................................................................................................................................................................83
Validation scripts..............................................................................................................................................................84
Calculation script.............................................................................................................................................................85
Task-based topics.........................................................................................................................................................................86
Highlighting required form fields....................................................................................................................................86
Making a form fillable...........................................................................................................................................................87
Setting the hierarchy of form fields.................................................................................................................................87
Creating forms........................................................................................................................................................................88
Positioning form fields...................................................................................................................................................88
Duplicating form fields..................................................................................................................................................89
Creating multiple form fields......................................................................................................................................90
Defining the tabbing order................................................................................................................................................91
Defining form field calculation order.............................................................................................................................91
Making PDF forms web-ready...........................................................................................................................................91
Creating a submit button.............................................................................................................................................92
Creating a reset form button.......................................................................................................................................92
Defining CGI export values..........................................................................................................................................92
Importing and exporting form data................................................................................................................................92
Emailing completed forms.................................................................................................................................................93
Use date objects.....................................................................................................................................................................93
Date arithmetic.......................................................................................................................................................................95
Defining global variables in JavaScript..........................................................................................................................96
Enable the global object security policy.................................................................................................................96
Setting and getting a global variable.......................................................................................................................96
Deleting global variables..............................................................................................................................................97
Making global variables persistent...........................................................................................................................97
Querying an Acrobat form field value in another open form..........................................................................97
Global object security policy.......................................................................................................................................98
Intercepting keystrokes in an Acrobat form.................................................................................................................98
Constructing custom colors...............................................................................................................................................99
Prompting the user for a response..................................................................................................................................99
Fetching an URL from JavaScript.....................................................................................................................................99
Creating special rollover effects.......................................................................................................................................99
Adobe Acrobat SDK Contents
Developing Acrobat Applications Using JavaScript 6
6 Using JavaScript in Forms (Continued)
Introduction to XML forms architecture (XFA)..................................................................................................................99
Enabling dynamic layout and rendering....................................................................................................................100
Growable form fields.........................................................................................................................................................100
Variable-size rows and tables.........................................................................................................................................100
Multiple customized forms within a form based on user input.........................................................................100
Handling image data.........................................................................................................................................................100
Dynamic tooltips.................................................................................................................................................................100
XFA-specific JavaScript methods..................................................................................................................................101
JavaScript methods not enabled in XML Forms......................................................................................................105
ADO support for Windows..............................................................................................................................................105
Detecting XML forms and earlier form types............................................................................................................105
Saving form data as XML or XML Data Package (XDP)..........................................................................................106
Global submit.......................................................................................................................................................................106
Making forms accessible.........................................................................................................................................................107
Text-to-speech.....................................................................................................................................................................107
Tagging annotations.........................................................................................................................................................108
Document metadata..........................................................................................................................................................109
Short description.................................................................................................................................................................109
Setting tab order.................................................................................................................................................................109
Reading order.......................................................................................................................................................................109
Using JavaScript to secure forms.........................................................................................................................................110
7 Review, Markup, and Approval..............................................................................................112
Working with comments using JavaScript.......................................................................................................................112
Annotation types................................................................................................................................................................112
Getting annotation data...................................................................................................................................................113
Adding comments with JavaScript...............................................................................................................................114
Setting comment properties..........................................................................................................................................114
Online collaboration essentials............................................................................................................................................115
Reviewing documents with additional usage rights.............................................................................................115
Emailing PDF documents.................................................................................................................................................116
JavaScript-based collaboration driver.........................................................................................................................116
Spell-checking in comments and forms.....................................................................................................................118
Setting spelling preferences.....................................................................................................................................118
Adding words to a dictionary...................................................................................................................................119
Approval.................................................................................................................................................................................119
Managing comments...............................................................................................................................................................119
Selecting, moving, and deleting comments.............................................................................................................119
Using the comments list...................................................................................................................................................120
Changing the status of comments.........................................................................................................................120
Changing the appearance of comments.............................................................................................................120
Sorting comments..............................................................................................................................................................120
Showing and hiding comments..............................................................................................................................121
Exporting and importing comments...........................................................................................................................121
Aggregating comments for use in Excel....................................................................................................................121
Comparing comments in two PDF documents.......................................................................................................121
Extracting comments in a batch process...................................................................................................................122
Adobe Acrobat SDK Contents
Developing Acrobat Applications Using JavaScript 7
7 Review, Markup, and Approval (Continued)
Approving documents using stamps (Japanese workflows)....................................................................................122
Setting up a Hanko approval workflow......................................................................................................................122
Participating in a Hanko approval workflow.............................................................................................................122
Installing and customizing Hanko stamps..........................................................................................................123
Creating custom Inkan stamps................................................................................................................................123
Deleting custom stamps............................................................................................................................................123
8 Working with Digital Media in PDF Documents....................................................................124
Media players: control, settings, renditions, and events.............................................................................................124
Accessing a list of active players....................................................................................................................................125
Specifying playback settings..........................................................................................................................................125
Monitors........................................................................................................................................................................................127
Integrating media into documents....................................................................................................................................128
Controlling multimedia through a rendition action..............................................................................................130
Controlling multimedia with a Run a JavaScript action........................................................................................131
Adding and editing renditions.......................................................................................................................................133
Setting multimedia preferences..........................................................................................................................................134
9 Modifying the User Interface..................................................................................................135
Adding toolbar buttons and menu items........................................................................................................................135
Adding navigation to PDF documents..............................................................................................................................137
Thumbnails............................................................................................................................................................................138
Creating page thumbnails.........................................................................................................................................138
Adding page actions with page thumbnails......................................................................................................138
Bookmarks.............................................................................................................................................................................139
Creating bookmarks....................................................................................................................................................139
Managing bookmarks.................................................................................................................................................140
Creating a bookmark hierarchy...............................................................................................................................140
Links.........................................................................................................................................................................................141
Adding and removing web links from text.........................................................................................................142
Adding and removing links.......................................................................................................................................142
Defining the appearance of a link..........................................................................................................................143
Opening links.................................................................................................................................................................144
Opening file attachments..........................................................................................................................................144
Using destinations........................................................................................................................................................144
Using actions for special effects....................................................................................................................................145
Highlighting form fields and navigational components......................................................................................145
Setting up a presentation................................................................................................................................................146
Defining the initial view in full screen view........................................................................................................146
Defining an initial view...............................................................................................................................................147
Numbering pages...............................................................................................................................................................149
Creating buttons.................................................................................................................................................................150
Working with PDF layers.........................................................................................................................................................150
Navigating with layers.......................................................................................................................................................151
Editing the properties of PDF layers.............................................................................................................................151
Reordering layers................................................................................................................................................................152
Adobe Acrobat SDK Contents
Developing Acrobat Applications Using JavaScript 8
10 Acrobat Templates..................................................................................................................153
The role of templates in PDF form architecture.............................................................................................................153
Spawning templates................................................................................................................................................................153
Dynamic form field generation......................................................................................................................................154
Dynamic page generation...............................................................................................................................................154
Template syntax and usage............................................................................................................................................154
11 Search and Index Essentials....................................................................................................157
Searching for text in PDF documents................................................................................................................................157
Finding words in an PDF document.............................................................................................................................158
Using advanced search options..............................................................................................................................159
Searching across multiple PDF documents...............................................................................................................159
Searching all PDF files in a specific location.......................................................................................................160
Using advanced search options for multiple document searches.............................................................160
Searching PDF index files...........................................................................................................................................160
Using Boolean queries................................................................................................................................................160
Indexing multiple PDF documents.....................................................................................................................................161
Creating, updating, or rebuilding indexes.................................................................................................................161
Searching metadata.................................................................................................................................................................162
12 Security.....................................................................................................................................163
Security essentials.....................................................................................................................................................................163
Methods for adding security to PDF documents....................................................................................................163
Passwords and restrictions........................................................................................................................................163
Certifying documents.................................................................................................................................................163
Encrypting files using certificates...........................................................................................................................165
Security policies............................................................................................................................................................166
Secure forms...................................................................................................................................................................166
Digitally signing PDF documents........................................................................................................................................166
Signing a PDF document.................................................................................................................................................166
The security handler object.............................................................................................................................................166
The SignatureInfo object...........................................................................................................................................167
Applying the signature...............................................................................................................................................167
Clearing a digital signature from a signature field...........................................................................................168
Getting signature information from another user..................................................................................................168
Removing signatures.........................................................................................................................................................168
Certifying a document......................................................................................................................................................168
Validating signatures.........................................................................................................................................................169
Setting digital signature properties with seed values...........................................................................................169
Adding security to PDF documents....................................................................................................................................170
Adding passwords and setting security options.....................................................................................................170
Adding usage rights to a document............................................................................................................................170
Encrypting PDF files for a list of recipients................................................................................................................171
Encrypting PDF files using security policies..............................................................................................................173
Adding security to document attachments..............................................................................................................175
Adobe Acrobat SDK Contents
Developing Acrobat Applications Using JavaScript 9
12 Security (Continued)
Digital IDs and certification methods................................................................................................................................175
Digital IDs...............................................................................................................................................................................176
About digital ID providers.........................................................................................................................................176
Creating a digital ID (default certificate security).............................................................................................177
Using digital IDs (default certificate security).....................................................................................................179
Managing digital IDs (Windows certificate security).......................................................................................179
Managing digital ID certificates.....................................................................................................................................180
Sharing digital ID certificates...................................................................................................................................180
Building a list of trusted identities..........................................................................................................................181
Checking information on certificates....................................................................................................................181
Task based topics......................................................................................................................................................................182
Disallowing changes in scripts.......................................................................................................................................182
Hiding scripts........................................................................................................................................................................182
13 Rights-Enabled PDF Files........................................................................................................183
Additional usage rights...........................................................................................................................................................183
LiveCycle Reader Extensions.................................................................................................................................................184
Writing JavaScript for Adobe Reader.................................................................................................................................184
Enabling collaboration............................................................................................................................................................186
14 Interacting with Databases.....................................................................................................188
About ADBC................................................................................................................................................................................188
Establishing an ADBC connection.......................................................................................................................................189
Executing SQL statements.....................................................................................................................................................191
15 SOAP and Web Services ..........................................................................................................193
Using SOAP and web services..............................................................................................................................................193
Using a WSDL proxy to invoke a web service...........................................................................................................194
Synchronous and asynchronous information exchange.....................................................................................195
Establishing a synchronous connection...............................................................................................................196
Asynchronous web service calls..............................................................................................................................198
Using document/literal encoding.................................................................................................................................199
Exchanging file attachments and binary data..........................................................................................................200
Converting between string and readstream information....................................................................................201
Accessing SOAP version information..........................................................................................................................201
Accessing SOAP header information...........................................................................................................................201
Authentication.....................................................................................................................................................................202
Error handling......................................................................................................................................................................202
DNS service discovery..............................................................................................................................................................203
Managing XML-based information.....................................................................................................................................205
Workflow applications.............................................................................................................................................................206
16 Interfacing with 3D JavaScript...............................................................................................207
Basic concepts............................................................................................................................................................................207
Getting the Annot3D object of the 3D annotation.......................................................................................................208
Annot3D properties...........................................................................................................................................................208
Acquiring the JavaScript 3D engine.............................................................................................................................209
Using the default script of a 3D annotation....................................................................................................................210
Initializing upon activation....................................................................................................................................................211
Index.........................................................................................................................................213
List of Examples
Example 2.1 Test a regular expression in the JavaScript Debugger Console.....................................................................24
Example 3.1 Executing privileged methods....................................................................................................................................46
Example 4.1 Creating a document with content...........................................................................................................................50
Example 4.2 Creating a new document from two other documents....................................................................................51
Example 4.3 Combining several PDF files........................................................................................................................................51
Example 4.4 Combining several files of different formats.........................................................................................................52
Example 4.5 Extracting and saving pages........................................................................................................................................52
Example 4.6 Saving form data to and reading form data from an attachment.................................................................53
Example 4.7 Accessing an XML attachment using E4X...............................................................................................................54
Example 5.1 Set up booklet printing for right-side binding of text and print....................................................................64
Example 5.2 Print booklet in duplex mode, printing only the front pages.........................................................................64
Example 6.1 Custom script for a combo box..................................................................................................................................78
Example 6.2 Accessing a list from another field............................................................................................................................80
Example 6.3 Accessing individual radio button widgets...........................................................................................................81
Example 6.4 Counting the number of widgets in a radio button field..................................................................................81
Example 6.5 Inputting numbers and checking the range in a text field...............................................................................84
Example 6.6 Calculating the average of several text fields........................................................................................................85
Example 6.7 Highlighting required fields.........................................................................................................................................86
Example 6.8 Inserting navigation buttons on each page..........................................................................................................89
Example 6.9 Detecting and classifying XML forms in batch...................................................................................................105
Example 8.1 Customizing the number of repetitions for playback.....................................................................................127
Example 8.2 Running openPlayer with settings and events as a rendition action........................................................130
Example 8.3 Play a clip in full screen...............................................................................................................................................131
Example 8.4 Playing a rendition in a screen annotation from a form button..................................................................132
Example 8.5 Playing a media clip from a URL..............................................................................................................................132
Example 8.6 Playing a media clip from a file................................................................................................................................133
Example 8.7 Playing a sound clip from a URL..............................................................................................................................133
Example 9.1 Adding a menu item....................................................................................................................................................135
Example 9.2 Installing and uninstalling a toolbar......................................................................................................................136
Example 9.3 Add navigation links to the document.................................................................................................................142
Example 9.4 Setting full screen preferences and resetting them.........................................................................................146
Example 9.5 Adding page transitions.............................................................................................................................................147
Example 9.6 Creating a rollover effect...........................................................................................................................................150
Example 9.7 Toggling a PDF layer....................................................................................................................................................151
Example 10.1 Gathering personal data using templates...........................................................................................................155
Example 12.1 Certification signature................................................................................................................................................170
10